# Налаштування декоратора маршрутів OBI

> Налаштуйте компонент декоратора маршрутів перед тим, як OBI надішле дані на наступний етап конвеєра.

---

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

---

Секція YAML: `routes`

Ви можете налаштувати компонент у секції `routes` вашої YAML конфігурації або за допомогою змінних середовища.

Ви повинні налаштувати цю секцію у файлі YAML. Якщо ви не надасте секцію `routes`, OBI створить стандартний етап конвеєра маршрутів і використовуватиме декоратор маршрутів `heuristic`.

Наприклад:

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

| YAML               | Опис                                                                                                                                         | Тип           | Стандартно |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------- |
| `patterns`         | Список шаблонів URL-адрес для відповідності та встановлення властивості `http.route`. Див. [шаблони](#patterns).                             | список рядків | (unset)    |
| `ignored_patterns` | Список шаблонів URL-адрес для ігнорування. Викидає події трейси/метрики, якщо вони мають збіг. Див. [ігноровані шаблони](#ignored-patterns). | список рядків | (unset)    |
| `ignore_mode`      | Уточнює, які типи подій ігноруються при використанні `ignored_patterns`. Див. [режим ігнорування](#ignore-mode).                             | рядок         | all        |
| `unmatched`        | Вказує, що робити, коли HTTP-шлях трасування не відповідає жодному з записів `patterns`. Див. [невідповідність](#unmatched).                 | рядок         | heuristic  |
| `wildcard_char`    | Символ, який використовується для компонентів шляху, замінених режимом евристики. Див. [символ підстановки](#wildcard-char).                 | рядок         | `*`        |

## Шаблони {#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/*
```

Будь-які трейси з HTTP шляхами, які починаються з `/user` (включаючи `/user` сам по собі), відповідають маршруту `/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 використовує зірочку `'*'`. Значення повинно бути в лапках і повинно бути єдиним символом.

## Режим евристичного декорування маршруту {#heuristic-route-decorator-mode}

Декоратор `heuristic` є декоратором маршруту, що забезпечує найкращі результати, який все ще може призвести до вибуху кардинальності в деяких сценаріях. Наприклад, URL-адреси GitHub є хорошим прикладом, де декоратор маршруту `heuristic` не спрацює, оскільки URL-адреси побудовані як дерево тек. У цьому сценарії всі шляхи залишаються унікальними і призводять до вибуху кардинальності.

Якщо ваші шаблони шляхів URL слідують певній структурі, а унікальні ідентифікатори складаються з чисел або випадкових символів, то декоратор `heuristic` може бути варіантом конфігурації з низькими витратами, який працює для вашого випадку використання. Наприклад, наступні макети URL-адрес Google Docs правильно зменшуються до версії з низькою кардинальністю:

Обидва шляхи URL нижче:

```text
document/d/CfMkAGbE_aivhFydEpaRafPuGWbmHfG/edit (відсутність цифр в ідентифікаторі)
document/d/C2fMkAGb3E_aivhFyd5EpaRafP123uGWbmHfG/edit
```

перетворюються на маршрут з низькою кардинальністю (використовуючи стандартний `wildcard_char`):

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