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

> OBI がパイプラインの次のステージにデータを送信する前に、ルートデコレーターコンポーネントを設定します。

---

LLMS index: [llms.txt](/llms.txt)

---

YAML セクション: `routes`

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

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

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

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

| YAML               | 説明                                                                                                                                                   | 型             | デフォルト |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ---------- |
| `patterns`         | マッチさせて `http.route` プロパティを設定する URL パスパターンのリスト。[パターン](#patterns) を参照してください。                                    | 文字列のリスト | 未設定     |
| `ignored_patterns` | 無視する URL パスパターンのリスト。マッチした場合、トレース/メトリクスイベントを破棄します。[無視するパターン](#ignored-patterns) を参照してください。 | 文字列のリスト | 未設定     |
| `ignore_mode`      | `ignored_patterns` を使用する際に、どの種類のイベントを無視するかを細かく指定します。[無視モード](#ignore-mode) を参照してください。                   | string         | all        |
| `unmatched`        | トレースの HTTP パスが `patterns` のエントリのいずれにもマッチしない場合の動作を指定します。[マッチしない場合](#unmatched) を参照してください。        | string         | heuristic  |
| `wildcard_char`    | ヒューリスティックモードによって置き換えられるパスコンポーネントに使用する文字。[ワイルドカード文字](#wildcard-char) を参照してください。              | string         | `*`        |

## パターン {#patterns}

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

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

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

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

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

```text
/user/123
/user/456
```

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

```text
/user/123/basket/1
/user/456/basket/3
```

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

```yaml
routes:
  patterns:
    - /user/*
```

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

```text
/user
/user/123
/user/123/basket/1
/user/456/basket/3
```

## 無視するパターン {#ignored-patterns}

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

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

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

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

## 無視モード {#ignore-mode}

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

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

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

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

## マッチしない場合 {#unmatched}

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

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

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

## ワイルドカード文字 {#wildcard-char}

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

## ヒューリスティックルートデコレーターモード {#heuristic-route-decorator-mode}

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

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

以下の両方の URL パスは:

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

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

```text
document/d/*/edit
```