内部テレメトリー

インスタンス自身の内部テレメトリーを確認することで、任意の OpenTelemetry コレクターのインスタンスの健全性を詳しく調べることができます。 このテレメトリーとコレクターの監視 およびトラブルシューティング に役立つように設定する方法を学ぶために読み進めてください。

コレクターで内部テレメトリーを有効化する

デフォルトでは、コレクターは2つの方法で自身のテレメトリーを公開します。

• 内部 メトリクス はデフォルトのポート 8888 の Prometheus インターフェイスを使用して公開されます。
• デフォルトでログ は stderr に出力されます。

リソース属性を設定する

コレクターは、その内部テレメトリーシグナルに service.name、service.version、および service.instance.id（ランダムに生成される）リソース属性を自動的に付与します。 これらは、属性値を null（例: service.name: null）に設定することで無効化できます。

コレクターの内部テレメトリーシグナル（トレース、メトリクス、ログ）に追加のリソース属性を加えたい場合は、service::telemetry::resource の下で設定できます。

service:
  telemetry:
    resource:
      attribute_key: 'attribute_value'

内部メトリクスを設定する

内部メトリクス向けのOTLP エクスポーター

コレクターによってどのように内部メトリクスが生成され、公開されるかを設定できます。 デフォルトでは、コレクターは自身に関する基本的なメトリクスを生成し、スクレイピング先 http://127.0.0.1:8888/metrics 向けに OpenTelemetry Go のPrometheus エクスポーターを使用してそれらを公開します。

コレクターは、以下の設定により OTLP バックエンドへ内部メトリクスをプッシュできます。

service:
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

内部メトリクス向けの Prometheus エンドポイント

また、必要に応じて、Prometheus エンドポイントを特定の 1 つのネットワークインターフェイス、またはすべてのネットワークインターフェイスで公開できます。 コンテナ化された環境では、このポートをパブリックインターフェイスで公開したい場合があります。

Prometheus の設定を service::telemetry::metrics の下に設定してください。

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: '0.0.0.0'
                port: 8888

Prometheus のメトリクスに追加のラベルを加えたい場合、それらを prometheus::with_resource_constant_labels で追加できます。

prometheus:
  host: '0.0.0.0'
  port: 8888
  with_resource_constant_labels:
    included:
      - label_key

そして、service::telemetry::resource でラベルを参照してください。

resource:
  label_key: label_value

サービスのアドレス

service:
  telemetry:
    metrics:
      address: 0.0.0.0:8888

メトリクスの詳細度

以下のいずれかの値を level フィールドに設定することで、コレクターのメトリクス出力の詳細度を調整できます。

• none: テレメトリーは収集されません。
• basic: 標準的なサービスのテレメトリーになります。
• normal: デフォルトレベルで、basic に加えて標準的な指標を追加します。
• detailed: 最も詳細なレベルで、dimensions と views を含みます。

各詳細度レベルは、特定のメトリクスが出力されるしきい値を表します。 レベルごとの内訳を含むメトリクスの完全な一覧については、内部メトリクスの一覧 を参照してください。

メトリクス出力のデフォルトレベルは normal です。 別のレベルを使用するには、service::telemetry::metrics::level を設定します。

service:
  telemetry:
    metrics:
      level: detailed

メトリクスビュー

views を使用することで、コレクターからどのようにメトリクスが出力されるかをさらに設定できます。 たとえば、以下の設定は、otelcol_process_uptime という名前のメトリクスを、新しい名前 process_uptime と説明で出力するように更新します。

service:
  telemetry:
    metrics:
      views:
        - selector:
            instrument_name: otelcol_process_uptime
            instrument_type:
          stream:
            name: process_uptime
            description: The amount of time the Collector has been up

結果となる集計、属性、およびカーディナリティ制限を更新するために views を使用することもできます。 オプションの完全な一覧については、OpenTelemetry 構成スキーマのリポジトリにある例を参照してください。

内部ログの設定

