トランスフォームプロセッサー

テレメトリを Splunk Observability Cloud にエクスポートする前に、変換プロセッサを使用してトレース、メトリクス、またはログを変更します。コンポーネントの設定方法については、続きをお読みください。

変換プロセッサは、 ステートメントを介して一致スパン、メトリクス、またはログを変更する OpenTelemetry Collector コンポーネントです。ユースケースには、メトリクスを別のタイプに変換する、キーを置換または削除する、事前定義された条件に応じてフィールドを設定するなどがあります。

ステートメントは、OpenTelemetry Transformation Language（OTTL）の関数であり、リスト内の順序に従ってテレメトリに適用されます。変換プロセッサには、メトリクスタイプを変換するための追加関数が含まれています。ステートメントは、定義した OTTL コンテキスト（Span や DataPoint など）に従ってデータを変換します。

トランスフォームプロセッサーは、以下のコンテキストをサポートしています：

シグナル

サポートされているコンテキスト

トレース

resource → scope → span → spanevent

メトリクス

resource → scope → metric → datapoint

ログ

resource → scope → logs

ステートメントは、より高いコンテキストのテレメトリを変換できます。たとえば、データポイントに適用されたステートメントは、データポイントのメトリクスとリソースにアクセスできます。下位コンテキストにはアクセスできません。たとえば、span ステートメントを使用して単一の span イベントを変換することはできません。一般的に、変換するコンテキストにステートメントを関連付けます。

注意: テレメトリを変更すると、スパンやログの取り残し、アイデンティティの競合、誤ったメトリクス変換など、意図しない結果が生じる可能性があります。実稼働環境でリリースする前に、必ず変換をテストしてください。

はじめに

以下の手順に従って、コンポーネントの設定とアクティベーションを行ってください：

  1. Splunk Distribution of OpenTelemetry Collector をホストまたはコンテナプラットフォームにデプロイします。「Get started: Understand and use the Collector」を参照してください。

  2. 次のセクションで説明するように、TCPログレシーバーを設定します。

  3. Collector を再起動します。

サンプル構成

パイプラインの変換プロセッサを有効にするには、設定の processors セクションに transform を追加します。例：

transform:
  error_mode: ignore
  # Statements can be trace, metric, or log
  <trace|metric|log>_statements:
    - context: <context>
      statements:
        - <statement>
        - <statement>
        - <statement>
     - context: <context>
        statements:
        - <statement>
        - <statement>
        - <statement>

その後、互換性のあるパイプラインに変換プロセッサを追加することができます。例：

:emphasize-lines: 6, 14, 22

service:
  pipelines:
    traces:
      receivers: [jaeger, otlp, zipkin]
      processors:
      - transform
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [otlphttp, signalfx]
    metrics:
      receivers: [hostmetrics, otlp, signalfx]
      processors:
      - transform
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [signalfx]
    logs:
      receivers: [fluentforward, otlp]
      processors:
      - transform
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [splunk_hec]

error_mode フィールドは、ステートメントを処理する際にプロセッサーがどのようにエラーに対応するかを記述します：

  • error_mode: ignore は、エラーを無視して実行を続行するようにプロセッサに指示します。これがデフォルトのエラーモードです。

  • error_mode: propagate はプロセッサにエラーを返すように指示します。その結果、Collector はペイロードをドロップします。

OTTLの関数と構文の詳細については、こちらを参照してください：

設定例

以下のサンプル構成は、スパン、メトリクス、およびログに対してさまざまな変換を実行する方法を示しています。

Kubernetesのオブジェクトログを変換する

次の例は、k8sobjects レシーバーを使用して受信したログを編集する方法を示しています。ログを短縮すると、ダッシュボードでオブジェクトを視覚化する場合やアラートを設定する場合に役立ちます。

transform:
  error_mode: ignore
  log_statements:
    - context: log
      statements:
        - replace_all_patterns(attributes, "(object\.)(.*\.)", "object.")

リソースとスパンを編集してサイズを調整する

次の例は、属性の数を制限し、4,096 文字に切り詰めることによって、リソースとスパンを編集する方法を示しています。 resource ステートメントは、keep_keys で示されたキー以外のすべてのキーを削除します。

transform:
  error_mode: ignore
  trace_statements:
     - context: resource
       statements:
         # Only keep the following keys
         - keep_keys(attributes, ["service.name", "service.namespace", "cloud.region", "process.command_line"])
         - limit(attributes, 100, [])
         - truncate_all(attributes, 4096)
     - context: span
       statements:
         - limit(attributes, 100, [])
         - truncate_all(attributes, 4096)

データポイントを異なるタイプに変換する

以下の例では、変換プロセッサーに含まれる関数を使用して、データポイントをメトリクス名によって異なるタイプに変換する方法を示しています。

transform:
  metric_statements:
    - context: metric
      statements:
        - set(description, "Sum") where type == "Sum"
    - context: datapoint
      statements:
        - convert_sum_to_gauge() where metric.name == "system.processes.count"
        - convert_gauge_to_sum("cumulative", false) where metric.name == "prometheus_metric"

設定

次の表は、属性プロセッサーの設定オプションを示します：

メトリクス関数

メトリクスコンテキストには以下の関数を適用できます：

  • convert_sum_to_gauge：sum 型のメトリクスを gauge 型に変換します。データポイントを保持します。

  • convert_gauge_to_sum：gauge 型のメトリクスを sum 型に変換します。データポイントを保持します。集約時間（cumulative または delta）および単調性（boolean）を引数として指定します。

  • convert_summary_count_val_to_sum：サマリーのカウント値から sum 型のメトリクスを作成します。集約時間（cumulative または delta）および単調性（boolean）を引数として指定します。新しいメトリクスの名前の形式は <summary metric name>_count です。タイムスタンプ、属性、説明は保持されます。

  • convert_summary_sum_val_to_sum：サマリーのカウント値から sum 型のメトリクスを作成します。集約時間（cumulative または delta）および単調性（boolean）を引数として指定します。新しいメトリクスの名前の形式は <summary metric name>_sum です。タイムスタンプ、属性、説明は保持されます。

注意: 変換関数を使用すると、メトリクスのセマンティクスが壊れる可能性があります。

トラブルシューティング

__ ___ ___ _ ______ _____________ _____ ________ ___ ___ ___ ____ __ ___ ____ ____ __ ______ _____________ ______ ___ ___ ___ ____ __ ___ _________ _____

_________ __ ______ _____________ _____ _________

_________ __ ___________ _________ ___ ____ _____ _____

  • ___ _ ________ ___ ___ _______ _______ _________ _______ __ ______ ________

  • ____ ___ ______ ______________ ____ _____ _____ _______ __ ___________ ____ __________ _________ ___ ______ _________ __________ __ _____ ___ ____ _______