id›Guides›Observability›Telemetry

Mengintegrasikan tumpukan observability Anda dengan OpenTelemetry

OpenTelemetry (opens in a new tab) (OTel) adalah kerangka kerja observability sumber terbuka yang dirancang untuk menyediakan cara yang konsisten dan dapat diandalkan untuk mengumpulkan data telemetri di seluruh sistem terdistribusi. Projek ini di bawah naungan Cloud Native Computing Foundation (CNCF) (opens in a new tab) sebagai proyek yang sedang dipanen. Tujuan dari projek ini adalah untuk menyediakan standar dan set peralatan yang terintegrasi untuk menginstrumentasi, menghasilkan, dan mengekspor data telemetri dari aplikasi modern, membuat pengawasan, debug, dan pemahaman layanan kompleks menjadi lebih mudah.

Tujuan NQRust-Identity adalah untuk mendukung OpenTelemetry Logs, Metrics, dan Traces untuk menciptakan tumpukan observability terpusat tanpa beban penyebaran tambahan.

Opsi Umum

NQRust-Identity menyediakan dukungan untuk pengaturan global ekspor data telemetri. Ini berarti Anda dapat mengonfigurasi parameter koneksi ke satu OpenTelemetry collector (opens in a new tab) yang akan digunakan untuk semua komponen yang didukung.

Untuk mengaktifkan OpenTelemetry, setidaknya satu komponen harus diaktifkan, misalnya Traces.

Fitur OpenTelemetry diaktifkan secara default. Nonaktifkan fitur ini untuk menonaktifkan komponen OpenTelemetry.

Endpoint

Anda dapat mengonfigurasi endpoint global collector OpenTelemetry yang dibagikan di semua komponen dengan menggunakan opsi telemetry-endpoint. Nilai default adalah http://localhost:4317.

Anda dapat mengganti endpoint melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --telemetry-endpoint=http://my-otel-endpoint:4317

Nama Layanan

Anda dapat mengonfigurasi nama layanan OpenTelemetry global yang digunakan untuk mengidentifikasi eksportir data telemetri. Nama layanan default adalah keycloak, ditentukan melalui properti telemetry-service-name, yang mengambilprecedence atas service.name yang didefinisikan dalam properti telemetry-resource-attributes.

Anda dapat mengganti nama layanan melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --telemetry-service-name=my-keycloak-iam

Protokol

Anda dapat mengonfigurasi protokol transportasi OpenTelemetry global yang digunakan sebagai saluran komunikasi antara NQRust-Identity dan collector OpenTelemetry. Nilai default adalah grpc.

NQRust-Identity mendukung protokol komunikasi berikut:

grpc (default)
http/protobuf

Anda dapat mengganti protokol melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --telemetry-protocol=http/protobuf

Header Permintaan

Anda dapat mengonfigurasi header permintaan khusus yang akan dikirimkan saat mengekspor data telemetri ke collector OpenTelemetry. Hal ini berguna untuk menyediakan token autentikasi atau header khusus lain yang diperlukan oleh backend telemetri Anda.

Gunakan opsi telemetry-header-<header> untuk menetapkan header untuk semua komponen telemetri (log, metrik, dan jejak).

Ganti <header> dengan nama header khusus Anda dalam nama opsi.

bin/kc.[sh|bat] start --telemetry-header-Authorization='Bearer my-token' --telemetry-header-X-Custom-Header=custom-value

Header spesifik komponen mengambil precedence atas header umum untuk komponen masing-masing.

Pengaturan melalui NQRust-Identity CR (Operator)

NQRust-Identity CR memiliki opsi konfigurasi pertama kelas untuk telemetri. Ini dapat dikonfigurasi di bawah spesifikasi telemtry sebagai berikut:

apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
metadata:
  name: example-kc
spec:
  telemetry:
    endpoint: http://my-telemetry:4317          # default 'http://localhost:4317'
    serviceName: my-best-keycloak-telemetry     # default 'keycloak'
    protocol: http/protobuf                     # default 'grpc'
    resourceAttributes:
      service.namespace: keycloak-namespace-telemetry