ログ出力は stderr にあります。 ログは構成 service::telemetry::logs で設定できます。 設定のオプションは以下のとおりです。

journalctl を使用して、Linux の systemd システム上でコレクターのログを確認することもできます。

• All logs
• Errors only

journalctl | grep otelcol

journalctl | grep otelcol | grep Error

以下の設定はコレクターから OTLP/HTTP バックエンドへ内部ログを出力するために使用できます。

service:
  telemetry:
    logs:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

内部トレースの設定

コレクターはデフォルトではトレースを公開しませんが、公開するように設定できます。

以下の設定はコレクターから OTLP バックエンドへ内部トレースを出力するために使用できます。

service:
  telemetry:
    traces:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

追加のオプションについては、設定例 を参照してください。 tracer_provider セクションが、ここでの traces に対応していることに注意してください。

内部テレメトリーの種類

OpenTelemetry コレクターは、自身の運用メトリクスを明確に公開することで、可観測なサービスのモデルとなることを目指しています。 さらに、同じホスト上の別のプロセスによって問題が引き起こされているかどうかを把握するのに役立つホストリソースのメトリクスを収集します。 コレクターの特定のコンポーネントは、それぞれ独自のカスタムテレメトリーを出力できます。 このセクションでは、コレクター自身が出力するさまざまな種類の可観測性について学びます。

内部メトリクスで観測可能な値の概要

コレクターは、少なくとも以下の値に対して内部メトリクスを出力します。

• プロセスの稼働時間と開始以降の CPU 時間。
• プロセスのメモリとヒープ使用量。
• レシーバーについて: データタイプごとに承認および拒否された項目。
• プロセッサーについて: 入力と出力項目数。
• エクスポーターについて: データの種類ごとの送信した項目数、キューに追加できなかった項目数 および送信に失敗した項目数。
• エクスポーターについて: キューサイズと容量。
• HTTP/gRPC リクエストおよびレスポンスの数、継続時間、サイズ。

より詳細な一覧は、以下のセクションで参照できます。

メトリクス名

このセクションでは、いくつかの内部メトリクスに適用される特別な命名規則を説明します。

otelcol_ 接頭辞

コレクターの v0.106.1 以降では、内部メトリクス名はそのソースに基づいて異なる方法で扱われます。

• コレクターコンポーネントから生成されるメトリクスは、otelcol_ 接頭辞が付きます。
• 計装ライブラリから生成されるメトリクスは、そのメトリクス名に明示的に接頭辞が付けられていない限り、デフォルトでは otelcol_ 接頭辞を使用しません。

v0.106.1 より前のコレクターのバージョンにおいて、Prometheus エクスポーターを使用して出力されるすべての内部メトリクスは、そのメトリクスの生成元に関係なく otelcol_ という接頭辞が付与されます。 これには、コレクターのコンポーネントと計装ライブラリの両方からのメトリクスが含まれます。

_total 接尾辞

デフォルトで Prometheus 固有の動作として、Prometheus エクスポーターはotelcol_exporter_send_failed_spans_total のように、Prometheus の命名規則に従うため合計メトリクスに _total 接尾辞を追加します。 この動作は、Prometheus エクスポーターの設定で without_type_suffix: true を設定することで無効化できます。

コレクターの設定で service::telemetry::metrics::readers を省略する場合、コレクターによって設定されるデフォルトの Prometheus エクスポーターは、すでに without_type_suffix が false に設定されています。 ただし、readers をカスタマイズして Prometheus エクスポーターを手動で追加する場合は、「raw」メトリクス名に戻すためにそのオプションを設定する必要があります。 詳細については、コレクター v1.25.0/v0.119.0 リリースノートを参照してください。

OTLP を通じてエクスポートされる内部メトリクスは、この動作がありません。 このページの 内部メトリクス は、otelcol_exporter_send_failed_spans のような OTLP 形式で一覧化されています。

_seconds とその他の単位接尾辞

