OBI ルートデコレーターを設定する

YAML セクション: routes

このコンポーネントは、YAML 設定ファイルの routes セクション、または環境変数を使用して設定できます。

このセクションは YAML ファイルで設定する必要があります。 routes セクションを指定しない場合、OBI はデフォルトのルートパイプラインステージを作成し、heuristic ルートデコレーターを使用します。

たとえば次のとおりです。

routes:
  patterns:
    - /basic/:rnd
  unmatched: path
  ignored_patterns:
    - /metrics
  ignore_mode: traces

パターン

OBI は指定された URL パスパターンとマッチさせ、http.route のトレース/メトリクスプロパティを設定します。 生成されるメトリクスのカーディナリティを抑えるため、可能な限り routes プロパティを使用してください。

各ルートパターンは、パスセグメントをグループ化するタグを含む URL パスです。 マッチャータグには :name または {name} 形式を使用できます。

たとえば、次のパターンを定義した場合を考えます。

routes:
  patterns:
    - /user/{id}
    - /user/{id}/basket/{product}

次の HTTP パスを持つトレースには、同じ http.route='/user/{id}' プロパティが含まれます。

/user/123
/user/456

次の HTTP パスを持つトレースには、同じ http.route='/user/{id}'/basket/{product} プロパティが含まれます。

/user/123/basket/1
/user/456/basket/3

ルートマッチャーは、パスの接頭辞にマッチするワイルドカード文字 * もサポートします。 たとえば、次のパターンを定義した場合を考えます。

routes:
  patterns:
    - /user/*

/user で始まる（/user 自体も含む）HTTP パスを持つトレースはすべて、ルート /user/* にマッチします。 以下のすべてのパスが /user/* としてマッチします。

/user
/user/123
/user/123/basket/1
/user/456/basket/3

無視するパターン

OBI は、指定された URL パスを定義されたパターンと照合し、ignored_patterns のいずれかにマッチした場合、トレースおよび/またはメトリクスイベントを破棄します。 ignored_patterns フィールドの形式は patterns フィールドと同じです。 無視するパターンは、ワイルドカードオプションの有無にかかわらず定義できます。 たとえば、次の無視するパターンを定義した場合を考えます。

routes:
  ignored_patterns:
    - /health
    - /v1/*

/v1 を接頭辞として持つ、または /health と等しいイベントパスはすべて無視されます。

このオプションは、開発用やサービスヘルスモニタリング用に使用される特定のパスがトレースまたはメトリクスとして記録されないようにしたい場合に有用です。

無視モード

このプロパティを ignored_patterns プロパティと組み合わせて使用することで、どの種類のイベントを無視するかを細かく指定できます。

ignore_mode プロパティに指定可能な値は次のとおりです。

• all は、ignored_patterns にマッチするメトリクスとトレースの両方を破棄します
• traces は、ignored_patterns にマッチするトレースのみを破棄し、メトリクスイベントは無視しません
• metrics は、ignored_patterns にマッチするメトリクスのみを破棄し、トレースイベントは無視しません

特定の種類のイベントを無視したい場合があります。 たとえば、ヘルスチェック API のパフォーマンスメトリクスは知りたいが、それらのトレースレコードによるトレースデータベースのオーバーヘッドは避けたい、というケースです。 この場合、ignore_mode プロパティを traces に設定すると、ignored_patterns にマッチするトレースのみが破棄され、メトリクスは記録され続けます。

マッチしない場合

このプロパティは、トレースの HTTP パスが patterns のエントリのいずれにもマッチしない場合の動作を指定します。

unmatched プロパティに指定可能な値は次のとおりです。

• unset は、http.route プロパティを未設定のままにします
• path は、http.route フィールドプロパティをパス値にコピーします。このオプションは、取り込み側でカーディナリティ爆発を引き起こす可能性があります
• wildcard は、http.route フィールドプロパティを汎用的なアスタリスクベースの /** 値に設定します
• heuristic は、次のルールに基づいて、パス値から http.route フィールドプロパティを自動的に導出します。
  • 数字や ASCII アルファベット（または - と _）以外の文字を含むパスコンポーネントは、wildcard_char に置き換えられます
  • 単語のように見えないアルファベットのコンポーネントは、wildcard_char に置き換えられます

ワイルドカード文字

このプロパティを unmatched: heuristic と組み合わせて使用し、ヒューリスティックモードで識別されたパスコンポーネントを置き換える文字を選択します。 デフォルトでは、OBI はアスタリスク '*' を使用します。 値は引用符で囲み、1 文字でなければなりません。

ヒューリスティックルートデコレーターモード

heuristic デコレーターはベストエフォートのルートデコレーターであり、一部のシナリオでは依然としてカーディナリティ爆発を引き起こす可能性があります。 たとえば、GitHub の URL パスは heuristic ルートデコレーターが機能しない好例で、URL パスがディレクトリツリーのように構成されているためです。 このシナリオでは、すべてのパスが一意のままになり、カーディナリティ爆発を引き起こします。

URL パスパターンが一定の構造に従っており、一意の ID が数字またはランダムな文字で構成されている場合、heuristic デコレーターはあなたのユースケースに合う、設定の手間が少ないオプションかもしれません。 たとえば、次のモック Google Docs URL は、低カーディナリティのバージョンに正しく削減されます。

以下の両方の URL パスは:

document/d/CfMkAGbE_aivhFydEpaRafPuGWbmHfG/edit (IDに数字を含まない)
document/d/C2fMkAGb3E_aivhFyd5EpaRafP123uGWbmHfG/edit

低カーディナリティのルート（デフォルトの wildcard_char を使用）に変換されます。

document/d/*/edit