Bidang ini harus mencerminkan asosiasi 1:1 dengan opsi server telemetry-*.

Mengaktifkan Semua Komponen OpenTelemetry

Untuk mengaktifkan metrik, log, dan jejak OpenTelemetry, Anda dapat mengonfigurasi NQRust-Identity CR sebagai berikut:

⚠️

OpenTelemetry Logs dan Metrics adalah fitur preview/eksperimental.

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  features:
    enabled:
      - opentelemetry-logs
      - opentelemetry-metrics
  telemetry:
    endpoint: http://my-telemetry:4317
    serviceName: my-best-keycloak-telemetry
    protocol: grpc
  tracing:
    enabled: true
  additionalOptions:
    - name: telemetry-logs-enabled
      value: "true"
    - name: telemetry-metrics-enabled
      value: "true"
    - name: metrics-enabled
      value: "true"

Jejak

Lihat panduan Analisis akar masalah dengan jejak.

Anda dapat menimpa pengaturan OpenTelemetry global melalui opsi Jejak jika Anda ingin mengekspor jejak ke collector OpenTelemetry yang berbeda.

Log

Dukungan OpenTelemetry Logs adalah Preview dan belum sepenuhnya didukung. Fitur ini dimatikan secara default.

Untuk mengaktifkannya, jalankan server dengan --features=preview atau --features=opentelemetry-logs

Fitur OpenTelemetry (opentelemetry) perlu diaktifkan (secara default).

Mungkin untuk mengekspor log NQRust-Identity ke collector OpenTelemetry dan dikelola oleh berbagai backend logging yang mendukung OpenTelemetry.

Mengaktifkan Log

Anda dapat mengaktifkan OpenTelemetry Logs melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --features=opentelemetry-logs --telemetry-logs-enabled=true

Untuk informasi lebih lanjut tentang cara mengatur logging, lihat panduan Mengonfigurasi Logging.

Tipe Log

Secara default, semua tipe log diekspor oleh NQRust-Identity. Anda dapat secara opsional mengonfigurasi tipe log yang paling verbose untuk diekspor melalui opsi telemetry-logs-level.

Opsi telemetry-logs-level menyaring log mana yang diekspor ke OpenTelemetry, sementara log-level dan log-level-<category> mengontrol log mana yang dihasilkan oleh NQRust-Identity.

Filter telemetri diterapkan pada log yang sudah dihasilkan, jadi menetapkan telemetry-logs-level=DEBUG tidak akan diekspor log DEBUG jika log-level=WARN.

Sebagai contoh, jika Anda hanya ingin diekspor log WARN dan ERROR, Anda dapat mengganti level log melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --telemetry-logs-level=WARN

Header Permintaan

Seperti yang dinyatakan untuk pengaturan umum header, Anda dapat mengonfigurasi header permintaan khusus yang akan digunakan saat mengekspor log.

bin/kc.[sh|bat] start --telemetry-logs-header-Authorization='Bearer logs-token'

Metrik

⚠️

Fitur Metrik OpenTelemetry saat ini eksperimental, dan tidak disarankan untuk digunakan dalam produksi.

Untuk fitur Metrik bekerja, fitur OpenTelemetry opentelemetry tidak dapat dinonaktifkan.

Untuk mengintegrasikan Metrik OpenTelemetry, NQRust-Identity menggunakan Micrometer-to-OpenTelemetry bridge (opens in a new tab), yang menyediakan fungsionalitas untuk mengekspor metrik yang dibuat oleh Micrometer ke collector OpenTelemetry. Ini berarti bahwa semua metrik yang dibuat melalui Micrometer atau metrik OpenTelemetry akan diekspor ke OpenTelemetry.

Ada beberapa perbedaan konvensi API, dan semantik (opens in a new tab) untuk Micrometer vs OTel Metrics, jadi Anda harus memeriksa apakah semua metrik yang diperlukan telah diekspor.

Mengaktifkan Metrik

Anda dapat mengaktifkan Metrik OpenTelemetry melalui CLI sebagai berikut:

