OpenTelemetry メトリクスを Prometheus に送信する

OTLP/HTTP の受信設定と Collector の転送方法、Prometheus に保存される名前やリソース属性、Delta の扱いを確認します。

ベストプラクティス
テレメトリーが可観測性バックエンドに流れるイメージ

決済サービスの OpenTelemetry メトリクスを新しいバックエンドへ送り始めたところ、Collector はバッチを受け取っているのに、Prometheus のダッシュボードには何も出ない。まず実際の HTTP リクエストを確認します。Prometheus の OTLP メトリクス受信パスは /api/v1/otlp/v1/metrics です。リクエストが届いていれば、計装を変更する前に、保存されたメトリクス名とラベルを調べます。

メトリクスを受信パスに届ける

Prometheus 3.x では、OTLP レシーバーを明示的に有効化します。ローカルでの動作確認では、下記の Prometheus 設定を prometheus.yml として保存し、待ち受けをループバックに限定します。

prometheus --web.enable-otlp-receiver --web.listen-address=127.0.0.1:9090 --config.file=prometheus.yml

環境変数で設定できる SDK から直接送る場合は、OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf と OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:9090/api/v1/otlp/v1/metrics を設定します。メトリクス専用の変数には完全な URL を指定します。共通の OTEL_EXPORTER_OTLP_ENDPOINT を使う場合はベース URL を指定すると、HTTP エクスポーターがシグナル別のパスを追加します。トレースとログの送信先は別に設定します。

Collector 0.159.0 では、次の最小構成で OTLP/HTTP メトリクスを受け取り、Prometheus に転送できます。以前の Collector ではエクスポーター名が otlphttp の場合があります。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
exporters:
  otlp_http:
    endpoint: http://127.0.0.1:9090/api/v1/otlp
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [otlp_http]

Collector は endpoint に /v1/metrics を追加します。metrics_endpoint を使う場合は完全な URL を指定します。受信側に gRPC を設定すればアプリケーションから OTLP/gRPC で受け取れます。Prometheus へ転送する側は引き続き HTTP です。Prometheus 2.47 では実験的レシーバーが --enable-feature=otlp-write-receiver で導入されました。実際に運用するバージョンで起動オプションを確認してください。Prometheus の OTLP ガイド · OTLP エクスポーター仕様 · Collector の HTTP エクスポーター

保存されたメトリクス名とラベルを確認する

決済サービスが checkout.requests という累積の単調増加カウンターを送ったとします。Prometheus 3.16 の既定の変換では checkout_requests_total として検索できます。メトリクス名とラベル名が正規化され、型や単位に応じた接尾辞が付きます。UTF-8 をサポートするバージョンでも、OTLP の変換方式は設定で決まります。方式を変えると、ダッシュボードやルールのセレクターが変わったり、型や単位で区別されていた系列が衝突したりします。

job は service.name から作られ、service.namespace があれば先頭に付きます。instance には service.instance.id が入ります。名前空間が shop、サービス名が checkout、インスタンス ID が checkout-1 なら、checkout_requests_total{job="shop/checkout",instance="checkout-1"} で確認できます。Prometheus 3.16 が target_info を生成するのは、リソースが job または instance になる識別属性と、少なくとも一つの非識別属性を持つ場合です。job と instance で結合するには、対応する情報系列が一つに定まる必要があります。属性が変わると旧系列と新系列が一時的に同時に見える場合があります。

リソースに環境属性があり、各アラートで絞り込みに使うなら、通常のメトリクスラベルに追加します。Pod 名が各系列に不要であれば、target_info 側に残します。下記の設定では、既定の変換により deployment_environment_name ラベルが付きます。

otlp:
  translation_strategy: UnderscoreEscapingWithSuffixes
  promote_resource_attributes:
    - deployment.environment.name

新しいラベルの組み合わせが現れるたびに時系列が分かれます。同時に存在する系列数があまり増えなくても、再起動などで値が頻繁に入れ替わると、系列の生成と消滅が増えます。実際の負荷で有効系列数、系列の増加ペース、メモリの余裕を確認してください。Prometheus のリソース属性変換 · Prometheus 3.16 の変換実装(英語) · 可観測性データの高カーディナリティ

ダッシュボードを移す前に集計の時間性を決める

Cumulative のカウンターは開始時点からの累計を持ち、Delta のデータ点は各区間の増分を持ちます。既存のダッシュボードが累積カウンターに対して rate() を実行するなら、可能な限り SDK から Cumulative で出力します。Collector で変換する場合は、同じストリームを一貫して同じ変換先へ送ります。変換処理は状態を持つため、再起動や経路の切り替えで累計が変わり得ます。

Prometheus 3.2 では実験的な otlp-deltatocumulative が追加されました。変換状態はメモリ上にあり、再起動で失われます。3.4 で追加された実験的な otlp-native-delta-ingestion は、増分値をそのまま格納します。二つのフラグは排他的です。生の増分値を扱う場合は、そのバージョンの Delta の挙動に合わせてクエリを見直します。Prometheus の機能フラグ · バージョン変更履歴

遅延到着と重複書き込みを切り分ける

複数の Collector を経由すると、バッチの到着順序が前後することがあります。同じストリームの一部を別々のレプリカが転送する場合は、実際の遅延を確認して storage.tsdb.out_of_order_time_window の範囲を検討します。同じサンプルを二重に転送していたり、別々の送信元で同じインスタンス ID を使っていたりする場合は、まず経路と ID を修正します。許容範囲を広げる効果は、範囲内の遅延サンプルを受け入れることに限られます。

ループバック以外で受信する前に TLS を有効化し、書き込み元を制限します。エクスポート失敗、リトライ、キューの状態に加え、Prometheus が破棄したサンプルや、アラートが参照する系列を確認します。Remote Write で長期保存先にも送るなら、そのキューも個別に監視します。アプリケーションから OTLP でプッシュする経路の死活は、スクレイプで生成される up とは別に監視します。OpenTelemetry Collector の監視

保存先を切り替える前に数値を突き合わせる

既存の Guance ワークスペースであれば、DataKit の OpenTelemetry 入力(英語)を設定して OTLP メトリクスを受け取れます。既存の /metrics は DataKit の Prom コレクター(英語)からスクレイプできます。アプリケーションのカウンターとは別に、トレースの転送先と、トレースから生成される APM 指標を確認します。

二つの保存先へ並行して送信する期間を設けるなら、同じサービス、時間範囲、計装からのデータを比較します。既知のリクエスト数の変化やレイテンシーヒストグラムを確認してからアラートを移します。Guance の PromQL クエリモード(英語)を使う場合も、保存された名前、ラベル、バケット境界を確かめてからクエリを流用します。

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