Zenn
Open9

OpenTelemetry Collector

OpenTelemetry
nomadblackynomadblacky

Processors の一般情報

https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor#recommended-processors

プロセッサーは、パイプラインのさまざまな段階で使用されます。一般的に、プロセッサーはデータがエクスポートされる前に前処理を行ったり（例：属性の変更やサンプリング）、データがパイプラインを正常に通過するのを確実にするのに役立ちます（例：バッチ処理/リトライ）。

パイプラインとプロセッサーに関する重要なポイント:

サポートされているプロセッサー（アルファベット順）:

contrib リポジトリ には、コレクターのカスタムビルドに追加できるその他のプロセッサーが含まれています。

推奨プロセッサー

デフォルトでは、プロセッサーは有効化されていません。データソースによっては、複数のプロセッサーを有効化することが推奨される場合があります。プロセッサーはすべてのデータソースに対して有効化される必要がありますが、すべてのプロセッサーがすべてのデータソースをサポートしているわけではありません。また、プロセッサーの順序が重要であることも注意が必要です。以下の各セクションで示されている順序がベストプラクティスです。詳細については、各プロセッサーのドキュメントを参照してください。

  1. memory_limiter
  2. 任意のサンプリングまたは初期フィルタリングプロセッサー
  3. Context から送信元を使用するプロセッサー（例：k8sattributes）
  4. batch
  5. その他のプロセッサー

データ所有権

パイプライン内の pdata.Traces、pdata.Metrics および pdata.Logs データの所有権は、データがパイプラインを通過するにつれて引き継がれます。データはレシーバーによって作成され、その後 ConsumeTraces/ConsumeMetrics/ConsumeLogs 関数が呼び出されたときに最初のプロセッサーに所有権が引き継がれます。

注意: レシーバーは複数のパイプラインに接続されている場合があり、その場合、同じデータがデータファンアウトコネクタを介してすべての接続されたパイプラインに渡されます。

データ所有権の観点から、パイプラインは2つのモードで動作します:

  • 排他的データ所有権
  • 共有データ所有権

このモードは、プロセッサーによって報告されたデータ変更の意図に基づいて、起動時に定義されます。意図は、Capabilities 関数によって返される構造体の MutatesData フィールドを介して各プロセッサーによって報告されます。パイプライン内の任意のプロセッサーがデータを変更する意図を宣言すると、そのパイプラインは排他的所有権モードで動作します。さらに、排他的所有権モードのパイプラインに接続されているレシーバーからデータを受け取る任意の他のパイプラインも、排他的所有権モードで動作することになります。

排他的所有権

排他的所有権モードでは、特定のプロセッサーが特定の時点でデータを排他的に所有し、所有するデータを自由に変更できます。

排他的所有権モードは、同じレシーバーからデータを受け取るパイプラインにのみ適用されます。パイプラインが排他的所有権モードであるとマークされている場合、共有レシーバーから受信したデータは、ファンアウトコネクタで複製され、それぞれのパイプラインに渡される前に複製されます。これにより、各パイプラインがデータの独自の排他的なコピーを持ち、そのデータを安全にパイプライン内で変更できるようになります。

データの排他的所有権により、プロセッサーはデータを自由に変更できます（例：attributesprocessorを参照）。データの所有権の期間は、ConsumeTraces/ConsumeMetrics/ConsumeLogs 呼び出しの開始から、次のプロセッサーの ConsumeTraces/ConsumeMetrics/ConsumeLogs 関数が呼び出され、所有権が次のプロセッサーに渡されるまでです。それ以降、プロセッサーはデータを読み書きしてはなりません。新しい所有者が並行してデータを変更する可能性があるためです。

排他的所有権モードにより、データを変更する必要があるプロセッサーを簡単に実装できます。これは、単にその意図を宣言することで実現できます。

共有所有権

共有所有権モードでは、特定のプロセッサーがデータを所有しておらず、共有データを変更することは許可されていません。

このモードでは、複数のパイプラインに接続されているレシーバーのファンアウトコネクタでの複製は行われません。この場合、すべてのパイプラインは同じ単一の共有データコピーを参照します。共有所有権モードで動作するパイプライン内のプロセッサーは、ConsumeTraces/ConsumeMetrics/ConsumeLogs 呼び出しを介して受信した元のデータを変更することが禁止されています。プロセッサーはデータを読み取ることはできますが、データを変更してはなりません。

プロセッサーが処理中にデータを変更する必要があるが、排他的モードによって発生するデータ複製のコストを避けたい場合、プロセッサーはデータを変更しないと宣言し、元のデータが変更されないことを保証する他の方法を使用できます。例えば、プロセッサーは pdata.Traces/pdata.Metrics/pdata.Logs 引数の個々のサブパーツに対してコピーオンライト方式を実装することができます。元の pdata.Traces/pdata.Metrics/pdata.Logs を変更しない方法であれば、どのようなアプローチでも許可されています。

プロセッサーがこのような手法を使用する場合、MutatesData=false と設定することで、元のデータを変更する意図がないことを宣言し、排他的所有権のためにパイプラインをマークすることや、排他的所有権セクションで説明されているデータ複製のコストを避けることができます。

プロセッサーの順序

パイプライン内でプロセッサーが指定される順序は重要です。これは、各プロセッサーが適用される順序です。

nomadblackynomadblacky

Attributes Processor (Contrib)

https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/attributesprocessor

Attributes Processor

ステータス
安定性 beta: traces, metrics, logs
配布物 core, contrib
警告 Identity Conflict
問題点 Open issues Closed issues
コードオーナー @boostchicken

Attributes processorは、スパン、ログ、またはメトリックの属性を変更します。設定仕様については、config.go を参照してください。

このプロセッサーは、入力データをフィルターし、一致させて指定されたアクションに対して含めるか除外するかを判断する機能もサポートしています。

このプロセッサーは、設定に指定された順序で実行されるアクションのリストを受け取ります。サポートされているアクションは次の通りです:

  • insert: キーが既に存在しない場合、入力データに新しい属性を挿入します。
  • update: キーが既に存在する場合、入力データ内の属性を更新します。
  • upsert: 挿入または更新を行います。キーが既に存在しない場合は新しい属性を挿入し、キーが存在する場合は属性を更新します。
  • delete: 入力データから属性を削除します。
  • hash: 既存の属性値をハッシュ化（SHA1）します。
  • extract: 正規表現ルールを使用して入力キーからターゲットキーに指定された値を抽出します。ターゲットキーが既に存在する場合、それは上書きされます。注: これは、既存の属性をソースとしているSpan Processorのto_attributes設定と同様に動作します。
  • convert: 既存の属性を指定された型に変換します。

insert、update、upsertのアクションについて、

  • key が必要です
  • value、from_attribute または from_context のいずれかが必要です
  • action が必要です。
  # Keyは、操作対象の属性を指定します。
- key: <key>
  action: {insert, update, upsert}
  # Valueは、キーに対して設定する値を指定します。
  # 型は設定から推測されます。
  value: <value>

  # Keyは、操作対象の属性を指定します。
- key: <key>
  action: {insert, update, upsert}
  # FromAttributeは、入力データから値を設定するために使用する属性を指定します。
  # 属性が存在しない場合、アクションは実行されません。
  from_attribute: <other key>

  # Keyは、操作対象の属性を指定します。
- key: <key>
  action: {insert, update, upsert}
  # FromContextは、属性値を設定するために使用するコンテキスト値を指定します。
  # キーが `metadata.` で始まる場合、値は受信者のトランスポートプロトコルの追加情報（gRPCメタデータやHTTPヘッダーなど）から検索されます。
  # キーが `auth.` で始まる場合、値はサーバー認証者によって設定された認証情報から検索されます。
  # パイプラインの一部であるサーバー認証者のドキュメントを参照して、利用可能な属性について詳細を確認してください。
  # キーが `client.address` の場合、クライアントアドレスが設定されます。
  # キーが存在しない場合、アクションは実行されません。
  # キーに複数の値がある場合、値は `;` で結合されます。
  from_context: <other key>

deleteアクションについて、

  • key および/または pattern が必要です
  • action: delete が必要です。