bin/kc.[sh|bat] start --features=opentelemetry-metrics --telemetry-metrics-enabled=true --metrics-enabled=true

Metrik (metrics-enabled) juga perlu diaktifkan

Untuk informasi lebih lanjut tentang cara mengatur metrik, lihat opsi konfigurasi di bawah atau kunjungi panduan Mendapatkan wawasan dengan metrik.

Header Permintaan

Seperti yang dinyatakan untuk pengaturan umum header, Anda dapat mengonfigurasi header permintaan khusus yang akan digunakan saat mengekspor metrik.

bin/kc.[sh|bat] start --telemetry-metrics-header-Authorization='Bearer metrics-token'

Pengaturan Pengembangan

Untuk tujuan pengembangan, Anda dapat menggunakan Grafana OTel-LGTM service (opens in a new tab), yang berisi OpenTelemetry Collector dan backend untuk log (Loki), metrik (Prometheus), dan jejak (Tempo).

grafana otel lgtm

Anda dapat memulai layanan ini dengan menggunakan Docker/Podman sebagai berikut:

docker run -p 3000:3000 -p 4317:4317 -p 4318:4318 --rm -ti grafana/otel-lgtm

Kemudian, Anda dapat menavigasi ke UI Grafana dengan mengakses localhost:3000 dan kemudian Anda dapat menjelajahi semua data yang dikirimkan ke collector OpenTelemetry.

Opsi Yang Relevan

Opsi	Tipe atau Nilai	Default
`telemetry-endpoint` Endpoint OpenTelemetry untuk terhubung. CLI: `--telemetry-endpoint` Env: `KC_TELEMETRY_ENDPOINT`	String	`http://localhost:4317`
`telemetry-header-<header>` Header OpenTelemetry umum yang akan menjadi bagian dari permintaan ekspor (utama untuk menyediakan header Autorisasi). Periksa dokumentasi tentang cara mengatur variabel lingkungan untuk header yang berisi karakter khusus atau header sensitif besar kecil huruf kustom. CLI: `--telemetry-header-<header>` Env: `KC_TELEMETRY_HEADER_<HEADER>`	String
`telemetry-protocol` Protokol OpenTelemetry yang digunakan untuk komunikasi antara server dan collector OpenTelemetry. CLI: `--telemetry-protocol` Env: `KC_TELEMETRY_PROTOCOL`	`grpc`, `http/protobuf`	`grpc`
`telemetry-resource-attributes` Atribut sumber daya OpenTelemetry yang mengkarakterkan produsen telemetri. Nilai dalam format `key1=val1,key2=val2`. CLI: `--telemetry-resource-attributes` Env: `KC_TELEMETRY_RESOURCE_ATTRIBUTES`	List
`telemetry-service-name` Nama layanan OpenTelemetry. Mengambil precedence atas `service.name` yang didefinisikan dalam properti `telemetry-resource-attributes`. CLI: `--telemetry-service-name` Env: `KC_TELEMETRY_SERVICE_NAME`	String	`keycloak`

Jejak

