啟用追蹤

了解如何在 Keycloak 中啟用分散式追蹤
本指南描述目前處於預覽階段的功能。在我們持續開發此功能的同時，請提供您的回饋意見。

本指南說明如何透過使用 OpenTelemetry (OTel) 在 Keycloak 中啟用和設定分散式追蹤。追蹤可以詳細監控每個請求的生命週期，這有助於快速識別和診斷問題，從而提高除錯和維護效率。

它還提供了對效能瓶頸的寶貴見解，並有助於優化系統的整體效率。Keycloak 使用受支援的 Quarkus OTel 擴充功能，該擴充功能提供應用程式追蹤的順暢整合和公開。

啟用追蹤

可以使用建置時選項 tracing-enabled 來啟用公開追蹤，並啟用 opentelemetry 功能，如下所示

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

預設情況下，追蹤匯出器會使用 gRPC 協定和端點 https://127.0.0.1:4317 以批次方式傳送資料。

預設服務名稱為 keycloak，透過 tracing-service-name 屬性指定，此屬性優先於 tracing-resource-attributes 屬性中定義的 service.name。

有關可透過 tracing-resource-attributes 屬性提供的資源屬性的詳細資訊，請參閱 Quarkus OpenTelemetry 資源 指南。

如需更多追蹤設定，請參閱以下所有可能的配置。

開發設定

為了查看擷取的 Keycloak 追蹤，可以使用利用 Jaeger 追蹤平台的基本設定。為了方便開發，可以使用 Jaeger all-in-one 來儘可能輕鬆地查看追蹤。

Jaeger all-in-one 包括 Jaeger 代理程式、OTel 收集器和查詢服務/UI。您無需安裝單獨的收集器，因為您可以將追蹤資料直接傳送到 Jaeger。 
podman|docker run --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one

公開的連接埠

  • :16686 - Jaeger UI

  • :4317 - OpenTelemetry 協定 gRPC 接收器 (預設)

  • :4318 - OpenTelemetry 協定 HTTP 接收器

您可以造訪 https://127.0.0.1:16686/ 上的 Jaeger UI 以查看追蹤資訊。Jaeger UI 可能看起來像這樣，帶有任意的 Keycloak 追蹤

Jaeger UI

記錄中的追蹤

啟用追蹤後，追蹤資訊會包含在所有已啟用記錄處理常式的記錄訊息中 (詳見 設定記錄)。這對於將記錄事件與請求執行關聯非常有用，這可能會提供更好的追蹤能力和除錯能力。來自相同請求的所有記錄行在記錄中都將具有相同的 traceId。

記錄訊息還包含一個 sampled 旗標，它與下面描述的取樣有關，並指示是否對跨度進行取樣 - 已傳送到收集器。

記錄記錄的格式可能如下所示

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

隱藏記錄中的追蹤資訊

您可以透過指定其相關聯的 Keycloak 選項 log-<handler-name>-include-trace，在特定的記錄處理常式中隱藏追蹤資訊，其中 <handler-name> 是記錄處理常式的名稱。例如，若要停用 console 記錄中的追蹤資訊，您可以如下關閉它

bin/kc.[sh|bat] start --tracing-enabled=true --features=opentelemetry --log=console --log-console-include-trace=false
當您明確覆寫特定記錄處理常式的記錄格式時，*-include-trace 選項將不起作用，並且不會包含任何追蹤。

取樣

取樣器決定是否應捨棄或轉發追蹤，透過限制傳送到收集器的已收集追蹤的數量來有效減少額外負荷。它有助於管理資源消耗，從而避免追蹤每個請求的巨大儲存成本和潛在的效能損失。

對於可供生產環境使用的環境，應正確設定取樣，以盡量減少基礎架構成本。

Keycloak 支援多個內建的 OpenTelemetry 取樣器，例如

  • always_on

  • always_off

  • traceidratio (預設)

  • parentbased_always_on

  • parentbased_always_off

  • parentbased_traceidratio

可以使用 tracing-sampler-type 屬性來變更使用的取樣器。

預設取樣器

Keycloak 的預設取樣器是 traceidratio，它根據可透過 tracing-sampler-ratio 屬性設定的指定比例來控制追蹤取樣率。

追蹤比例

預設追蹤比例為 1.0，這表示對所有追蹤進行取樣 - 傳送到收集器。該比例是範圍在 (0,1] 中的浮點數。例如，當比例為 0.1 時，僅對 10% 的追蹤進行取樣。

對於可供生產環境使用的環境，追蹤比例應為較小的數字，以防止追蹤儲存基礎架構的巨額成本並避免效能額外負荷。

基本原理

取樣器會根據目前取樣跨度的比例自行做出取樣決策，無論是否使用 parentbased_traceidratio 取樣器在父跨度上做出的決策如何。

parentbased_traceidratio 取樣器可能是較佳的預設類型，因為它可以確保父跨度和子跨度之間的取樣一致性。具體而言，如果對父跨度進行取樣，則也會對其所有子跨度進行取樣 - 對於所有跨度採取相同的取樣決策。這有助於將所有跨度保持在一起，並防止儲存不完整的追蹤。