# Keyは、操作対象の属性を指定します。
- key: <key>
  action: delete
  # Ruleは、操作対象の属性名に対する正規表現パターンを指定します。
  pattern: <regular pattern>

hashアクションについて、

  • key および/または pattern が必要です
  • action: hash が必要です。
# Keyは、操作対象の属性を指定します。
- key: <key>
  action: hash
  # Ruleは、操作対象の属性名に対する正規表現パターンを指定します。
  pattern: <regular pattern>

extractアクションについて、

  • key が必要です
  • pattern が必要です。
 # Keyは、値を抽出する属性を指定します。
 # `key`の値は変更されません。
- key: <key>
  # Ruleは、`key`の値から属性を抽出するために使用される正規表現パターンを指定します。
  # サブマッチャーは名前付きでなければなりません。
  # 属性が既に存在する場合、それは上書きされます。
  pattern: <regular pattern with named matchers>
  action: extract

convertアクションについて、

  • key が必要です
  • action: convert が必要です
  • converted_type が必要で、int、double、stringのいずれかでなければなりません
# Keyは、操作対象の属性を指定します。
- key: <key>
  action: convert
  converted_type: <int|double|string>

これらのアクションのリストは、属性のバックフィルや新しいキーへのコピー、機密情報の編集などの複雑なシナリオを作成するために組み合わせることができます。以下は、サンプルの設定です。

processors:
  attributes/example:
    actions:
      - key: db.table
        action: delete
      - key: redacted_span
        value: true
        action: upsert
      - key: copy_key
        from_attribute: key_original
        action: update
      - key: account_id
        value: 2245
        action: insert
      - key: account_password
        action: delete
      - key: account_email
        action: hash
      - key: http.status_code
        action: convert
        converted_type: int

詳細な例については、config.yamlを参照してください。

メトリクス用のAttributes ProcessorとMetric Transform Processorの比較

メトリクスサポートに関しては、これら二つのプロセッサーは機能が重複しています。どちらもメトリック属性のキーと値のペアを単純に修正できます。一般的なルールとして、属性プロセッサーは属性に関連する機能が多く、メトリクストランスフォームプロセッサーはより多くのデータ操作が可能です。必要な機

能が重複している場合は、公式のOpenTelemetryデータモデルをネイティブに使用するため、属性プロセッサーが推奨されます。ただし、メトリクストランスフォームプロセッサーが既に使用されている場合や、追加の機能が必要な場合は、移行する必要はありません。

共通機能

  • 属性の追加
  • 属性値の更新

属性プロセッサー特有の機能

  • 削除
  • ハッシュ化
  • 抽出

メトリクストランスフォームプロセッサー特有の機能

  • メトリックの名前変更
  • データポイントの削除
  • データ型の切り替え
  • 値のスケーリング
  • ラベルセット間での集計
  • ラベル値間での集計

インクルード/エクスクルードフィルタリング

属性プロセッサーは、入力データがプロセッサーに含まれるべきか、または除外されるべきかを判断するために、スパン、ログ、またはメトリックレコードのプロパティのセットを提供するオプションを公開しています。このオプションを設定するには、includeおよび/またはexcludeの下で、少なくともmatch_typeと以下のいずれかが必要です:

  • スパンの場合、services、span_names、span_kinds、attributes、resources、librariesのいずれかが指定され、有効な設定には非空の値が必要です。log_bodies、log_severity_texts、log_severity_number、metric_namesフィールドは無効です。
  • ログの場合、log_bodies、log_severity_texts、log_severity_number、attributes、resources、librariesのいずれかが指定され、有効な設定には非空の値が必要です。span_names、span_kinds、metric_names、servicesフィールドは無効です。
  • メトリクスの場合、metric_namesまたはresourcesのいずれかが指定され、非空の値が有効な設定には必要です。span_names、span_kinds、log_bodies、log_severity_texts、log_severity_number、services、attributes、librariesフィールドは無効です。

注: includeとexcludeの両方が指定されている場合、includeプロパティはexcludeプロパティよりも先にチェックされます。

attributes:
    # includeおよび/またはexcludeを指定できます。ただし、includeプロパティは常にexcludeプロパティよりも先にチェックされます。
    {include, exclude}:
      # services、span_namesまたはattributesのいずれかを指定する必要があります。
      # 1つ以上指定することができますが、すべての指定された条件が一致する必要があります。

      # match_typeは、"services"、"span_names"、および"attributes"配列内の項目が解釈される方法を制御します。可能な値は"regexp"または"strict"です。
      # これは必須フィールドです。
      match_type: {strict, regexp}

      # regexpは、match_typeがregexpの場合のオプション設定セクションです。
      regexp:
        # <以下の"Match Configuration"を参照>

      # servicesは、サービス名と一致させるための項目の配列を指定します。
      # スパンのサービス名が項目の少なくとも1つと一致する場合、一致が発生します。
      # これはオプションフィールドです。
      services: [<item1>, ..., <itemN>]

      # resourcesは、一致させるリソースのリストを指定します。
      # 入力データのリソースが項目の少なくとも1つと一致する場合、一致が発生します。
      # これはオプションフィールドです。
      resources:
          # Keyは、一致させるリソースを指定します。
        - key: <key>
          # Valueは、一致させる正確な値を指定します。
          # 指定されていない場合、リソースにキーが存在する場合に一致が発生します。
          value: {value}

      # librariesは、実装ライブラリと一致させる項目のリストを指定します。
      # 入力データの実装ライブラリが項目の少なくとも1つと一致する場合、一致が発生します。
      # これはオプションフィールドです。
      libraries: [<item1>, ..., <itemN>]
          # Nameは、一致させるライブラリを指定します。
        - name: <name>
          # Versionは、一致させる正確なバージョンを指定します。
          # これはオプションフィールドです。
          # フィールドが設定されていない場合、任意のバージョンが一致します。
          # フィールドが空文字列に設定されている場合、空文字列のバージョンのみが一致します。
          version: {version}

      # スパン名は、少なくとも1つの項目と一致しなければなりません。
      # これはオプションフィールドです。
      span_names: [<item1>, ..., <itemN>]

      # スパンの種類は、少なくとも1つの項目と一致しなければなりません。
      # これはオプションフィールドです。
      span_kinds: [<item1>, ..., <itemN>]

      # ログの本文は、少なくとも1つの項目と一致しなければなりません。
      # 現在、文字列型の本文のみがサポートされています。
      # これはオプションフィールドです。
      log_bodies: [<item1>, ..., <itemN>]

      # ログの重大度テキストは、少なくとも1つの項目と一致しなければなりません。
      # これはオプションフィールドです。
      log_severity_texts: [<item1>, ..., <itemN>]

      # ログの重大度番号は、ログレコードのSeverityNumberと一致させる方法を定義します。
      # これはオプションフィールドです。
      log_severity_number:
        # Minは、一致する可能性のある最低の重大度です。
        # 例: これがplog.SeverityNumberInfoの場合、INFO、WARN、ERROR、およびFATALのログが一致します。
        min: <int>
        # MatchUndefinedは、"未定義"の重大度を持つログが一致するかどうかを制御します。
        # これがtrueの場合、未定義の重大度を持つエントリが一致します。
        match_undefined: <bool>

      # メトリック名は、少なくとも1つの項目と一致しなければなりません。
      # これはオプションフィールドです。
      metric_names: [<item1>, ..., <itemN>]

      # Attributesは、一致させる属性のリストを指定します。
      # これらの属性がすべて一致する必要があります。
      # これはオプションフィールドです。
      attributes:
          # Keyは、一致させる属性を指定します。
        - key: <key>
          # Valueは、一致させる値を指定します。
          # 指定されていない場合、属性にキーが存在する場合に一致が発生します。
          value: {value}

一致設定

いくつかのmatch_type値には、追加の設定オプションを指定することができます。match_type値は、設定セクションの名前です。これらのセクションは任意です。

