配置 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 开头的 HTTP 路径的跟踪（包括 /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 的跟踪才会被丢弃，而指标仍会被记录。

未匹配

此属性指定当跟踪的 HTTP 路径不匹配任何 patterns 条目时要执行的操作。

unmatched 属性的可能值是

• unset 将 http.route 属性留空
• path 将 http.route 字段属性复制到路径值。此选项可能导致摄取端发生基数爆炸
• wildcard 将 http.route 字段属性设置为通配符 /** 值
• heuristic 根据以下规则自动从路径值派生 http.route 字段属性
  • 任何包含数字或不在 ASCII 字母表中的字符（或 - 和 _）的路径组件都将被 wildcard_char 替换
  • 任何看起来不像单词的字母组件都将被 wildcard_char 替换

通配符

与 unmatched: heuristic 一起使用此属性，以选择启发式模式识别的路径组件将被替换为哪个字符。默认情况下，OBI 使用星号 '*'。值应加引号，并且必须是单个字符。

启发式路由装饰器模式

heuristic 装饰器是一种尽力而为的路由装饰器，在某些情况下仍可能导致基数爆炸。例如，GitHub 的 URL 路径就是一个很好的例子，其中 heuristic 路由装饰器将无法正常工作，因为 URL 路径的构造方式类似于目录树。在这种情况下，所有路径都保持唯一，并导致基数爆炸。

如果您的 URL 路径模式遵循特定的结构，并且唯一 ID 由数字或随机字符组成，那么 heuristic 装饰器可能是适用于您用例的低成本配置选项。例如，以下模拟的 Google Docs URL 可以正确地减少到低基数版本

以下两个 URL 路径

document/d/CfMkAGbE_aivhFydEpaRafPuGWbmHfG/edit (no numbers in the ID)
document/d/C2fMkAGb3E_aivhFyd5EpaRafP123uGWbmHfG/edit

将被转换为低基数路由（使用默认的 wildcard_char）

document/d/*/edit