Prometheus エクスポーターは、単位を持つメトリクスに単位接尾辞を付加します。 たとえば、otelcol_process_uptime（単位: 秒）は otelcol_process_uptime_seconds_total としてエクスポートされることがあります。 つまり、_seconds の単位接尾辞が先に追加され、その後に _total のカウンタを示す接尾辞が追加されます。

コレクターによって設定されるデフォルトの Prometheus エクスポーター（readers が指定されていない場合）は、すでに後方互換性のために without_type_suffix と without_units を true に設定しています。 そのため、 otelcol_process_uptime はそのまま使用されます。

しかし、service::telemetry::metrics::readers の下で Prometheus エクスポーターを手動で設定する場合、それらのオプションはデフォルトでは設定されません。 元のより短いメトリクス名を維持するには、以下のように両方のオプションを明示的に true に設定してください。

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: '0.0.0.0'
                port: 8888
                without_type_suffix: true
                without_units: true

この設定では、otelcol_process_uptime_seconds_total は otelcol_process_uptime としてエクスポートされます。

ドット (.) とアンダースコア (_)

http* および rpc* メトリクスは計装ライブラリに由来します。 それらの元の名前はドット（.）を使っていました。 コレクター v0.120.0 より前では、Prometheus で公開される内部メトリクスは、Prometheus の命名規則に合わせるためにドット（.）をアンダースコア（_）に変更していました。その結果、rpc_server_durationのようなメトリクス名になっていました。

コレクターの 0.120.0 以降のバージョンでは Prometheus 3.0 スクレーパーを使用するため、ドットを含む元の http* および rpc* メトリクス名が保持されます。 このページの内部メトリクス は、rpc.server.duration のような元の形式で一覧化されています。 詳細については、コレクター v0.120.0 リリースノートを参照してください。

内部メトリクスの一覧

以下の表では、各内部メトリクスを詳細度レベル basic、normal、detailed ごとにグループ化しています。 各メトリクスは名前と説明によって識別され、計装タイプ別に分類されています。

basic レベルのメトリクス

追加の normal レベルのメトリクス

追加の detailed レベルのメトリクス

内部ログで観測可能なイベント

コレクターは以下の内部イベントをログに記録します。

• コレクターのインスタンスの開始または停止。
• ローカル飽和、ダウンストリーム飽和、ダウンストリーム利用不可など、指定された理由によるスロットリングのためにデータドロップが開始される。
• スロットリングによるデータドロップが停止する。
• 無効なデータによるデータドロップが開始される。無効なデータのサンプルが含まれる。
• 無効なデータによるデータドロップが停止する。
• クリーン停止とは区別される形でクラッシュが検出される。利用可能であればクラッシュデータが含まれる。

テレメトリーの成熟度レベル

コレクターのテレメトリーレベルは、コレクターが生成するすべてのファーストパーティーテレメトリーに適用されます。 OpenTelemetry Go のものを含むサードパーティーライブラリは、これらの成熟度レベルの対象外になります。

トレース

トレーシング計装はまだ活発に開発中であり、スパン名、付加される属性、計測対象エンドポイント、またはテレメトリーのその他の側面に変更が加えられる可能性があります。 この機能が安定版に移行するまで、トレーシング計装の後方互換性は保証されません。

メトリクス

コレクターのファーストパーティーメトリクスは、以下のライフサイクルに従います。

stateDiagram-v2
    state StabilityLevels {
    InDevelopment --> Alpha
    Alpha --> Beta
    Beta --> Stable
    }

    InDevelopment: In Development

    StabilityLevels --> Deprecated
    Deprecated --> Removed

安定性レベルは、OTEP-0232 に由来するセマンティック規約の ガイダンス に従います。 コレクターのメトリクスは release_candidate レベルをスキップします。

非推奨および削除済の段階は、安定性レベルではなくライフサイクル状態である点に注意してください。

OpenTelemetry Go の計装ライブラリによって生成されるものを含むサードパーティーメトリクスは、これらの成熟度レベルの対象外です。