# regexpは、match_typeがregexpの場合のオプション設定セクションです。
regexp:
  # cacheenabledは、一致結果をLRUキャッシュに格納し、次回の一致を高速化するかどうかを決定します。
  # キャッシュサイズは、cachemaxnumentriesが指定されていない限り無制限です。
  cacheenabled: <bool>
  # cachemaxnumentriesは、LRUキャッシュの最大エントリ数です。cacheenabledがfalseの場合は無視されます。
  cachemaxnumentries: <int>

警告

一般的に、Attributes Processorは非常に安全なプロセッサーです。データポイント属性を変更する際にのみ注意が必要です:

nomadblackynomadblacky

Memory Limitter Processor

https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor

概要

メモリ リミッター プロセッサは、コレクターのメモリ不足状態を防ぐために使用されます。コレクターが処理するデータの量とタイプは環境によって異なり、コレクターのリソース使用率も構成されたプロセッサに依存するため、メモリ使用量に関するチェックを実施することが重要です。

機能

メモリ リミッター プロセッサは、メモリ使用量を定期的にチェックし、定義された制限を超えるとデータを拒否し、GC にメモリ消費を減らすよう強制します。

プロセッサは、ソフト メモリ制限とハード メモリ制限を使用します。ハード制限は、limit_mib 構成オプションで定義され、常にソフト制限以上になります。ソフト制限とハード制限の差は、spike_limit_mib 構成オプションで定義されます。

メモリ使用量がソフト制限を超えると、プロセッサはメモリ制限モードに入り、データを拒否し始めます。これは、ConsumeLogs/Trace/Metrics 関数呼び出しを行ったパイプライン内の先行コンポーネントにエラーを返すことによって行われます。

メモリ制限モードでは、ConsumeLogs/Trace/Metrics 関数によって返されるエラーは非永続的なエラーです。受信者がこのエラーを確認すると、同じデータの送信を再試行することが期待されます。受信者は、コレクターへのデータの流入を遅くし、メモリ使用量が設定された制限を下回るように、独自のデータ ソースにバックプレッシャーを適用することもあります。

警告: テレメトリ パイプライン内のメモリ リミッターの先行コンポーネントが、メモリ リミッターによって拒否された後にデータの送信を正しく再試行しないと、データは永久に失われます。
このようなコンポーネントは正しく実装されていないとみなされます。

メモリ使用量がハード リミットを超えると、プロセッサはガベージ コレクションをさらに強制的に実行します。

メモリ使用量がソフト リミットを下回ると、通常の操作が再開されます。つまり、データは拒否されなくなり、プロセッサはガベージ コレクションを強制的に実行しません。

ベスト プラクティス

プロセッサはメモリ不足の状況を軽減するのに役立ちますが、コレクターの適切なサイズ設定と構成に代わるものではないことに注意してください。ソフト リミットを超えると、十分なメモリが解放されるまで、コレクターはすべての受信操作にエラーを返すことに注意してください。これにより、レシーバーがデータを無期限に再試行できなくなる可能性があるため、最終的にデータがドロップされる可能性があります。

すべてのコレクターで GOMEMLIMIT 環境変数 と memory_limiter プロセッサを構成することを強くお勧めします。GOMEMLIMIT は、コレクターのハード メモリ制限の 80% に設定する必要があります。memory_limiter プロセッサの場合、ベスト プラクティスは、パイプラインの最初のプロセッサとして追加することです。これは、バックプレッシャーが適切な受信者に送信され、memory_limiter がトリガーされたときにデータがドロップされる可能性を最小限に抑えるためです。

spike_limit_mib 構成オプションの値は、1 回のメモリ チェック間隔内でメモリ使用量がこの値を超えて増加しないように選択する必要があります。そうしないと、一時的であってもメモリ使用量がハード リミットを超える可能性があります。
spike_limit_mib の適切な開始点は、ハード リミットの 20% です。スパイクの多いトラフィックやチェック間隔が長い場合は、より大きな spike_limit_mib 値が必要になる場合があります。

構成

構成仕様については、memorylimiter.go を参照してください。

次の構成オプションは変更する必要があります:

  • check_interval (デフォルト = 0s): メモリ使用量の測定間隔。推奨値は 1 秒です。
    コレクターへのトラフィックが急増すると予想される場合は、check_interval を減らすか、spike_limit_mib を増やして、メモリ使用量がハード リミットを超えないようにしてください。
  • limit_mib (デフォルト = 0): プロセス ヒープによって割り当てられるメモリの最大量 (MiB 単位)。通常、プロセスの合計メモリ使用量はこの値より約 50MiB 高くなります。これがハード リミットを定義します。
  • spike_limit_mib (デフォルト = limit_mib の 20%): メモリ使用量の測定間で予想される最大スパイク。値は limit_mib より小さくする必要があります。ソフト制限値は (limit_mib - spike_limit_mib) と等しくなります。
    spike_limit_mib の推奨値は limit_mib の約 20% です。
  • limit_percentage (デフォルト = 0): プロセス ヒープによって割り当てられる合計メモリの最大量。この構成は cgroups を備えた Linux システムでサポートされており、docker などの動的プラットフォームで使用することを目的としています。
    このオプションは、使用可能な合計メモリから memory_limit を計算するために使用されます。
    たとえば、合計メモリが 1GiB で 75% に設定すると、制限は 750 MiB になります。
    固定メモリ設定 (limit_mib) は、パーセンテージ構成よりも優先されます。
  • spike_limit_percentage (デフォルト = 0): メモリ使用量の測定間で予想される最大スパイク。値は limit_percentage より小さくなければなりません。
    このオプションは、使用可能なメモリの合計から spike_limit_mib を計算するために使用されます。
    たとえば、合計メモリが 1GiB で 25% に設定すると、スパイク制限は 250MiB になります。
    このオプションは limit_percentage でのみ使用することを目的としています。

例:

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 4000
    spike_limit_mib: 800

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 50
    spike_limit_percentage: 30

プロセッサの使用に関する詳細な例については、config.yaml を参照してください。

nomadblackynomadblacky

Batch Processor

https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor

ステータス
安定性 beta: traces, metrics, logs
配布物 core, contrib, k8s
問題点 Open issues Closed issues

バッチプロセッサーは、スパン、メトリック、またはログを受け取り、それらをバッチにまとめます。バッチ処理は、データをより効率的に圧縮し、データの送信に必要な外部接続の数を減らすのに役立ちます。このプロセッサーは、サイズベースおよび時間ベースのバッチ処理の両方をサポートしています。

すべてのコレクターでバッチプロセッサーを構成することを強く推奨します。バッチプロセッサーは、memory_limiter およびサンプリングプロセッサーの後にパイプラインで定義する必要があります。これは、サンプリングなどのデータドロップが行われた後にバッチ処理が行われるべきだからです。

設定仕様については、config.go を参照してください。

次の設定オプションを変更できます：

  • send_batch_size（デフォルト = 8192）：バッチが送信されるスパン、メトリックデータポイント、またはログレコードの数。この設定は、タイムアウトに関係なくバッチを送信するトリガーとして機能し、バッチのサイズには影響しません。パイプライン内の次のコンポーネントに送信されるバッチサイズの制限を適用する必要がある場合は、send_batch_max_sizeを参照してください。
  • timeout（デフォルト = 200ms）：タイムアウトに関係なくバッチが送信されるまでの時間。ゼロに設定されている場合、send_batch_sizeは無視され、データは直ちに送信され、send_batch_max_sizeのみに依存します。
  • send_batch_max_size（デフォルト = 0）：バッチサイズの上限。0はバッチサイズに上限がないことを意味します。このプロパティは、大きなバッチがより小さな単位に分割されることを保証します。send_batch_size以上でなければなりません。
  • metadata_keys（デフォルト = 空）：設定すると、このプロセッサーはclient.Metadata内の値の異なる組み合わせごとに1つのバッチャーインスタンスを作成します。
  • metadata_cardinality_limit（デフォルト = 1000）：metadata_keysが空でない場合、この設定により、プロセスの生涯にわたって処理されるメタデータキー値のユニークな組み合わせの数が制限されます。

以下にメタデータバッチ処理に関する注意点を記載します。

例：

