OTTLとは? Collectorでテレメトリーを変換する構文と実例
OTTL の文、パス、コンテキストを解説。Collector で古いステータスの変換を修正し、属性を削除・抽出する設定例を紹介します。
計装ライブラリを入れ替えたあと、リクエストの挙動は同じなのに、ダッシュボード上のエラー数だけが変わることがあります。古いライブラリがすべての404をエラー扱いしていたとしても、404のスパンを一律に直せば、クライアント側の失敗まで見えなくなりかねません。書き換える対象と、その状態になった理由を先に確かめます。
OTTL(OpenTelemetry Transformation Language)は、Collector がテレメトリーを調べ、処理するための言語です。 transform processor ではフィールドを変更でき、filter processor では OTTL の条件に合うデータを破棄できます。どちらも Collector 内の構造化されたデータを扱います。
OTTL の要点
- 変換文は編集用の関数を呼び出し、必要に応じて
where条件を付けます。 span.attributes["http.request.method"]やspan.status.codeのようなパスで、コンテキスト内のフィールドを指定します。- 属性名の変更、フィールドの削除、値の抽出、条件に応じた更新などに使えます。
- 処理を別の段階に移すときは、フィールド、値の型、失敗時の挙動を比較します。
OTTL でできること
バックエンドに送る前に、取得したヘッダーを取り除いたり、古い属性名をセマンティック規約(英語)に合わせたりする場合があります。由来が分かるステータスを修正することもできます。こうした処理を Collector の設定で表せるのが OTTL です。たとえば HTTP のステータスコードは、計装のバージョンによって http.status_code と http.response.status_code のどちらで出るかが変わります。変換前に実際の属性を確認します。
パイプラインに流れるデータ
トレースにはスパンとスパンイベント、メトリクスにはデータポイント、ログにはレコードがあります。コンテキストによって処理対象と参照できるフィールドが決まります。スパンのコンテキストからは、現在のスパンやそのリソース属性を参照できます。リソース属性は共有されるため、書き換えると同じリソースに属する別のデータにも影響する場合があります。
OTTL の構文
文
変換文は編集用の関数を一つ呼び出します。必要であれば where を付けます。同じグループの文は順番に実行されます。以下は Collector Contrib v0.162.0 のスパンコンテキストを使う例です。
set(span.attributes["app.http.response_class"], "2xx") where IsInt(span.attributes["http.response.status_code"]) and span.attributes["http.response.status_code"] >= 200 and span.attributes["http.response.status_code"] < 300
delete_key(span.attributes, "http.request.header.authorization")
式とリテラル
真偽値、数値、文字列のリテラルに加え、== や != といった比較演算子、and や or を使えます。列挙値はコンテキストによって決まり、スパンでは STATUS_CODE_UNSET などを使えます。属性の型が一定でなければ、IsInt で整数かを確かめてから比較します。
パスとコンテキスト
span.attributes["key"] はスパンの属性を指し、resource.attributes["service.name"] はリソース属性を指します。span.name と span.status.code はスパンの組み込みフィールドです。transform processor はパスの接頭辞からコンテキストを推論できます。グループの context に明示することもできます。パス、関数、列挙値は、選んだコンテキストで利用できるものを使います。
条件
where が真になったときだけ、その文を実行します。グループ全体の条件は conditions に設定できます。ここに複数の条件を書くと OR で評価されます。すべての判断を満たす必要があるときは、一つの条件の中で and でつなぎます。
HTTP スパンを変換する例
一つ目のグループは、由来が分かっている古いルールによる誤判定を修正します。上流は、サーバーが 4xx を返したことだけを理由に古いルールが Error を設定したと確認できた場合に、例の属性 app.legacy_http_status_error を設定します。この取り決めがある場合に限り、一つ目のグループを有効にします。HTTP のセマンティック規約では、計装に追加の情報がなければ、サーバー側の 4xx は Unset のままにし、クライアント側の 4xx は Error にすることが推奨されます。HTTP スパンのステータス規約(英語)
processors:
transform:
error_mode: ignore
trace_statements:
- context: span
conditions:
- >-
span.kind == SPAN_KIND_SERVER
and span.status.code == STATUS_CODE_ERROR
and span.attributes["app.legacy_http_status_error"] == true
and IsInt(span.attributes["http.response.status_code"])
and span.attributes["http.response.status_code"] >= 400
and span.attributes["http.response.status_code"] < 500
statements:
- set(span.status.message, "")
- set(span.status.code, STATUS_CODE_UNSET)
- context: span
statements:
- delete_key(span.attributes, "http.request.header.cookie")
- set(span.cache["route_parts"], ExtractPatterns(span.attributes["url.path"], "^/api/(?P<group>orders|customers)(/|$)")) where IsString(span.attributes["url.path"])
- set(span.attributes["app.route_group"], span.cache["route_parts"]["group"]) where span.cache["route_parts"]["group"] != nil
二つ目のグループが削除するのは指定したスパン属性です。Cookie がリソース属性、スパンイベント、ログ本文にも残っているなら、それぞれ別に処理します。ExtractPatterns は名前付きキャプチャをマップで返し、マッチしなければ空のマップを返します。次の文がその group をカスタムの文字列属性に書き込みます。http.route は元の値を保ちます。
実行するには、実際の service.pipelines.traces.processors に transform を追加します。他の例は OTTL パターン集(簡体字中国語)で確認できます。
どの段階で変換するか
すでに Collector で動いているルールは、エクスポート前にそのまま実行できます。DataKit の Guance Pipeline(英語) でログを処理する場合は、Platypus の関数で書き直し、同じ入力を使って出力を比較します。フィールドの削除、型の変換、失敗時の処理を個別に確認します。どの段階でマスキングや名前の変更を行うか決めたら、バックエンドで受信したデータを確認します。後段で削除しても、それより前の処理は元の値に触れます。
よくある質問
OTTL と filter processor の違いは何ですか? OTTL は言語です。transform processor は OTTL でフィールドを変更し、filter processor は条件に合うスパンやログなどを破棄します。書き換えた値を条件に使う場合は、同じパイプラインで transform を先に実行します。
OTTL の処理コストはどの程度ですか? ルールを実行する回数、データ量、処理内容によって異なります。全レコードに対する正規表現や JSON パースは CPU を使います。ルールや処理箇所を変えるときは、スループット、処理遅延、Collector のリソース使用量を比べます。
文の実行時にエラーが起きるとどうなりますか? このバージョンで transform の既定値は ignore です。実行時エラーをログに残して次へ進みます。silent はログに残さず続行し、propagate はエラーをパイプラインに返してそのデータを破棄します。文をパースできない場合は設定エラーです。マスキングで ignore を使うなら、処理に失敗するデータで元の値が残るかも確認します。
Guance Pipeline で OTTL を使えますか? Pipeline は Platypus のスクリプトを使います。実際の関数とデータ型に合わせてルールを書き直し、同じサンプルで結果を確かめます。
関連記事
- 前の記事 OCB でカスタム Collector を作る(英語)
- 次の記事 OTLP の転送方式と設定
- 関連 OTTL パターン集(簡体字中国語) · OpenTelemetry のセマンティック規約(英語) · 技術ガイド一覧
参考資料 OTTL の言語仕様 v0.162.0(英語) · Guance の OpenTelemetry 連携(英語) · DataKit Pipeline(英語) · DataKit 文書(英語)