但是，這可能會引入某些安全風險，導致 DoS 攻擊。外部呼叫者可以操縱追蹤標頭、可以注入父跨度，並且追蹤儲存可能會不堪重負。需要評估適當的 HTTP 標頭 (尤其是 tracestate) 篩選和呼叫者信任的充分措施。

如需詳細資訊，請參閱 W3C 追蹤內容 文件。

Kubernetes 環境中的追蹤

當在使用 Keycloak Operator 時啟用追蹤時，有關部署的某些資訊會傳播到基礎容器。

Keycloak CR 中尚不支援追蹤配置，因此可以使用 additionalOptions 來設定 tracing-enabled 屬性和其他追蹤選項。

您可以根據追蹤後端的標籤篩選出所需的追蹤

  • service.name - Keycloak 部署名稱

  • k8s.namespace.name - 命名空間

  • host.name - Pod 名稱

Keycloak Operator 會自動為其管理的 Pod 中包含的每個 Keycloak 容器設定 KC_TRACING_SERVICE_NAME 和 KC_TRACING_RESOURCE_ATTRIBUTES 環境變數。

相關選項

值

log-console-include-trace

在主控台記錄中包含追蹤資訊。

如果指定了 log-console-format 選項，則此選項無效。

CLI: --log-console-include-trace
Env: KC_LOG_CONSOLE_INCLUDE_TRACE

僅在啟用主控台記錄處理常式和追蹤時可用

true (預設)、false

log-file-include-trace

在檔案記錄中包含追蹤資訊。

如果指定了 log-file-format 選項，則此選項無效。

CLI: --log-file-include-trace
Env: KC_LOG_FILE_INCLUDE_TRACE

僅在啟用檔案記錄處理常式和追蹤時可用

true (預設)、false

log-syslog-include-trace

在 Syslog 中包含追蹤資訊。

如果指定了 log-syslog-format 選項，則此選項無效。

CLI: --log-syslog-include-trace
Env: KC_LOG_SYSLOG_INCLUDE_TRACE

僅在啟用 Syslog 處理常式和追蹤時可用

true (預設)、false

tracing-compression

預覽：用於壓縮酬載的 OpenTelemetry 壓縮方法。

如果未設定，則停用壓縮。

CLI: --tracing-compression
Env: KC_TRACING_COMPRESSION

僅在啟用 'opentelemetry' 功能和追蹤時可用

gzip、none (預設)

tracing-enabled

預覽：啟用 OpenTelemetry 追蹤。

CLI: --tracing-enabled
Env: KC_TRACING_ENABLED

僅在啟用 'opentelemetry' 功能時可用

true、false (預設)

tracing-endpoint

預覽：要連線的 OpenTelemetry 端點。

CLI: --tracing-endpoint
Env: KC_TRACING_ENDPOINT

僅在啟用 'opentelemetry' 功能和追蹤時可用

https://127.0.0.1:4317 (預設)

tracing-jdbc-enabled

預覽：啟用 OpenTelemetry JDBC 追蹤。

CLI: --tracing-jdbc-enabled
Env: KC_TRACING_JDBC_ENABLED

僅在啟用 'opentelemetry' 功能和追蹤時可用

true (預設)、false

tracing-protocol

預覽：用於遙測資料的 OpenTelemetry 協定。

CLI: --tracing-protocol
Env: KC_TRACING_PROTOCOL

僅在啟用 'opentelemetry' 功能和追蹤時可用

grpc (預設)、http/protobuf

tracing-resource-attributes

預覽：匯出的追蹤中存在的 OpenTelemetry 資源屬性，用於描述遙測產生器。

格式為 key1=val1,key2=val2 的值。如需詳細資訊，請檢查追蹤指南。

CLI: --tracing-resource-attributes
Env: KC_TRACING_RESOURCE_ATTRIBUTES

僅在啟用 'opentelemetry' 功能和追蹤時可用

tracing-sampler-ratio

預覽：OpenTelemetry 取樣器比例。

跨度被取樣的機率。預期的雙精度值在間隔 <0,1) 中。

CLI: --tracing-sampler-ratio
Env: KC_TRACING_SAMPLER_RATIO

僅在啟用 'opentelemetry' 功能和追蹤時可用

1.0 (預設)

tracing-sampler-type

預覽：用於追蹤的 OpenTelemetry 取樣器。

CLI: --tracing-sampler-type
Env: KC_TRACING_SAMPLER_TYPE

僅在啟用 'opentelemetry' 功能和追蹤時可用

always_on、always_off、traceidratio (預設)、parentbased_always_on、parentbased_always_off、parentbased_traceidratio

tracing-service-name

預覽：OpenTelemetry 服務名稱。

優先於 tracing-resource-attributes 屬性中定義的 service.name。

CLI: --tracing-service-name
Env: KC_TRACING_SERVICE_NAME

僅在啟用 'opentelemetry' 功能和追蹤時可用

keycloak (預設)
本頁內容
編輯本指南