この構成には、デフォルトのバッチプロセッサーとカスタム設定を持つ2つ目のバッチプロセッサーが含まれています。batch/2プロセッサーは、データ項目を分割せずに最大10,000のスパン、メトリックデータポイント、またはログレコードを最大10秒間バッファリングします。

processors:
  batch:
  batch/2:
    send_batch_size: 10000
    timeout: 10s

この構成では、任意の人工的な遅延を導入することなく、最大10,000のスパン、メトリックデータポイント、またはログレコードのバッチサイズ制限が適用されます。

processors:
  batch:
    send_batch_max_size: 10000
    timeout: 0s

プロセッサーの使用に関する詳細な例については、config.yamlを参照してください。

バッチ処理とクライアントメタデータ

メタデータによるバッチ処理は、同じ認証メタデータを持つデータのグループをバッチ処理することで、マルチテナントのOpenTelemetry Collectorパイプラインをサポートします。例えば：

processors:
  batch:
    # テナントIDごとにデータをバッチ処理
    metadata_keys:
    - tenant_id

    # エラーを発生させる前にバッチャープロセスを10個に制限
    metadata_cardinality_limit: 10

レシーバーはinclude_metadata: trueで構成され、メタデータキーがプロセッサーに利用可能になるようにする必要があります。

メタデータの異なる組み合わせがそれぞれ新しいバックグラウンドタスクをトリガーすることに注意してください。これらのタスクはプロセスのライフタイムにわたって実行され、各バックグラウンドタスクは最大send_batch_sizeレコードの保留中のバッチを保持します。したがって、メタデータによるバッチ処理は、バッチ処理に専念するメモリ量を大幅に増加させる可能性があります。

ユニークな組み合わせの最大数は、デフォルトでメモリ影響を制限するために1000に設定されているmetadata_cardinality_limitに制限されています。

メタデータキーを使用して構成されたバッチプロセッサーのユーザーは、関連するメタデータキー値を検証するためにAuth拡張機能の使用を検討する必要があります。

現在使用されているバッチプロセッサーの数は、otelcol_processor_batch_metadata_cardinalityメトリックとしてエクスポートされます。

nomadblackynomadblacky

Prometheus Exporter

https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusexporter

ステータス
安定性 beta: metrics
配布物 core, contrib
問題点 Open issues Closed issues
コードオーナー @Aneurysm9, @dashpole

このエクスポーターは、Prometheusフォーマットでデータをエクスポートし、Prometheusサーバーがデータを収集できるようにします。

はじめに

以下の設定が必須です：

  • endpoint（デフォルトなし）：メトリクスが /metrics パスを使用して公開されるアドレス。ServerConfig の完全なリストについてはこちらを参照してください。

以下の設定は任意で構成できます：

  • const_labels（デフォルトなし）：すべてのエクスポートされたメトリクスに適用されるキー/値。
  • namespace（デフォルトなし）：設定すると、指定された値の下でメトリクスがエクスポートされます。
  • send_timestamps（デフォルト = false）：trueに設定すると、応答に基づいたメトリクスサンプルのタイムスタンプを送信します。
  • metric_expiration（デフォルト = 5m）：更新なしでメトリクスが公開される時間を定義します。
  • resource_to_telemetry_conversion
    • enabled（デフォルト = false）：enabledがtrueの場合、すべてのリソース属性がデフォルトでメトリクスラベルに変換されます。
  • enable_open_metrics：（デフォルト = false）：trueに設定すると、メトリクスがOpenMetricsフォーマットでエクスポートされます。エグゼンプラはOpenMetricsフォーマットでのみエクスポートされ、ヒストグラムとモノトニックサム（つまり、カウンタ）メトリクスに対してのみエクスポートされます。
  • add_metric_suffixes：（デフォルト = true）：falseに設定すると、タイプおよび単位のサフィックスの追加が無効になります。

例：

exporters:
  prometheus:
    endpoint: "1.2.3.4:1234"
    tls:
      ca_file: "/path/to/ca.pem"
      cert_file: "/path/to/cert.pem"
      key_file: "/path/to/key.pem"
    namespace: test-space
    const_labels:
      label1: value1
      "another label": spaced value
    send_timestamps: true
    metric_expiration: 180m
    enable_open_metrics: true
    add_metric_suffixes: false
    resource_to_telemetry_conversion:
      enabled: true

この例では、メトリクスは https://1.2.3.4:1234/metrics で利用可能になります。

メトリクス名とラベルの正規化

OpenTelemetryのメトリクス名と属性は、Prometheusの命名規則に準拠するように正規化されます。この正規化プロセスの詳細は、Prometheusトランスレーターモジュールで説明されています（こちら）。

リソース属性をメトリクスラベルとして設定

デフォルトでは、リソース属性は target_info と呼ばれる特別なメトリクスに追加されます。リソース属性ごとにメトリクスを選択しグループ化するには、target_info でジョインを行う必要があります。例えば、k8s_namespace_name 属性が my-namespace に等しいメトリクスを選択するには、次のようにします：

app_ads_ad_requests_total * on (job, instance) group_left target_info{k8s_namespace_name="my-namespace"}

または、特定の属性（例：k8s_namespace_name）でグループ化するには：

sum by (k8s_namespace_name) (app_ads_ad_requests_total * on (job, instance) group_left(k8s_namespace_name) target_info)

これは一般的なパターンではないため、最も一般的なリソース属性をメトリクスラベルにコピーすることをお勧めします。これを行うには、トランスフォームプロセッサーを使用します：

processor:
  transform:
    metric_statements:
      - context: datapoint
        statements:
        - set(attributes["namespace"], resource.attributes["k8s.namespace.name"])
        - set(attributes["container"], resource.attributes["k8s.container.name"])
        - set(attributes["pod"], resource.attributes["k8s.pod.name"])

この後、グループ化や選択は次のように簡単になります：

app_ads_ad_requests_total{namespace="my-namespace"}

sum by (namespace) (app_ads_ad_requests_total)
nomadblackynomadblacky

Prometheus Remote Write Exporter

https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusremotewriteexporter

ステータス
安定性 ベータ版: メトリクス
ディストリビューション コア, 貢献
イシュー オープンイシュー クローズドイシュー
コードオーナー @Aneurysm9, @rapphil, @dashpole

Prometheus Remote Write Exporter は、OpenTelemetry のメトリクスを Prometheus のリモート書き込み互換のバックエンド（例えば Cortex、Mimir、Thanos）に送信します。デフォルトでは、このエクスポーターは TLS を必要とし、キューイングと再試行機能を提供します。

:warning: 非累積単調、ヒストグラム、およびサマリーの OTLP メトリクスは、このエクスポーターによって破棄されます。

このエクスポーターの詳細な動作については、設計ドキュメントが利用可能です。

はじめに

次の設定は必須です：

  • endpoint（デフォルトなし）：リモート書き込みサンプルを送信するためのリモート書き込み URL。

デフォルトでは、TLS が有効になっており、tls:の下で設定する必要があります：

  • insecure（デフォルト = false）：エクスポーターの接続に対してクライアントトランスポートセキュリティを有効にするかどうか。

その結果、次のパラメータも tls: の下で必須となります：

  • cert_file（デフォルトなし）：TLS が必要な接続に使用する TLS 証明書のパス。insecure が false に設定されている場合にのみ使用してください。
  • key_file（デフォルトなし）：TLS が必要な接続に使用する TLS キーのパス。insecure が false に設定されている場合にのみ使用してください。

