mcpField
O
otel-ottl

otel-ottl

github.com/dash0hq云与 DevOps98608 次安装1 周前更新
代码仓库

关于 otel-ottl

面向 OpenTelemetry 用户的 OTTL 表达式参考，介绍语法、函数、错误处理与性能实践，适用于编写遥测数据转换和过滤规则。

主要功能

  1. 01使用路径表达式访问遥测数据
  2. 02编写条件转换与过滤表达式
  3. 03使用转换器和编辑器函数
  4. 04配置错误处理模式
  5. 05优化表达式执行效率

适用场景

  1. 01脱敏或删除敏感遥测属性
  2. 02按条件丢弃遥测数据
  3. 03规范高基数属性
  4. 04为遥测补充静态属性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dash0hq/agent-skills --skill otel-ottl

安装后在 Claude Code 中输入/otel-ottl确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

rules/
cardinality.md
components.md
enrichment.md
function-reference.md
patterns.md
redaction.md

详细介绍

OpenTelemetry 转换语言（OTTL）

使用 OTTL 的组件

OTTL 不仅限于 transform 和 filter 处理器。 处理器（transform、filter、tailsampling、logdedup）和连接器（routing、count、sum、signaltometrics）都接受 OTTL 表达式。 请参阅组件，了解完整列表和使用场景。

OTTL 语法

路径表达式

使用点号表示法导航遥测数据：

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

上下文（第一个路径段）：resource、scope、span、spanevent、metric、datapoint、log。

枚举

枚举字段使用 int64 常量：

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER
运算符

赋值：= — 比较：==、!=、>、<、>=、<= — 逻辑：and、or、not

函数

转换器（大写，返回值）：

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

编辑器（小写，原地修改数据）：

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

请参阅函数参考，了解编辑器和转换器的完整列表。

条件语句

使用 where 有条件地应用转换：

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"
Nil 检查

使用 nil 检查是否缺失（而非 null）：

resource.attributes["service.name"] != nil

验证工作流

  1. 验证配置语法 — 运行 otelcol validate --config=config.yaml，在启动 Collector 前检查编译错误。
  2. 使用 debug exporter 测试 — 将转换后的遥测数据路由到 debug exporter 并检查输出：
exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform]
      exporters: [debug]   # swap in production exporter once validated
  1. 在生产环境中设置 error_mode: ignore — 请参阅错误处理。
  2. 切换到生产环境的 exporter — 将 debug 替换为生产环境的 exporter。

常见模式

错误处理

编译错误

在处理器初始化期间发生，并会阻止 Collector 启动：

  • 语法无效（缺少引号）
  • 未知函数
  • 路径表达式无效
  • 类型不匹配
运行时错误

在遥测数据处理期间发生：

  • 访问不存在的属性
  • 类型转换失败
  • 函数执行错误
错误模式配置

始终显式设置 error_mode；默认值因组件而异。 从 Collector Contrib v0.153.0 起，transform 和 filter 处理器的默认值为 ignore；在此之前，默认值为 propagate。 routing 和 signaltometrics 连接器的默认值为 propagate。 count 和 sum 连接器没有 error_mode 键，且始终会传播错误。

模式行为使用场景
ignore记录错误并继续执行下一条语句生产环境和一般用途 — transform 和 filter 处理器的默认值
propagate将错误返回到流水线，并从 Collector 丢弃负载开发环境和严格环境，适合需要捕获每个错误的场景
silent忽略错误且不记录日志错误日志会造成干扰，且转换已知安全的高流量流水线
processors:
  transform:
    error_mode: ignore
    trace_statements:
      - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

语句是一个扁平列表；Collector 会根据路径前缀推断上下文（span、metric、datapoint、log 等）。 只有当一组语句混合了无法推断为单一上下文的路径，或者需要组级条件或 error_mode 时，才使用带有显式 context: 的对象形式。

性能

使用 where 子句尽早跳过项目。

# BAD — runs replace_pattern on every span
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}")

# GOOD — skips spans that lack the attribute
replace_pattern(span.attributes["url.path"], "/\\d+", "/{id}") where span.attributes["url.path"] != nil

参考资料

评论

支持 Markdown