Opsi	Tipe atau Nilai	Default
`tracing-enabled` Mengaktifkan jejak OpenTelemetry. CLI: `--tracing-enabled` Env: `KC_TRACING_ENABLED`	`true`, `false`	`false`
`tracing-endpoint` Endpoint OpenTelemetry untuk terhubung untuk jejak. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-endpoint`. CLI: `--tracing-endpoint` Env: `KC_TRACING_ENDPOINT`	String	`http://localhost:4317`
`tracing-protocol` Protokol OpenTelemetry yang digunakan untuk data telemetri. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-protocol`. CLI: `--tracing-protocol` Env: `KC_TRACING_PROTOCOL`	`grpc`, `http/protobuf`	`grpc`
`tracing-resource-attributes` Atribut sumber daya OpenTelemetry yang ada dalam jejak yang diekspor untuk mengkarakterkan produsen telemetri. Nilai dalam format `key1=val1,key2=val2`. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-resource-attributes`. Untuk informasi lebih lanjut, periksa panduan Jejak. CLI: `--tracing-resource-attributes` Env: `KC_TRACING_RESOURCE_ATTRIBUTES`	List
`tracing-service-name` Nama layanan OpenTelemetry. Mengambil precedence atas `service.name` yang didefinisikan dalam properti `tracing-resource-attributes`. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-service-name`. CLI: `--tracing-service-name` Env: `KC_TRACING_SERVICE_NAME`	String	`keycloak`

Log

Opsi	Tipe atau Nilai	Default
`telemetry-logs-enabled` Mengaktifkan ekspor log ke tujuan yang menangani log OpenTelemetry. CLI: `--telemetry-logs-enabled` Env: `KC_TELEMETRY_LOGS_ENABLED`	`true`, `false`	`false`
`telemetry-logs-endpoint` Endpoint OpenTelemetry untuk mengekspor log. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-endpoint`. CLI: `--telemetry-logs-endpoint` Env: `KC_TELEMETRY_LOGS_ENDPOINT`	String
`telemetry-logs-header-<header>` Header OpenTelemetry yang akan menjadi bagian dari permintaan ekspor log (utama untuk menyediakan header Autorisasi). Periksa dokumentasi tentang cara mengatur variabel lingkungan untuk header yang berisi karakter khusus atau header sensitif besar kecil huruf kustom. CLI: `--telemetry-logs-header-<header>` Env: `KC_TELEMETRY_LOGS_HEADER_<HEADER>`	String
`telemetry-logs-level` Tipe log yang paling verbose yang diekspor ke endpoint telemetri. Untuk informasi lebih lanjut, periksa panduan Telemetri. CLI: `--telemetry-logs-level` Env: `KC_TELEMETRY_LOGS_LEVEL`	`off`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`, `all`	`all`
`telemetry-logs-protocol` Protokol OpenTelemetry yang digunakan untuk mengekspor log. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-protocol`. CLI: `--telemetry-logs-protocol` Env: `KC_TELEMETRY_LOGS_PROTOCOL`	`grpc`, `http/protobuf`

Metrik

Opsi	Tipe atau Nilai	Default
`metrics-enabled` Apakah server harus mengekspos metrik. Jika diaktifkan, metrik tersedia di endpoint `/metrics`. CLI: `--metrics-enabled` Env: `KC_METRICS_ENABLED`	`true`, `false`	`false`
`telemetry-metrics-enabled` Mengaktifkan ekspor metrik ke tujuan yang menangani metrik OpenTelemetry. CLI: `--telemetry-metrics-enabled` Env: `KC_TELEMETRY_METRICS_ENABLED`	`true`, `false`	`false`
`telemetry-metrics-endpoint` Endpoint OpenTelemetry untuk terhubung ke Metrik. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-endpoint`. CLI: `--telemetry-metrics-endpoint` Env: `KC_TELEMETRY_METRICS_ENDPOINT`	String
`telemetry-metrics-header-<header>` Header OpenTelemetry yang akan menjadi bagian dari permintaan ekspor metrik (utama untuk menyediakan header Autorisasi). Periksa dokumentasi tentang cara mengatur variabel lingkungan untuk header yang berisi karakter khusus atau header sensitif besar kecil huruf kustom. CLI: `--telemetry-metrics-header-<header>` Env: `KC_TELEMETRY_METRICS_HEADER_<HEADER>`	String
`telemetry-metrics-interval` Interval antara awal dua upaya ekspor metrik ke tujuan yang menangani data metrik OpenTelemetry. Menerima format waktu sederhana seperti java.time.Duration (seperti 5000ms, 30s, 5m, 1h). Jika nilai hanya angka, itu mewakili waktu dalam detik. CLI: `--telemetry-metrics-interval` Env: `KC_TELEMETRY_METRICS_INTERVAL`	String	`60s`
`telemetry-metrics-protocol` Protokol OpenTelemetry yang digunakan untuk data telemetri metrik. Jika tidak diberikan, nilai diwarisi dari opsi `telemetry-protocol`. CLI: `--telemetry-metrics-protocol` Env: `KC_TELEMETRY_METRICS_PROTOCOL`	`grpc`, `http/protobuf`

Semua konfigurasi provider Melacak status instance dengan health check