文档 Beyla 配置 路由装饰器

配置 Beyla 路由装饰器

您可以在 YAML 配置文件的 routes 部分或通过环境变量配置此组件。

此部分只能通过 YAML 文件进行配置。如果 YAML 文件中未提供 routes 部分，将创建一个默认的路由管道阶段，并使用 heuristic 路由装饰器进行过滤。

将匹配提供的 URL 路径模式并相应地设置 http.route 追踪/指标属性。您应尽可能使用 routes 属性，以减少生成的指标基数。

每个路由模式都是一个带有特定标签的 URL 路径，这些标签允许对路径段进行分组。匹配器标签可以是 :name 或 {name} 格式。

例如，如果您定义以下模式

yaml 复制

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

此外，路由匹配器还支持通配符 *，可用于匹配路径前缀。例如，如果您定义以下模式

yaml 复制

routes:
  patterns:
    - /user/*

任何以 /user 开头（包括 /user 本身）的 HTTP 路径的追踪都将匹配到路由 /user/*。根据上面的示例，以下所有路径都将匹配为 /user/*

复制

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

将提供的 URL 路径与定义的模式进行匹配，如果匹配到任何 ignored_patterns，则丢弃追踪和/或指标事件。ignored_patterns 字段的格式与上面描述的 patterns 字段完全相同。您可以定义带有或不带有任何通配符选项的忽略模式。例如，如果您定义以下忽略模式

yaml 复制

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 一起使用，以选择启发式模式识别的路径组件替换为什么字符。默认使用星号（'*'）。该值应加引号且必须是单个字符。

使用 heuristic 路由装饰器模式时的特殊注意事项

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