外れ値とエラーをExemplarで分析

Exemplarを使用して、メトリクスを記録されたトレースに接続し、エラーまたはレイテンシの根本原因を分析します。

メトリクスは複数のイベントを集計したもので、システムが定義された範囲内で動作しているかどうかを示します。エラー率やテールレイテンシを監視し、アラートを設定したり、パフォーマンスの最適化を推進したりするのに非常に役立ちます。しかし、集計によって、メトリクスで報告されたレイテンシやエラーの根本原因を見つけることが困難になります。

エラーとレイテンシの根本原因は、トレースを有効にすることで見つけることができます。メトリクスを記録されたトレースに接続するために、Exemplarという概念があります。

Exemplarが設定されると、Keycloakは最後に記録されたトレースをExemplarとしてメトリクスを報告します。Grafanaのようなダッシュボードツールは、メトリクスダッシュボードからトレースビューへのExemplarをリンクできます。

Exemplarをサポートするメトリクスは次のとおりです

http_server_requests_seconds_count (ヒストグラムを含む)
このメトリクスの詳細については、HTTPメトリクスのガイドを参照してください。
keycloak_credentials_password_hashing_validations_total
このメトリクスの詳細については、Self-provided metricsのガイドを参照してください。
keycloak_user_events_total
このメトリクスの詳細については、Self-provided metricsのガイドを参照してください。

ピンク色のインジケーターの1つにカーソルを合わせるとExemplarが表示されるレイテンシのヒートマップ視覚化のスクリーンショットを以下に示します。

図1. Exemplar付きヒートマップ図

Exemplarの設定

Exemplarを活用するには、次の手順を実行します

メトリクスによる洞察の獲得ガイドで説明されているように、Keycloakのメトリクスを有効にします。
トレースによる根本原因分析ガイドで説明されているように、Keycloakのトレースを有効にします。
モニタリングシステムでExemplarストレージを有効にします。

Prometheusの場合、これは有効にする必要のあるプレビュー機能です。
Prometheusでデフォルトで有効になっていないOpenMetricsText1.0.0プロトコルを使用してメトリクスをスクレイピングします。

Kubernetes環境でPodMonitorsなどを使用している場合、カスタムリソースのspecに追加することでこれを実現できます
```
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  ...
spec:
  scrapeProtocols:
    - OpenMetricsText1.0.0
```
トレースにリンクするメトリクスデータソースを構成します。

GrafanaとPrometheusを使用する場合、これはPrometheusデータソースのexemplarTraceIdDestinationsを設定することになります。これは、JaegerやTempoのようなツールによって提供されるトレースデータソースを指します。
ダッシュボードでExemplarを有効にします。

Exemplarを表示したい各ダッシュボードの各クエリで、Exemplarトグルを有効にします。正しく設定すると、トレースを表示するためにクリックできる小さな点または星がダッシュボードに表示されます。

スクレイピングプロトコルを指定しない場合、Prometheusはデフォルトでコンテンツネゴシエーションでそれを送信せず、KeycloakはExemplarを含まないPrometheusTextプロトコルにフォールバックします。
トレースとメトリクスを有効にしても、リクエストサンプリングがトレースを記録しなかった場合、公開されたメトリクスにはExemplarは含まれません。
ブラウザでメトリクスエンドポイントにアクセスすると、コンテンツネゴシエーションによりPrometheusText形式が返され、Exemplarは表示されません。

Exemplarが期待どおりに動作することの確認

KeycloakがExemplar用に正しく設定されていることを確認するには、次の手順を実行します

Keycloakのメトリクスとトレースを設定する手順に従ってください。
テスト目的で、トレース比率を1.0に設定してすべてのトレースを記録します。本番環境での推奨サンプリング設定については、トレースによる根本原因分析を参照してください。
Keycloakインスタンスにログインして、いくつかのトレースを作成します。
次のようなコマンドでメトリクスをスクレイピングし、Exemplarが設定されているメトリクスを検索します
```
$ curl -s https://#:9000/metrics \
-H 'Accept: application/openmetrics-text; version=1.0.0; charset=utf-8' \
| grep "#.*trace_id"
```
これにより、次のような出力が得られるはずです。スパンIDとトレースIDが追加される後の追加の#に注意してください
```
http_server_requests_seconds_count {...} ... # {span_id="...",trace_id="..."} ...
```

このページで

このガイドを編集