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

Секція YAML: routes

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

Ви повинні налаштувати цю секцію у файлі 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/*

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

Unmatched

Ця властивість визначає, що робити, коли HTTP шлях трасування не відповідає жодному з записів patterns.

Можливі значення для властивості unmatched:

• unset залишає властивість http.route не заданою
• path копіює властивість поля http.route в значення шляху. Ця опція може призвести до вибуху кардинальності на стороні споживання
• wildcard встановлює властивість поля http.route на загальне значення з зірочкою /**
• heuristic автоматично виводить властивість поля http.route з значення шляху, на основі цих правил:
  • Будь-які компоненти шляху з числами або символами поза ASCII алфавітом (або - і _) замінюються на wildcard_char
  • Будь-які алфавітні компоненти, які не виглядають як слова, замінюються на wildcard_char

Символ підстановки

Використовуйте цю властивість разом з unmatched: heuristic, щоб вибрати, яким символом замінюються компоненти шляху, визначені евристичним режимом. Типово OBI використовує зірочку '*'. Значення повинно бути в лапках і повинно бути єдиним символом.

Режим евристичного декорування маршруту

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

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

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

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

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

document/d/*/edit