Analisis akar masalah dengan pelacakan

Panduan ini menjelaskan cara Anda dapat mengaktifkan dan mengonfigurasi pelacakan terdistribusi di NQRust-Identity dengan menggunakan OpenTelemetry (opens in a new tab) (OTel). Pelacakan memungkinkan pemantauan detail dari siklus hidup setiap permintaan, yang membantu dengan cepat mengidentifikasi dan mendiagnosa masalah,从而导致 debugging dan pemeliharaan yang lebih efisien.

Hal ini memberikan wawasan berharga tentang kemacetan kinerja dan dapat membantu mengoptimalkan efisiensi sistem secara keseluruhan dan melampaui batas sistem. NQRust-Identity menggunakan ekstensi Quarkus OTel (opens in a new tab) yang didukung yang memberikan integrasi dan eksposur pelacakan aplikasi yang mulus.

Mengaktifkan pelacakan

Mungkin untuk mengaktifkan eksposur pelacakan menggunakan opsi waktu kompilasi tracing-enabled sebagai berikut:

bin/kc.[sh|bat] start --tracing-enabled=true

Secara default, eksportir pelacakan mengirimkan data dalam batch, menggunakan protokol gRPC dan endpoint http://localhost:4317.

Nama layanan default adalah keycloak, ditentukan melalui properti tracing-service-name, yang mengambilprecedence atas service.name yang didefinisikan dalam properti tracing-resource-attributes.

Untuk informasi lebih lanjut tentang atribut sumber daya yang dapat diberikan melalui properti tracing-resource-attributes, lihat panduan Quarkus OpenTelemetry Resource (opens in a new tab).

Untuk pengaturan pelacakan lainnya, lihat semua konfigurasi yang mungkin di bawah.

Pengaturan pengembangan

Untuk melihat pelacakan NQRust-Identity yang ditangkap, pengaturan dasar dengan memanfaatkan platform pelacakan Jaeger (opens in a new tab) mungkin digunakan. Untuk tujuan pengembangan, Jaeger-all-in-one dapat digunakan untuk melihat pelacakan selama mungkin dengan mudah.

podman|docker run --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one

Port yang terekspos

16686

Antarmuka Jaeger

4317

Penerima gRPC Protokol OpenTelemetry (default)

4318

Penerima HTTP Protokol OpenTelemetry

Anda dapat mengunjungi Antarmuka Jaeger di http://localhost:16686/ untuk melihat informasi pelacakan. Antarmuka Jaeger mungkin terlihat seperti ini dengan pelacakan NQRust-Identity acak:

Informasi dalam pelacakan

Span

NQRust-Identity membuat span untuk kegiatan berikut:

• Permintaan HTTP masuk
• Database yang keluar, termasuk memperoleh koneksi database
• Permintaan LDAP yang keluar, termasuk terhubung ke server LDAP
• Permintaan HTTP yang keluar, termasuk IdP brokerage

Tag

NQRust-Identity menambahkan tag ke pelacakan tergantung pada jenis permintaan. Semua tag diawali dengan kc..

Contoh tag adalah:

kc.clientId

ID Klien

kc.realmName

Nama Realm

kc.sessionId

ID Sesi Pengguna

kc.token.id

id seperti yang disebutkan dalam token

kc.token.issuer

issuer seperti yang disebutkan dalam token

kc.token.sid

sid seperti yang disebutkan dalam token

kc.authenticationSessionId

ID Sesi Otentikasi

kc.authenticationTabId

ID Tab Otentikasi

Log

Jika pelacakan sedang diambil, itu akan berisi setiap peristiwa pengguna yang dibuat selama permintaan. Ini mencakup, misalnya, peristiwa LOGIN, LOGOUT atau REFRESH_TOKEN dengan semua detail dan ID yang ditemukan dalam peristiwa pengguna.

Kesalahan komunikasi LDAP juga ditunjukkan sebagai entri log dalam pelacakan yang direkam, dengan tumpukan jejak dan detail operasi yang gagal.

ID Pelacakan dalam log

Ketika pelacakan diaktifkan, ID pelacakan termasuk dalam pesan log semua handler log yang diaktifkan (lihat lebih lanjut dalam Mengonfigurasi logging). Hal ini dapat berguna untuk mengasosiasikan peristiwa log dengan eksekusi permintaan, yang mungkin memberikan kelestarian dan debugging yang lebih baik. Semua baris log yang berasal dari permintaan yang sama akan memiliki traceId yang sama dalam log.

Pesan log juga berisi flag sampled, yang terkait dengan sampling yang dijelaskan di bawah dan menunjukkan apakah span diambil - dikirim ke collector.

Format catatan log mungkin dimulai sebagai berikut:

2024-08-05 15:27:07,144 traceId=b636ac4c665ceb901f7fdc3fc7e80154, parentId=d59cea113d0c2549, spanId=d59cea113d0c2549, sampled=true WARN  [org.keycloak.events] ...

Sembunyikan ID Pelacakan dalam log

Anda dapat menyembunyikan ID pelacakan dalam handler log tertentu dengan menentukan opsi NQRust-Identity terkait log-<handler-name>-include-trace, di mana <handler-name> adalah nama handler log. Sebagai contoh, untuk menonaktifkan info pelacakan dalam log console, Anda dapat mematikannya sebagai berikut:

bin/kc.[sh|bat] start --tracing-enabled=true --log=console --log-console-include-trace=false

Sampling

Pengambil sampel memutuskan apakah pelacakan harus dibuang atau diteruskan, secara efektif mengurangi beban dengan membatasi jumlah pelacakan yang dikumpulkan dan dikirim ke collector. Hal ini membantu mengelola konsumsi sumber daya, yang menghindari biaya penyimpanan yang mahal dari setiap permintaan pelacakan dan penalti kinerja potensial.

NQRust-Identity mendukung beberapa pengambil sampel OpenTelemetry bawaan, seperti:

• always_on
• always_off
• traceidratio (default)
• parentbased_always_on
• parentbased_always_off
• parentbased_traceidratio

Pengambil sampel yang digunakan dapat diubah melalui properti tracing-sampler-type.

Pengambil sampel default

Pengambil sampel default untuk NQRust-Identity adalah traceidratio, yang mengontrol tingkat pengambilan sampel berdasarkan rasio yang dapat dikonfigurasi melalui properti tracing-sampler-ratio.

Rasio pelacakan

Rasio pelacakan default adalah 1.0, yang berarti semua pelacakan diambil - dikirim ke collector. Rasio adalah angka mengambang di rentang [0,1]. Misalnya, ketika rasio adalah 0.1, hanya 10% dari pelacakan yang diambil.

Dasar

Pengambil sampel membuat keputusan pengambilan sampelnya berdasarkan rasio span yang diambil saat ini, terlepas dari keputusan yang dibuat pada span induk, seperti dengan penggunaan pengambil sampel parentbased_traceidratio.

Pengambil sampel parentbased_traceidratio bisa menjadi tipe default yang diinginkan karena itu memastikan konsistensi pengambilan sampel antara span induk dan anak. Secara spesifik, jika span induk diambil, semua span anaknya juga akan diambil - keputusan pengambilan sampel yang sama untuk semua. Hal ini membantu untuk menjaga semua span bersama-sama dan mencegah penyimpanan pelacakan yang tidak lengkap.

Namun, itu mungkin mengenali risiko keamanan tertentu yang mengarah pada serangan DoS. Panggilan eksternal dapat memanipulasi header pelacakan, span induk dapat disuntikkan, dan penyimpanan pelacakan dapat dibanjiri. Pengfilteran header HTTP yang tepat (terutama tracestate) dan ukuran kepercayaan panggilan yang memadai perlu dievaluasi.

Untuk informasi lebih lanjut, lihat dokumen W3C Trace context (opens in a new tab).

Pelacakan di lingkungan Kubernetes

Ketika pelacakan diaktifkan saat menggunakan Operator NQRust-Identity, informasi tertentu tentang deployment dipancarkan ke kontainer mendasar.

Pengaturan melalui NQRust-Identity CR

Anda dapat mengubah konfigurasi pelacakan melalui NQRust-Identity CR.

Filter pelacakan berdasarkan atribut Kubernetes

Anda dapat menyaring pelacakan yang diperlukan di backend pelacakan Anda berdasarkan tag mereka:

• service.name - Nama deployment NQRust-Identity
• k8s.namespace.name - Namespace
• host.name - Nama Pod

Operator NQRust-Identity secara otomatis menetapkan variabel lingkungan KC_TRACING_SERVICE_NAME dan KC_TRACING_RESOURCE_ATTRIBUTES untuk setiap kontainer NQRust-Identity yang termasuk dalam pod yang dikelolanya.

Mengikutsertakan informasi pelacakan dalam template Freemarker

Ketika pelacakan diaktifkan, Anda dapat mengikutsertakan ID pelacakan dalam template Freemarker tema masuk dengan menggunakan variabel traceId.

Secara default, tema masuk dasar menyertakan ID pelacakan dalam template error.ftl. Dengan ID pelacakan termasuk dalam halaman kesalahan, pengguna dapat melaporkannya saat mereka mengalami kesalahan, yang dapat membantu Anda dengan cepat mengidentifikasi dan menyelidiki informasi tercatat tambahan untuk operasi tersebut.

Kemudian Anda akan menemukan ID pelacakan dalam semua pesan log untuk permintaan ini, dan dalam sistem pelacakan Anda jika pelacakan ini diambil.

Opsi yang relevan