次の設定はオプションで構成できます：

  • external_labels：各メトリクスデータポイントに添付されるラベル名と値のマップ
  • headers：各 HTTP リクエストに添付される追加のヘッダー。
    • 以下のヘッダーは変更できません：Content-Encoding, Content-Type, X-Prometheus-Remote-Write-Version, User-Agent。
  • namespace：エクスポートされた各メトリクス名に添付されるプレフィックス。
  • add_metric_suffixes：false に設定した場合、メトリクスにタイプおよびユニットのサフィックスが追加されません。デフォルト：true。
  • send_metadata：true に設定すると、Prometheus のメタデータが生成され送信されます。デフォルト：false。
  • remote_write_queue：送信キューとリモート書き込みの微調整。
    • enabled：送信キューを有効にする（デフォルト：true）
    • queue_size：キューにできる OTLP メトリクスの数。enabled が false の場合は無視される（デフォルト：10000）
    • num_consumers：送信要求を分散するために使用する最小のワーカー数。（デフォルト：5）
  • resource_to_telemetry_conversion
    • enabled（デフォルト = false）：enabled が true に設定されている場合、すべてのリソース属性がデフォルトでメトリクスラベルに変換されます。
  • target_info：target_info メトリクスのカスタマイズ
  • export_created_metric：
    • enabled（デフォルト = false）：enabled が true に設定されている場合、StartTimeUnixNano が設定されている場合、Summary、Histogram、Monotonic Sum メトリクスポイントに対して _created メトリクスがエクスポートされます。
  • max_batch_size_bytes（デフォルト = 3000000 -> 約2.861 MB）：リモート書き込みエンドポイントに送信されるサンプルの最大バッチサイズ。この値より大きい場合、バッチは複数に分割されます。

例:

exporters:
  prometheusremotewrite:
    endpoint: "https://my-cortex:7900/api/v1/push"
    wal: # エクスポーターの Write-Ahead-Log を有効にします。
      directory: ./prom_rw # WAL を保存するディレクトリ
      buffer_size: 100 # WAL から読み取られる要素のオプション数; デフォルトは 300
      truncate_frequency: 45s # WAL を切り捨てる頻度のオプション設定。time.ParseDuration; デフォルトは 1m
    resource_to_telemetry_conversion:
      enabled: true # リソース属性をメトリクスラベルに変換

例:

exporters:
  prometheusremotewrite:
    endpoint: "https://my-cortex:7900/api/v1/push"
    external_labels:
      label_name1: label_value1
      label_name2: label_value2

高度な設定

いくつかのヘルパーファイルが使用され、自動的に追加機能が提供されます：

機能ゲート

このエクスポーターには機能ゲートがあります：exporter.prometheusremotewritexporter.RetryOn429。
この機能ゲートが有効になると、Prometheus Remote Write Exporter は HTTP ステータスコード 429 で再試行します。提供された再試行設定で再試行します。
現在、この機能は提供された場合でも HTTP ヘッダー Retry-After を尊重することをサポートしていません。これは使用されている再試行ライ

ブラリがこの機能をサポートしていないためです。

機能ゲート exporter.prometheusremotewritexporter.RetryOn429 を有効にしてコレクターを実行します。これは、追加のパラメーター --feature-gates=telemetry.useOtelForInternalMetrics を指定して実行することで実現できます。

メトリクス名とラベルの正規化

OpenTelemetry メトリクス名と属性は、Prometheus の命名ルールに準拠するように正規化されます。この正規化プロセスの詳細は、Prometheus 翻訳モジュールで説明されています。

リソース属性をメトリクスラベルとして設定する

デフォルトでは、リソース属性は target_info と呼ばれる特別なメトリクスに追加されます。リソース属性でメトリクスを選択およびグループ化するには、target_info で結合する必要があります。例えば、k8s_namespace_name 属性が my-namespace と等しいメトリクスを選択するには、次のようにします：

app_ads_ad_requests_total * on (job, instance) group_left target_info{k8s_namespace_name="my-namespace"}

または、特定の属性（例：k8s_namespace_name）でグループ化するには、次のようにします：

sum by (k8s_namespace_name) (app_ads_ad_requests_total * on (job, instance) group_left(k8s_namespace_name) target_info)

これは一般的なパターンではないため、最も一般的なリソース属性をメトリクスラベルにコピーすることをお勧めします。これを transform プロセッサーを通じて行うことができます：

processor:
  transform:
    metric_statements:
      - context: datapoint
        statements:
        - set(attributes["namespace"], resource.attributes["k8s.namespace.name"])
        - set(attributes["container"], resource.attributes["k8s.container.name"])
        - set(attributes["pod"], resource.attributes["k8s.pod.name"])

これにより、グループ化や選択が次のように簡単になります：

app_ads_ad_requests_total{namespace="my-namespace"}

sum by (namespace) (app_ads_ad_requests_total)
nomadblackynomadblacky

以下は、Markdownを日本語に翻訳したものです。

Resource Detection Processor

https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md#supported-detectors

ステータス
安定性 ベータ版: トレース、メトリクス、ログ
ディストリビューション 貢献, k8s
イシュー オープンイシュー クローズドイシュー
コードオーナー @Aneurysm9, @dashpole

Resource Detection Processor は、ホストからリソース情報を検出し、それを OpenTelemetry リソースセマンティック規約 に準拠した形式で取得して、テレメトリーデータにこの情報を追加または上書きするために使用されます。

対応している検出器

環境変数

OTEL_RESOURCE_ATTRIBUTES 環境変数からリソース情報を読み取ります。この形式は <key1>=<value1>,<key2>=<value2>,... であることが期待されており、詳細は現在 OpenTelemetry 仕様で確認中です。

例:

processors:
  resourcedetection/env:
    detectors: [env]
    timeout: 2s
    override: false

システムメタデータ

注: コレクターを Docker コンテナとして実行する場合は、以下の Docker 検出器を使用してください。

ホストマシンから次のリソース属性を取得します：

* host.arch
* host.name
* host.id
* host.ip
* host.mac
* host.cpu.vendor.id
* host.cpu.family
* host.cpu.model.id
* host.cpu.model.name
* host.cpu.stepping
* host.cpu.cache.l2.size
* os.description
* os.type

デフォルトでは host.name は可能であれば FQDN に設定され、OS によって提供されるホスト名がフォールバックとして使用されます。このロジックは hostname_sources 設定で変更でき、デフォルトでは ["dns", "os"] に設定されています。

FQDN を取得せず、OS によって提供されるホスト名のみを適用するには、以下の設定を使用します：

processors:
  resourcedetection/system:
    detectors: ["system"]
    system:
      hostname_sources: ["os"]
  • hostname_sources に対するすべての有効なオプション:
    • "dns"
    • "os"
    • "cname"
    • "lookup"

ホスト名ソース

dns

"dns" ホスト名ソースは、完全修飾ドメイン名を取得するために複数のソースを使用します。最初に、ローカルマシンの hosts ファイルでホスト名を検索します。それが失敗した場合は、CNAME を検索します。最後に、それが失敗した場合は、リバース DNS クエリを実行します。注: このホスト名ソースは Windows では信頼性の低い結果を生成する可能性があります。完全修飾ドメイン名を生成するには、Windows ホストは、以下に述べる "lookup" ホスト名ソースを使用することでより良い結果が得られる可能性があります。

os

"os" ホスト名ソースは、ローカルマシンのカーネルによって提供されるホスト名を提供します。

cname

"cname" ホスト名ソースは、Go 標準ライブラリの net.LookupCNAME によって提供されるカノニカル名を提供します。注: このホスト名ソースは Windows では信頼性の低い結果を生成する可能性があります。

lookup

"lookup" ホスト名ソースは、現在のホストの IP アドレスのリバース DNS ルックアップを行います。

Docker メタデータ

ホストマシンから次のリソース属性を取得するために Docker デーモンを照会します：

* host.name
* os.type

Docker デーモンに接続するには、Docker ソケット（Linux では /var/run/docker.sock）をマウントする必要があります。Docker 検出は macOS では動作しません。

例:

processors:
  resourcedetection/docker:
    detectors: [env, docker]
    timeout: 2s
    override: false

Heroku メタデータ

Heroku dyno メタデータが有効な場合、Heroku アプリケーションは環境変数を通じて情報を公開します。

これらの環境変数を次のようにリソース属性にマッピングします：

Dyno メタデータ環境変数 リソース属性
HEROKU_APP_ID heroku.app.id
HEROKU_APP_NAME service.name
HEROKU_DYNO_ID service.instance.id
HEROKU_RELEASE_CREATED_AT heroku.release.creation_timestamp
HEROKU_RELEASE_VERSION service.version
HEROKU_SLUG_COMMIT heroku.release.commit

詳細については、OpenTelemetry 仕様のセマンティック規約の下にある Heroku クラウドプロバイダーのドキュメントを参照してください。

