Prometheus エグザンプラを使用する

このドキュメントでは、Google Cloud Managed Service for Prometheus を使用して、ヒストグラム指標に Prometheus エグザンプラを取り込む方法について説明します。次のいずれかを使用する必要があります。

Managed Service for Prometheus マネージドコレクションバージョン 0.7.0 以降
Managed Service for Prometheus セルフデプロイコレクションバージョン 2.35.0-gmp.5-gke.0 以降
OpenTelemetry Collector

エグザンプラは通常、一定の期間内に収集された指標データにトレース ID を関連付けるために使用されますが、指標以外のデータを収集された指標に関連付ける場合にも使用できます。トレース情報を指標データとともに保存すると、指標値の突然の変化に関連するトレースを迅速に特定できます。指標データが記録されたときに、アプリケーションで何が起こったかを特定するために、タイムスタンプを使用してトレース情報と指標データを手動で相互参照する必要がありません。

Managed Service for Prometheus エグザンプラは Cloud Trace と互換性があります。また、Grafana Tempo などのサードパーティトレースツールとも互換性があります。

次のスクリーンショットは、ヒストグラムバケットとそれに関連するエグザンプラのセットが表示されている Grafana チャートを示しています（1 つのエグザンプラが開いています）。

ヒストグラムバケットとエグザンプラが表示されている Grafana チャート。

Managed Service for Prometheus での Prometheus エグザンプラ

エグザンプラは、OpenMetrics の表示形式を使用することで、Prometheus でサポートされています。OpenMetrics エグザンプラの構造は次のとおりです。

エグザンプラの値: 整数または 64 ビット浮動小数点数のいずれか。
（省略可）タイムスタンプ: Unix エポック秒でなければなりません。負の値にすることもできます。
エグザンプラのラベルの数（通常は trace_id と span_id の値を含む）。すべてのラベル名と値の合計長は、128 個の UTF-8 文字以下にする必要があります（Go アプリケーションの場合は 128 実行以下）。

Google Cloud Managed Service for Prometheus は、ヒストグラム指標に適用されているエグザンプラのみを取り込むことができます。カウンタ指標に適用されているエグザンプラは取り込めません。Prometheus ヒストグラム指標は、エグザンプラをサポートする類似した Cloud Monitoring の Distribution タイプに変換されます。Cloud Monitoring の非分布指標は、エグザンプラをサポートしていません。

エグザンプラは 24 か月間クエリに使用できます。この保持期間とは対照的に、アップストリームの Prometheus では、エグザンプラはデータがメモリ内にある期間（通常は 14 日未満）しか保持されません。Managed Service for Prometheus は、エグザンプラを時系列で保存するため、エグザンプラは時系列の保持ポリシーに従って保持されます。Cloud Monitoring のデータ保持の詳細については、データの保持をご覧ください。

エグザンプラの取り込みを有効にする

マネージドコレクションバージョン 0.7.0 以降で Managed Service for Prometheus を使用している場合は、エグザンプラの取り込みが自動的に有効になります。

セルフデプロイコレクションと Managed Service for Prometheus を使用している場合、次のようなフィーチャートグルを指定して、サーバーの起動時にエグザンプラの取り込みを有効にする必要があります。

--enable-feature=exemplar-storage

エグザンプラを使用して指標を書き込む

各 Prometheus クライアントには、そのクライアント内でエグザンプラを適切に使用するための独自の手順があります。以下の手順に沿って、アプリケーションで OpenMetrics 形式の指標を公開し、Prometheus がアプリケーションの /metrics エンドポイントからスクレイピングできるようにします。例については、以下をご覧ください。

Cloud Trace と統合する

Cloud Trace と互換性のあるエグザンプラを使用して Prometheus ヒストグラムを記述できます。Cloud Monitoring のヒートマップグラフにエグザンプラなどのデータを表示すると、エグザンプラを使用して、関連するトレーススパンの詳細を表示できます。Trace でトレースデータを分析することもできます。詳細については、ヒートマップグラフにエグザンプラを表示するとトレースの詳細を表示するをご覧ください。

Trace と互換性のあるエグザンプラを作成するには、Prometheus エグザンプラに次のラベルを含める必要があります。

project_id
trace_id
span_id

エグザンプラにこれらの 3 つのラベルが含まれている場合、そのラベルは Trace 互換の SpanContext オブジェクトの作成に使用されます。このオブジェクトは、Cloud Monitoring Distribution バケット用に作成されたエグザンプラに適用されています。

完全な SpanContext を構成するラベル以外のすべてのラベルは、Distribution バケットのエグザンプラに適用される DroppedLabels オブジェクトに追加されます。

エグザンプラを使用して指標をクエリする

Prometheus API は、エグザンプラをクエリするために api/v1/query_exemplars エンドポイントを公開します。

Google Cloud Managed Service for Prometheus とやり取りするようにクエリインターフェースを設定すると、エグザンプラのクエリが自動的に含まれます。クエリインターフェースの設定については、Grafana を使用したクエリまたは Prometheus API または UI を使用したクエリをご覧ください。