otel-ottl

OpenTelemetry Transformation Language（OTTL）

OTTL を使用するコンポーネント

OTTL は transform プロセッサーと filter プロセッサーに限定されません。 プロセッサー（transform、filter、tailsampling、logdedup）とコネクター（routing、count、sum、signaltometrics）は、OTTL 式を受け付けます。 ユースケースを含む全リストについては、コンポーネントを参照してください。

OTTL の構文

パス式

ドット記法を使ってテレメトリーデータをたどります。

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

コンテキスト（パスの最初のセグメント）：resource、scope、span、spanevent、metric、datapoint、log。

列挙型

列挙型フィールドには int64 定数を使用します。

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER

演算子

代入：= — 比較：==、!=、>、<、>=、<= — 論理：and、or、not

関数

コンバーター（大文字、値を返します）：

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

エディター（小文字、データをその場で変更します）：

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

エディターとコンバーターの全リストについては、関数リファレンスを参照してください。

条件文

where を使って、条件に応じて変換を適用します。

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"

nil チェック

不在の確認には null ではなく nil を使用します。

resource.attributes["service.name"] != nil

検証ワークフロー

1. 設定構文を検証する — otelcol validate --config=config.yaml を実行して、Collector の起動前にコンパイルエラーを検出します。
2. デバッグエクスポーターでテストする — 変換したテレメトリーを debug エクスポーターにルーティングし、出力を確認します。

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform]
      exporters: [debug]   # swap in production exporter once validated

3. 本番環境では error_mode: ignore を設定する — エラー処理を参照してください。
4. 本番用エクスポーターに切り替える — debug を本番用エクスポーターに置き換えます。

一般的なパターン

• 属性を設定する
• パターンに基づいてテレメトリーを破棄する
• 古いデータを破棄する
• 欠落しているタイムスタンプを補完する
• Filter プロセッサーの例
• Transform プロセッサーの例
• 防御的な nil チェック
• 機密データを秘匿する — 戦略：置換、マスキング、ハッシュ化、削除、破棄。
• カーディナリティの高い属性を正規化する — パスセグメント、IP マスキング、属性数と長さの上限。
• 静的属性でテレメトリーを拡充する

エラー処理

コンパイルエラー

プロセッサーの初期化時に発生し、Collector の起動を妨げます。

• 構文が無効（引用符の欠落）
• 未知の関数
• 無効なパス式
• 型の不一致

実行時エラー

テレメトリーの処理中に発生します。

• 存在しない属性へのアクセス
• 型変換の失敗
• 関数実行エラー

エラーモードの設定

error_mode は必ず明示的に設定してください。デフォルトはコンポーネントによって異なります。 transform プロセッサーと filter プロセッサーのデフォルトは、Collector Contrib v0.153.0 以降では ignore、それ以前は propagate です。 routing コネクターと signaltometrics コネクターのデフォルトは propagate です。 count コネクターと sum コネクターには error_mode キーがなく、常にエラーを伝播します。

モード	動作	使用する場面
ignore	エラーをログに記録し、次のステートメントに進みます	本番環境および一般的な用途 — transform プロセッサーと filter プロセッサーのデフォルト
propagate	エラーをパイプラインに返し、Collector からペイロードを破棄します	すべてのエラーを検出したい開発環境や厳格な環境
silent	ログに記録せずにエラーを無視します	安全性が確認された変換を使う、高ボリュームのパイプラインで、エラーログがノイズとなる場合

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

ステートメントはフラットなリストです。Collector はパスのプレフィックスからコンテキスト（span、metric、datapoint、log など）を推測します。 単一のコンテキストを推測できないパスがステートメントグループに混在する場合、またはグループレベルの条件や error_mode が必要な場合にのみ、明示的な context: を指定したオブジェクト形式を使用してください。

パフォーマンス

where 句を使用して、早い段階で項目をスキップします。

# BAD — runs replace_pattern on every span
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}")

# GOOD — skips spans that lack the attribute
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}") where span.attributes["url.path"] != nil

参考資料

• OTTL ガイド
• OTTL 仕様
• OTTL 関数リファレンス
• OTTL プレイグラウンド