processors:
  resourcedetection/heroku:
    detectors: [env, heroku]
    timeout: 2s
    override: false

GCP メタデータ

Google Cloud クライアントライブラリ for Go を使用して、メタデータサーバーおよび環境変数からリソース情報を読み取り、アプリケーションが実行されている GCP プラットフォームを検出し、そのプラットフォームに適した属性を検出します。アプリケーションが実行されている GCP プラットフォームに関係なく、gcp 検出器を使用してください。

例:

processors:
  resourcedetection/gcp:
    detectors: [env, gcp]
    timeout: 2s
    override: false

GCE メタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_compute_engine")
* cloud.account.id (プロジェクトID)
* cloud.region  (例: us-central1)
* cloud.availability_zone (例: us-central1-c)
* host.id (インスタンスID)
* host.name (インスタンス名)
* host.type (マシンタイプ)
* (オプション) gcp.gce.instance.hostname
* (オプション) gcp.g

ce.instance.name

GKE メタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_kubernetes_engine")
* cloud.account.id (プロジェクトID)
* cloud.region (リージョナル GKE クラスターの場合のみ; 例: "us-central1")
* cloud.availability_zone (ゾーン GKE クラスターの場合のみ; 例: "us-central1-c")
* k8s.cluster.name
* host.id (インスタンスID)
* host.name (インスタンス名; ワークロードアイデンティティが無効な場合のみ)

ワークロードアイデンティティが有効な場合、GCE メタデータエンドポイントは利用できず、host.name を検出できません。その場合、次の方法で host.name を設定することが推奨されます：

  • node.name を downward API で env 検出器を使用して取得する
  • Kubernetes API（k8s.io/client-go を使用）から Kubernetes ノード名を取得する

Google Cloud Run サービスメタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_cloud_run")
* cloud.account.id (プロジェクトID)
* cloud.region (例: "us-central1")
* faas.id (インスタンスID)
* faas.name (サービス名)
* faas.version (サービスリビジョン)

Cloud Run ジョブメタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_cloud_run")
* cloud.account.id (プロジェクトID)
* cloud.region (例: "us-central1")
* faas.id (インスタンスID)
* faas.name (サービス名)
* gcp.cloud_run.job.execution ("my-service-ajg89")
* gcp.cloud_run.job.task_index ("0")

Google Cloud Functions メタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_cloud_functions")
* cloud.account.id (プロジェクトID)
* cloud.region (例: "us-central1")
* faas.id (インスタンスID)
* faas.name (関数名)
* faas.version (関数バージョン)

Google App Engine メタデータ

* cloud.provider ("gcp")
* cloud.platform ("gcp_app_engine")
* cloud.account.id (プロジェクトID)
* cloud.region (例: "us-central1")
* cloud.availability_zone (例: "us-central1-c")
* faas.id (インスタンスID)
* faas.name (サービス名)
* faas.version (サービスバージョン)

AWS EC2

AWS SDK for Go を使用して、EC2 インスタンスメタデータ API からリソース情報を読み取り、次のリソース属性を取得します：

* cloud.provider ("aws")
* cloud.platform ("aws_ec2")
* cloud.account.id
* cloud.region
* cloud.availability_zone
* host.id
* host.image.id
* host.name
* host.type

また、コレクターが実行されている EC2 インスタンスのタグをオプションで取得できます。EC2 タグを取得するには、EC2 インスタンスに割り当てられた IAM ロールに ec2:DescribeTags 権限が含まれている必要があります。

EC2 カスタム構成例:

processors:
  resourcedetection/ec2:
    detectors: ["ec2"]
    ec2:
      # リソース属性として追加するタグキーに一致する正規表現のリストを指定できます
      tags:
        - ^tag1$
        - ^tag2$
        - ^label.*$

EC2 インスタンスでプロキシサーバーを使用している場合、AWS CLI ユーザーガイドに記載されているように、インスタンスメタデータへのリクエストをプロキシの対象外にする必要があります。これを行わないと、プロキシされたデータまたは欠落したインスタンスデータが発生する可能性があります。

インスタンスが AWS ParallelCluster の一部であり、検出器がメタデータサーバーに接続できない場合は、iptables を確認し、チェーン PARALLELCLUSTER_IMDS に OTEL ユーザーが 169.254.169.254/32 へのアクセスを許可するルールが含まれていることを確認してください。

Amazon ECS

タスクメタデータエンドポイント（TMDE）を照会して、現在の ECS タスクに関する情報を記録します。TMDE V4 および V3 のみがサポートされています。

* cloud.provider ("aws")
* cloud.platform ("aws_ecs")
* cloud.account.id
* cloud.region
* cloud.availability_zone
* aws.ecs.cluster.arn
* aws.ecs.task.arn
* aws.ecs.task.family
* aws.ecs.task.id
* aws.ecs.task.revision
* aws.ecs.launchtype (V4 のみ)
* aws.log.group.names (V4 のみ)
* aws.log.group.arns (V4 のみ)
* aws.log.stream.names (V4 のみ)
* aws.log.stream.arns (V4 のみ)

例:

processors:
  resourcedetection/ecs:
    detectors: [env, ecs]
    timeout: 2s
    override: false

Amazon Elastic Beanstalk

X-Ray を有効にしたすべての Beanstalk インスタンスで利用可能な AWS X-Ray 構成ファイルを読み取ります。

* cloud.provider ("aws")
* cloud.platform ("aws_elastic_beanstalk")
* deployment.environment
* service.instance.id
* service.version

例:

processors:
  resourcedetection/elastic_beanstalk:
    detectors: [env, elastic_beanstalk]
    timeout: 2s
    override: false

Amazon EKS

* cloud.provider ("aws")
* cloud.platform ("aws_eks")
* k8s.cluster.name

例:

processors:
  resourcedetection/eks:
    detectors: [env, eks]
    timeout: 15s
    override: false

クラスター名

クラスター名検出はデフォルトで無効になっており、次の設定で有効にできます：

processors:
  resourcedetection/eks:
    detectors: [env, eks]
    timeout: 15s
    override: false
    eks:
      resource_attributes:
        k8s.cluster.name:
          enabled: true

注: Kubernetes クラスター名は EC2 インスタンスでのみ利用可能であり、EC2:DescribeInstances アクションを実行する権限が必要です。
context deadline exceeded というエラーメッセージが表示された場合は、構成のタイムアウト設定を増やしてください。

AWS Lambda

AWS Lambda ランタイム環境変数を使用して、次のリソース属性を取得します：

クラウドセマンティック規約

  • cloud.provider ("aws")
  • cloud.platform ("aws_lambda")
  • cloud.region ($AWS_REGION)

関数としてのサービスセマンティック規約および AWS Lambda セマンティック規約

  • faas.name ($AWS_LAMBDA_FUNCTION_NAME)
  • faas.version ($AWS_LAMBDA_FUNCTION_VERSION)
  • faas.instance ($AWS_LAMBDA_LOG_STREAM_NAME)
  • faas.max_memory ($AWS_LAMBDA_FUNCTION_MEMORY_SIZE)

[AWS ログセマンティック規約](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/cloud-provider

/aws/logs.md)

  • aws.log.group.names ($AWS_LAMBDA_LOG_GROUP_NAME)
  • aws.log.stream.names ($AWS_LAMBDA_LOG_STREAM_NAME)

例:

processors:
  resourcedetection/lambda:
    detectors: [env, lambda]
    timeout: 0.2s
    override: false

Azure

Azure インスタンスメタデータサービス を照会して、次のリソース属性を取得します：

* cloud.provider ("azure")
* cloud.platform ("azure_vm")
* cloud.region
* cloud.account.id (サブスクリプションID)
* host.id (仮想マシンID)
* host.name
* azure.vm.name (host.name と同じ)
* azure.vm.size (仮想マシンサイズ)
* azure.vm.scaleset.name (スケールセット名、存在する場合)
* azure.resourcegroup.name (リソースグループ名)

例:

processors:
  resourcedetection/azure:
    detectors: [env, azure]
    timeout: 2s
    override: false

また、コレクターが実行されている Azure インスタンスのタグをオプションで取得できます。

