otel-ottl

OpenTelemetry Transformation Language（OTTL）

OTTL は、Collector コンポーネント内のテレメトリーを変換または選択します。このスキルは collector-contrib v0.163.0 に固定されています。関数、パス、デフォルト、機能ゲートの利用可否はリリースによって異なります。ユーザーのバージョンが異なる場合は、該当する上流タグで確認してください。

v0.162.0 および v0.163.0 の日付付き OTTL 機能ゲートのステータスは、references/functions.md に記載されています。

ワークフロー

1. コンポーネントを選択します。 transform は書き換え、filter は破棄し、tail_sampling はトレースを保持するかどうかを判断し、routing はテレメトリーをパイプラインに送ります。コンポーネントによって、利用できるコンテキストと関数が異なります。
2. 利用可能な最も低いコンテキストを選択します。 低いコンテキストからは親を参照できます（たとえば、スパンから resource.attributes を参照できます）が、親から子は参照できません。metric.data_points をたどるのではなく、ポイント属性には datapoint を使用します。
3. 出力する各関数を確認してから、ステートメントを記述します。 references/functions.md で各関数の正確な識別子とシグネチャを確認してください。識別子が記載されていない場合は、もっともらしい名前を推測したり代用したりせず、未サポートとして扱ってください。set や delete_key などのエディターはデータを変更でき、where 条件を指定できる場合があります。ParseJSON や IsMatch などのコンバーターは値を返しますが、データは変更しません。
4. エラーの動作を意図的に設定します。 ignore はステートメントのエラーをログに記録して処理を続行し、silent はログに記録せず処理を続行し、propagate はエラーを返してコンポーネントによるペイロードの破棄につながることがあります。transform と filter のデフォルトは ignore です。transform のデフォルトエラー機能ゲートは v0.162.0 で削除されたため、--feature-gates で指定すると起動に失敗します（履歴については otel-collector スキルの transform に関する注意事項を参照）。filter のゲートは安定版で、無効化できません。ベータ版のデフォルトエラー機能ゲートが有効な場合、routing もデフォルトで ignore になります。routing では、ignore によってエラーの発生したペイロードが default_pipelines に送られます。このフォールバックを設定しないと、ペイロードは破棄されます。
5. エンドツーエンドで確認します。 正確な Collector バージョンで検証してください（v0.163 以降では validate によって routing コネクターの条件も解析されます）。次に、既知のテレメトリーを送信して、file-exporter の出力を確認します。telemetrygen のレシピを使用してください。

set(span.attributes["env"], "prod") where resource.attributes["env"] == nil

タスクに必要な情報だけを読み込む

• コンテキスト — 正確なパス、階層、列挙型、リクエストメタデータ。
• 関数 — エディター／コンバーターのシグネチャとリリースごとの利用可否。
• クイックリファレンス — コンポーネントの YAML、レシピ、エスケープ、トラブルシューティング、安全なスケルトン。

単一のパスまたは関数を確認する場合は、カタログ全体を読み込まず、該当するセクションだけを参照してください。

安全性と正確性のゲート

• 変換前に、省略可能または多相の入力を検証します。where x != nil、IsString(x)、または適切な型チェックを使用してください。
• JSON オブジェクトのみを扱う場合は、ParseJSON を呼び出す前に型と形式の両方を検証します。たとえば、IsString(log.body) and IsMatch(log.body.string, "(?s)^\\s*\\{.*\\}\\s*$") のようにします。RE2 の (?s) フラグを使うと、改行を含む整形済みオブジェクトも許容されます。解析後に IsMap をチェックしても、配列やスカラーの JSON が解析されるのを防ぐことはできません。
• バージョンを指定したリクエストでは、選択したパスと関数をすべて該当リリースタグで確認してください。このスキルの v0.163 を基準に一覧にある関数が、古いリリースにも存在するとは限りません。v0.156 で JSON オブジェクトを解析する場合、ParseJSON、IsString、IsMatch は v0.157 のアルファ版ラムダ機能ゲートなしで使用できます。
• リクエストメタデータは読み取り専用で、認証情報が含まれている場合があります。明示的に許可リストに指定された、機密情報ではないキーのみをコピーしてください。OTLP メタデータのルーティングには、レシーバーで include_metadata: true が必要です。HTTP／クライアントのヘッダー表記は元の形式を維持する場合があります（otelcol.client.metadata["X-Tenant"][0]）。gRPC メタデータのキーは小文字です（otelcol.grpc.metadata["x-tenant"][0]）。
• ルーティングの request コンテキストは v0.156 で非推奨になりました。otelcol.client.metadata または otelcol.grpc.metadata を使用してください。
• ログレコード固有の変換で共有リソースまたはスコープのデータを書き換えるには、flatten_data: true とアルファ版の transform.flatten.logs ゲートが必要です。これによりデータがコピーされ、再グループ化されます。誤って有効にしないでください。
• v0.161 以降、set(target, nil) は何もしない操作ではなくなりました。ottl.set.allowNil ゲートは v0.161 でベータ版になり、v0.162 で安定版になりました（無効化できません）。nil 値を指定すると、マップ、スライス、または pcommon.Value のターゲットは空になり（属性キーは空の値で作成されます）、スカラーのターゲットではエラーになります。入力がない場合に宛先を変更しないようにするには、where source != nil ガードを使用してください。
• 識別子をハッシュ化しても、必ず匿名化されるとは限りません。個人データの決定論的ハッシュを保持する前に、組織のデータ取り扱いポリシーを適用してください。

よくある構文上の落とし穴

• Collector YAML では、OTTL の置換後方参照 ${1} を $${1} と記述します。$1REDACTED のような置換文字列はリテラルとして扱われ、キャプチャの置換に失敗してもエラーになりません。
• Go RE2 は (.{1024}).* のような大きな回数指定の繰り返しを拒否します。型と nil のガードを付けた Substring と Len、またはマップ用の truncate_all を使用してください。
• 現在のスパンイベントパスは span_event.* ではなく spanevent.* です。キャッシュパスはコンテキスト修飾が必要です（span.cache["parsed"]）。
• YAML で : の後に空白があるマップリテラルを含む OTTL 文は、必ず引用符で囲んでください。たとえば 'set(log.attributes["a"], {"foo": "bar"})' のようにします。囲まないと、YAML は : をマッピングとして解析します。
• v0.159 以降、多相の pcommon.Value パスは基底の型で比較されます。マップとスライスでサポートされるのは等価と不等価のみですが、プリミティブ値では大小比較もサポートされます。
• Base64Decode は v0.161 で削除されたため、Decode(value, "base64") を使用してください。
• OTTL 文字列内の正規表現のエスケープは二重にします（\\d、\\s、\\.）。

上流ソース

• OTTL パッケージ
• Transform プロセッサー
• Filter プロセッサー
• Routing コネクター