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 のスクリプトを使います。実際の関数とデータ型に合わせてルールを書き直し、同じサンプルで結果を確かめます。

関連記事

参考資料 OTTL の言語仕様 v0.162.0(英語) · Guance の OpenTelemetry 連携(英語) · DataKit Pipeline(英語) · DataKit 文書(英語)

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