Azure カスタム構成例:

processors:
  resourcedetection/azure:
    detectors: ["azure"]
    azure:
      # リソース属性として追加するタグキーに一致する正規表現のリストを指定できます
      tags:
        - ^tag1$
        - ^tag2$
        - ^label.*$

一致したタグは次のように追加されます：

* azure.tags.<タグ名>

Azure AKS

  • cloud.provider ("azure")
  • cloud.platform ("azure_aks")
  • k8s.cluster.name
processors:
  resourcedetection/aks:
    detectors: [env, aks]
    timeout: 2s
    override: false

クラスター名

クラスター名検出はデフォルトで無効になっており、次の設定で有効にできます：

processors:
  resourcedetection/aks:
    detectors: [aks]
    timeout: 2s
    override: false
    aks:
      resource_attributes:
        k8s.cluster.name:
          enabled: true

Azure AKS クラスター名は、Azure インスタンスメタデータサービス（IMDS）のインフラストラクチャリソースグループフィールドから派生します。このフィールドには、リソースグループとクラスター名がアンダースコアで区切られて含まれています。例: MC_<リソースグループ>_<クラスター名>_<場所>。

例:

  • リソースグループ: my-resource-group
  • クラスター名: my-cluster
  • 場所: eastus
  • 生成された名前: MC_my-resource-group_my-cluster_eastus

クラスター名にアンダースコアが含まれていない場合、またはカスタムインフラストラクチャリソースグループ名が使用されていない場合にクラスター名が検出されます。

正確な解析が行えない場合、インフラストラクチャリソースグループの値が返されます。この値は、Azure が同じインフラストラクチャリソースグループ名で複数のクラスターを作成することを許可しないため、クラスターを一意に識別するために使用できます。

Consul

Consul エージェント を照会し、その 設定エンドポイント を読み取って次のリソース属性を取得します：

  • cloud.region (consul データセンター)
  • host.id (consul ノードID)
  • host.name (consul ノード名)
  • 展開された consul メタデータ - consul メタデータ のすべてのキー:値ペアをラベル:ラベル値ペアとして読み取ります。
processors:
  resourcedetection/consul:
    detectors: [env, consul]
    timeout: 2s
    override: false

Heroku

** アプリケーションで Heroku メタデータ機能 を最初に有効にする必要があります **

Heroku メタデータ を照会して、次のリソース属性を取得します：

  • heroku.release.version (現在のリリースの識別子)
  • heroku.release.creation_timestamp (リリースが作成された日時)
  • heroku.release.commit (現在のリリースのコミットハッシュ)
  • heroku.app.name (アプリケーション名)
  • heroku.app.id (アプリケーションの一意の識別子)
  • heroku.dyno.id (dyno 識別子。ホスト名として使用される)
processors:
  resourcedetection/heroku:
    detectors: [env, heroku]
    timeout: 2s
    override: false

K8S ノードメタデータ

K8S API サーバーを照会して、次のノードリソース属性を取得します：

* k8s.node.uid

次の権限が必要です:

kind: ClusterRole
metadata:
  name: otel-collector
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list"]
名前 タイプ 必須 デフォルト ドキュメント
auth_type string いいえ serviceAccount K8s API サーバーへの認証方法。none（認証なし）、serviceAccount（エージェントポッドに提供された標準のサービスアカウントトークンを使用する）、または kubeConfig（~/.kube/config から資格情報を使用） のいずれかを指定できます。
node_from_env_var string はい K8S_NODE_NAME メタデータを取得するノードの名前を保持する環境変数名。デフォルト値は K8S_NODE_NAME です。Downward API を使用して動的に環境変数を設定できます。例を参照してください。

デフォルトの node_from_env_var オプションを使用した例:

processors:
  resourcedetection/k8snode:
    detectors: [k8snode]

そして、これをワークロードに追加します:

        env:
          - name: K8S_NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName

カスタム変数 node_from_env_var オプションを使用した例:

processors:
  resourcedetection/k8snode:
    detectors: [k8snode]
    k8snode:
      node_from_env_var: "my_custom_var"

そして、これをワークロードに追加します:

        env:
          - name: my_custom_var
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName

Openshift

Openshift および Kubernetes API を照会して、次のリソース属性を取得します：

* cloud.provider
* cloud.platform
* cloud.region
* k8s.cluster.name

次の権限が必要です:

kind: ClusterRole
metadata:
  name: otel-collector
rules:
- apiGroups: ["config.openshift.io"]
  resources: ["infrastructures", "infrastructures/status"]
  verbs: ["get", "watch", "list"]

デフォルトでは、API アドレスは KUBERNETES_SERVICE_HOST、KUBERNETES_SERVICE_PORT の環境変数から決定され、サービストークンは /var/run/secrets/kubernetes.io/serviceaccount/token から読み取られます。
TLS が明示的に無効化されておらず、ca_file が構成されていない場合は、/var/run/secrets/kubernetes.io/serviceaccount/ca.crt が使用されます。
API アドレス、ca_file、サービストークンが設定されている場合は、それらの決定はスキップされます。

例:

processors:
  resourcedetection/openshift:
    detectors: [openshift]
    timeout: 2s
    override: false
    openshift: # オプション
      address: "https://api.example.com"


      token: "token"
      tls:
        insecure: false
        ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"

詳細なオプションについては、TLS 構成設定 を参照してください。

構成

# 実行するリソース検出器のリスト。有効なオプションは "env", "system", "gcp", "ec2", "ecs", "elastic_beanstalk", "eks", "lambda", "azure", "heroku", "openshift" です
detectors: [ <string> ]
# 既存のリソース属性を上書きするか保持するかを決定します。デフォルトは true です
override: <bool>
# [非推奨] 含まれている場合、リスト内の属性のみが追加されます。すべての検出器に適用されます。
attributes: [ <string> ]

さらに、resource_attributes オプションを使用して、各属性をどの検出器が収集するかを指定することができます。このような構成例は次の通りです：

resourcedetection:
  detectors: [system, ec2]
  system:
    resource_attributes:
      host.name:
        enabled: true
      host.id:
        enabled: false
  ec2:
    resource_attributes:
      host.name:
        enabled: false
      host.id:
        enabled: true

attributes から resource_attributes への移行

attributes オプションは非推奨であり、近いうちに削除される予定です。今後は resource_attributes を通じて属性の有効化/無効化を行ってください。
例えば、この設定：

resourcedetection:
  detectors: [system]
  attributes: ['host.name', 'host.id']

は次のように置き換えることができます：

resourcedetection:
  detectors: [system]
  system:
    resource_attributes:
      host.name:
        enabled: true
      host.id:
        enabled: true
      os.type:
        enabled: false

順序

複数の検出器が同じ属性名を挿入している場合、最初に挿入した検出器が優先されます。例えば、detectors: [eks, ec2] の場合、cloud.platform は aws_eks になり、ec2 にはなりません。以下の順序が推奨されます。

AWS

  • lambda
  • elastic_beanstalk
  • eks
  • ecs
  • ec2

この拡張機能で公開されているすべての設定のリストは ここ に記載され、詳細なサンプル構成は ここ に記載されています。

nomadblackynomadblacky

Datadog Exporter

https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/datadogexporter

ステータス
安定性 ベータ版: トレース、メトリクス、ログ
ディストリビューション 貢献
イシュー オープンイシュー クローズドイシュー
コードオーナー @mx-psi, @dineshg13, @liustanley, @songy23, @mackjmr, @ankitpatel96
エメリタス @gbbr

エクスポーターに必要な API キーなどの機密情報を保護するための推奨事項を含む、コレクターのセキュリティドキュメントを必ず確認してください。

Datadog Exporterは、デフォルトで APM 統計の計算をスキップするようになりました。APM 統計を計算するには、Datadog Connectorのみを使用することが推奨されます。
以前の動作に一時的に戻すには、exporter.datadogexporter.DisableAPMStats フィーチャーゲートを無効にしてください。例: otelcol --config=config.yaml --feature-gates=-exporter.datadogexporter.DisableAPMStats

Datadog Exporter の完全な設定および使用方法については、collector.yaml をご覧ください。その他の設定例は公式ドキュメントにあります。