開発中

開発中のメトリクスは、まだ活発に開発中であり、どのリリースでも変更される可能性があります。

アルファ

アルファのメトリクスには安定性保証がありません。これらのメトリクスは、いつでも変更または削除される可能性があります。

ベータ

ベータのメトリクスはリリース間でまだ変更される可能性がありますが、コンポーネントのオーナーは破壊的変更を最小化するよう努める必要があります。 この段階は、より広い利用を促進し、stable の前の最終ステップです。

安定版

安定版のメトリクスは変更されないことが保証されています。これは以下を意味します。

• 非推奨シグネチャがない安定版メトリクスは、削除も改名もされません。
• 安定版メトリクスの型と属性は変更されません。

非推奨

非推奨メトリクスは削除予定ですが、まだ使用可能です。 これらのメトリクスの説明には、それらが非推奨になったバージョンに関する注記が含まれます。 たとえば、以下になります。

非推奨化前

# HELP otelcol_exporter_queue_size this counts things
# TYPE otelcol_exporter_queue_size counter
otelcol_exporter_queue_size 0

非推奨化後

# HELP otelcol_exporter_queue_size (Deprecated since 1.15.0) this counts things
# TYPE otelcol_exporter_queue_size counter
otelcol_exporter_queue_size 0

削除済み

削除されたメトリクスは、公開されなくなり、使用できません。

ログ

個々のログエントリーとその書式は、あるリリースから次のリリースで変更される可能性があります。 現時点では安定性に関する保証はありません。

コレクターを監視するために内部テレメトリーを使用する

このセクションでは、コレクター自身のテレメトリーを使用して監視するためのベストプラクティスを推奨します。

監視

キュー長

ほとんどのエクスポーターは、コレクターのあらゆる本番デプロイメントでの使用が推奨されるキューおよび/または再試行メカニズムを提供します。

otelcol_exporter_queue_capacity メトリクスは、送信キューの容量をバッチ単位で示します。 otelcol_exporter_queue_size メトリクスは、送信キューの現在のサイズを示します。 キュー容量がワークロードをサポートできるかどうか確認するため、これら 2 つのメトリクスを使ってください。

以下の 3 つのメトリクスを使用すると、送信キューへの到達に失敗したスパン、メトリクスポイント、ログの数を特定できます。

• otelcol_exporter_enqueue_failed_spans
• otelcol_exporter_enqueue_failed_metric_points
• otelcol_exporter_enqueue_failed_log_records

これらの失敗は、未処理の要素でキューが埋まっている原因で発生する可能性があります。 送信レートを下げるか、コレクターを水平スケールする必要があるかもしれません。

キューまたは再試行メカニズムは、監視のためのロギングもサポートしています。 Dropping data because sending_queue is full のようなメッセージがログにあるか確認してください。

受信失敗

otelcol_receiver_refused_log_records、otelcol_receiver_refused_spans、および otelcol_receiver_refused_metric_points の発生率が継続している場合、クライアントに返されたエラーが多すぎることを示します。 デプロイメントやクライアントの耐障害性によっては、これはクライアントのデータ損失を示す可能性があります。

otelcol_exporter_send_failed_log_records、otelcol_exporter_send_failed_spans、および otelcol_exporter_send_failed_metric_points の発生率が継続している場合、コレクターが期待どおりにデータをエクスポートできていないことを示します。 これらのメトリクスは、再試行の可能性があるため、本質的にデータ損失を意味するものではありません。 しかし、失敗率が高い場合は、データを受信するネットワークまたはバックエンドに問題があることを示している可能性があります。

データフロー

otelcol_receiver_accepted_log_records、otelcol_receiver_accepted_spans、および otelcol_receiver_accepted_metric_points メトリクスでデータ流入を監視できます。 そして、 otelcol_exporter_sent_log_records、otelcol_exporter_sent_spans、および otelcol_exporter_sent_metric_points メトリクスでデータ流出を監視できます。