FAQs

413 エラー（Request Entity Too Large）が発生するのはなぜですか？ どうすれば修正できますか？

このエラーは、Datadog Exporter が送信するペイロードのサイズが制限を超えていることを示しています（過去の事例: https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/16834、https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/17566）。

通常、これはパイプラインが Datadog Exporter に送信する前に、あまりにも多くのテレメトリーデータをバッチ処理しているために発生します。これを修正するには、バッチプロセッサーの設定で send_batch_size と send_batch_max_size を小さくしてみてください。他のエクスポーターが大きなバッチサイズを期待している場合は、Datadog Exporter 用に専用のバッチプロセッサーを用意することを検討してください。例えば:

processors:
  batch:  # 他のエクスポーターで使用
    timeout: 1s
    # send_batch_size のデフォルト値は 8192
  batch/datadog:
    send_batch_max_size: 100
    send_batch_size: 10
    timeout: 10s
...
service:
  pipelines:
    metrics:
      receivers: ...
      processors: [batch/datadog]
      exporters: [datadog]

send_batch_size と send_batch_max_size の正確な値は、ワークロードによって異なります。また、Datadog のインテークは 3 種類のシグナルに対して異なるペイロードサイズ制限があります：

フィーチャーゲートで Zorkian メトリクスクライアントに戻る

v0.69.0 以降、Datadog Exporter はメトリクスのエクスポートに Zorkian クライアントの代わりに datadog-api-client-go を使用するようになりました。datadog-api-client-go は Zorkian クライアントに存在するいくつかの問題を修正しましたが、特に高いメトリクス量の下で Zorkian クライアントに比べてパフォーマンスの低下が見られます。datadog-api-client-go でメモリやスループットの問題が発生した場合は、フィーチャーゲート exporter.datadogexporter.metricexportnativeclient を無効にして Zorkian クライアントに戻すことができます。例えば:

otelcol --config=config.yaml --feature-gates=-exporter.datadogexporter.metricexportnativeclient

現在、Datadog メトリクスエクスポーターはメトリクスシリアライザーを使用するように移行中です。フィーチャーフラグ exporter.datadogexporter.metricexportnativeclient は非推奨となり、将来的にはフィーチャーライフサイクルに従って最終的に削除されます。

OTel の service.name 属性をログの service にリマップする

注意 このワークアラウンドは、フィーチャーゲート exporter.datadogexporter.UseLogsAgentExporter が無効な場合にのみ必要です。このフィーチャーゲートは v0.108.0 以降デフォルトで有効になっています。

Datadog Exporter のバージョン 0.83.0 から v0.107.0 では、OTel ログの service フィールドは OTel セマンティック規約 の service.name として設定されています。しかし、service.name は Datadog のログ事前処理におけるデフォルトのサービス属性ではありません。

ログの service フィールドを正しく設定するには、ログサービスリマッパープロセッサーを設定して、ログのサービスのソースとして service.name を指定できます。

カスタムログソースを追加する方法

OTLP ログにカスタムソースを追加するには、リソース属性 datadog.log.source を設定します。この機能を利用するには、フィーチャーゲート exporter.datadogexporter.UseLogsAgentExporter が有効である必要があります（現在はデフォルトで有効です）。

例:

processors:
  transform/logs:
    log_statements:
      - context: resource
        statements:
          - set(attributes["datadog.log.source"], "otel")
nomadblackynomadblacky

Debug Exporter

https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/debugexporter

ステータス
安定性 開発中: トレース、メトリクス、ログ、プロファイル
ディストリビューション core, contrib, k8s
警告 不安定な出力形式
イシュー オープンイシュー クローズドイシュー

Debug Exporter は、デバッグ目的でテレメトリーデータをコンソールに出力します。

使用例については、トラブルシューティング ドキュメントも参照してください。

初めに

以下の設定はオプションです：

  • verbosity (デフォルト = basic): Debug Exporter の詳細度を設定
    (detailed|normal|basic)。detailed に設定すると、パイプラインデータが詳細にログ出力されます。
  • sampling_initial (デフォルト = 2): 毎秒ログ出力される初期メッセージ数。
  • sampling_thereafter (デフォルト = 1): 初期メッセージがログ出力された後のサンプリングレート（毎 M 番目のメッセージがログ出力されます）。
    デフォルト値 1 は、サンプリングが無効であることを意味します。
    サンプリングを有効にするには、sampling_thereafter を 1 より大きな値に設定します。
    サンプリングパラメータがメッセージ数に与える影響の詳細は Zap docs を参照してください。
  • use_internal_logger (デフォルト = true): コレクターの内部ロガーを出力に使用します。詳細は以下を参照してください。

設定例：

exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200

詳細度レベル

以下のサブセクションでは、構成された詳細度レベル（basic、normal、detailed）に応じたエクスポーターの出力について説明します。
デフォルトの詳細度レベルは basic です。

Basic 詳細度

verbosity: basic では、エクスポーターは受信したログ、メトリクス、トレースのバッチごとに、テレメトリーレコードの合計数を含む単一行の要約を出力します。

出力例：

2023-11-10T22:49:03.510-0600    info    TracesExporter  {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}

Normal 詳細度

verbosity: normal では、エクスポーターは各テレメトリーレコードごとに約 1 行の出力を行います。
「各テレメトリーレコードごとに 1 行」は厳密なルールではありません。
例えば、複数行の本文を持つログは複数行で出力されます。

出力例：

2024-06-24T15:18:58.559+0200    info    TracesExporter  {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
2024-06-24T15:18:58.559+0200    info    okey-dokey-0 4bdc558f0f0650e3ccaac8f3ae133954 8b69459f015c164b net.peer.ip=1.2.3.4 peer.service=telemetrygen-client
lets-go 4bdc558f0f0650e3ccaac8f3ae133954 8820ee5366817639 net.peer.ip=1.2.3.4 peer.service=telemetrygen-server
        {"kind": "exporter", "data_type": "traces", "name": "debug"}

Detailed 詳細度

verbosity: detailed では、エクスポーターは各テレメトリーレコードのすべての詳細を出力し、通常、各テレメトリーレコードごとに複数行で出力します。

出力例：

2023-11-10T22:49:03.510-0600    info    TracesExporter  {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
2023-11-10T22:49:03.510-0600    info    ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0
Resource attributes:
     -> service.name: Str(telemetrygen)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope telemetrygen
Span #0
    Trace ID       : 3bde5d3ee82303571bba6e1136781fe4
    Parent ID      : 5e9dcf9bac4acc1f
    ID             : 2cf3ef2899aba35c
    Name           : okey-dokey
    Kind           : Server
    Start time     : 2023-11-11 04:49:03.509369393 +0000 UTC
    End time       : 2023-11-11 04:49:03.50949377 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
     -> net.peer.ip: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-client)
Span #1
    Trace ID       : 3bde5d3ee82303571bba6e1136781fe4
    Parent ID      :
    ID             : 5e9dcf9bac4acc1f
    Name           : lets-go
    Kind           : Client
    Start time     : 2023-11-11 04:49:03.50935117 +0000 UTC
    End time       : 2023-11-11 04:49:03.50949377 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
     -> net.peer.ip: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-server)
        {"kind": "exporter", "data_type": "traces", "name": "debug"}

コレクターの内部ロガーの使用

use_internal_logger が true に設定されている（デフォルト）場合、エクスポーターはコレクターの 内部ロガー を出力に使用します。
この設定には以下の影響があります：

  • エクスポーターからの出力に、コレクター

のロガーからの追加の出力が注釈として追加される場合があります。

  • エクスポーターからの出力は、service::telemetry::logs に指定されたコレクターの ログ設定 の影響を受けます。

use_internal_logger が false に設定されている場合、エクスポーターはコレクターの内部ロガーを使用しません。
service::telemetry::logs の値を変更してもエクスポーターの出力には影響がありません。
エクスポーターの出力は stdout に送られます。

警告

  • 不安定な出力形式: すべての詳細度レベルの出力形式は保証されておらず、破壊的変更なしにいつでも変更される可能性があります。