OTTL 详解:OpenTelemetry 转换语言的语法与用法

OTTL(OpenTelemetry Transformation Language)是 Collector 中用于转换和过滤遥测数据的语言。本文介绍语句、路径、上下文与错误处理,并说明它与观测云 Pipeline 的边界。

最佳实践
应用性能监控中的服务链路与指标示意

OTTL(OpenTelemetry Transformation Language)是 OpenTelemetry Collector 中用于处理遥测数据的领域语言。 transform processor 可读取、改写和删除 Span、指标或日志中的字段,filter processor 也可以用 OTTL 条件决定要丢弃哪些遥测记录。常见字段处理可以用配置表达。

核心要点速览

  • OTTL 转换语句由编辑函数和可选的 where 条件组成,作用于指定上下文中的数据。
  • 路径指向实际字段,例如 span.attributes["http.request.method"]、span.status.code。
  • 典型用途包括字段重命名、属性删除、提取数据和按条件改写。
  • 在不同处理层之间迁移规则时,逐项验证字段、类型与错误处理。

什么是 OTTL?解决什么问题?

遥测数据从应用到后端的路上,常需要「微调」:把已知的旧字段映射到语义约定、删掉敏感属性、根据可靠的来源信息修正状态。OTTL 为这些转换提供声明式的表达方式。映射前仍要确认字段含义和类型,例如旧版的 http.status_code 与新版的 http.response.status_code 可能来自不同的埋点版本。

数据在管道里长什么样?

OTTL 操作流经 pipeline 的遥测结构,例如链路中的 Span 和 Span Event、指标及其数据点、日志记录。上下文决定当前处理的对象和可访问的字段。Span 上下文能访问当前 Span 及其资源属性,日志记录与指标数据点则有各自的路径。路径中的 resource 指向共享资源,修改资源属性可能影响同一资源下的其他记录。

OTTL 语法要素

语句(Statements)

一条转换语句调用一个编辑函数,可跟一个 where 条件。同组语句按顺序执行。下面的示例使用 Collector Contrib v0.162.0 的语法,以 Span 为上下文。

set(span.attributes["app.http.response_class"], "2xx") where IsInt(span.attributes["http.response.status_code"]) and span.attributes["http.response.status_code"] >= 200 and span.attributes["http.response.status_code"] < 300
delete_key(span.attributes, "http.request.header.authorization")

表达式与字面量

OTTL 支持布尔、数字、字符串字面量,比较与逻辑运算符(==、!=、and、or),以及上下文所支持的枚举,例如 Span 的 STATUS_CODE_UNSET。IsInt 可先判断类型,避免把字符串状态码当整数比较。

路径(Path)与上下文(Context)

span.attributes["key"] 访问 Span 属性,resource.attributes["service.name"] 访问资源属性,span.name、span.status.code 访问 Span 内建字段。transform processor 可根据带前缀的路径推断上下文,也可在语句组中显式设置 context。同一组必须使用当前上下文能够访问的路径、函数和枚举。

条件(where)

where 条件为真时才执行该条语句。语句组还可以用 conditions 设共同条件,同一组中的多条全局条件按 OR 组合。若多个判断必须同时成立,应在同一条件中用 and 连接。

典型用法示例

下方配置片段分两组。第一组只修复有明确来源标记的历史误判。示例自定义属性 app.legacy_http_status_error 由上游在确认 唯一 的错误原因是旧规则把服务端 HTTP 4xx 映射成 Error 时设置。没有这项约定时不要启用第一组。HTTP 语义约定在缺少额外上下文时要求服务端 4xx 的 Span 状态保持 Unset,客户端 4xx 则应标为 Error。HTTP Span 状态约定

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - context: span
        conditions:
          - >-
            span.kind == SPAN_KIND_SERVER
            and span.status.code == STATUS_CODE_ERROR
            and span.attributes["app.legacy_http_status_error"] == true
            and IsInt(span.attributes["http.response.status_code"])
            and span.attributes["http.response.status_code"] >= 400
            and span.attributes["http.response.status_code"] < 500
        statements:
          - set(span.status.message, "")
          - set(span.status.code, STATUS_CODE_UNSET)
      - context: span
        statements:
          - delete_key(span.attributes, "http.request.header.cookie")
          - set(span.cache["route_parts"], ExtractPatterns(span.attributes["url.path"], "^/api/(?P<group>orders|customers)(/|$)")) where IsString(span.attributes["url.path"])
          - set(span.attributes["app.route_group"], span.cache["route_parts"]["group"]) where span.cache["route_parts"]["group"] != nil

第二组删除指定的 Span 属性。若 Cookie 还出现在 Span Event、资源或日志正文里,需要另行处理。ExtractPatterns 返回命名捕获组成的映射,没匹配时返回空映射。示例从中读取 group 写入自定义字符串字段,不会把映射或原始 URL 写成 http.route。要启用该片段,仍需把 transform 加入实际的 service.pipelines.traces.processors 列表。更多配方见《OTTL 实战手册》。

在采集链路中选择转换位置

已经在 Collector 中执行的 OTTL 规则可以继续保留。若在 DataKit 的观测云 Pipeline 中处理日志,按 Platypus 函数语法重写,并用相同样本验证。字段删除、类型转换和失败处理都要逐项核对。先确定哪一层负责脱敏和命名,再检查下游实际查到的字段。如果在后段才移除敏感值,前段仍会接触原始数据。

常见问题(FAQ)

Q:OTTL 和 filter processor 有什么区别? OTTL 是语言。transform processor 用它改字段,filter processor 用它评估条件并丢弃匹配的记录,例如 Span 或日志。若 filter 的条件依赖改写后的字段,就在对应管线中把 transform 放在 filter 前。

Q:OTTL 性能好么? 开销取决于规则执行次数、数据量和操作类型。逐条运行正则或解析 JSON 会消耗 CPU;是否需要改规则或调整位置,应根据实际吞吐、延迟和 Collector 资源用量判断。

Q:语句执行出错会怎样? 在本文使用的版本中,transform 默认 ignore,记录运行时错误并继续执行;silent 同样继续但不记录该错误;propagate 会向管线返回错误,导致该批数据被丢弃。无法解析的语句属于配置错误。脱敏规则使用 ignore 时尤其要检查失败样本,避免误以为原值已移除。

Q:观测云 Pipeline 支持 OTTL 语法吗? Pipeline 使用 Platypus 函数脚本。迁移时须按实际函数与数据类型重写,并用样本核对处理结果。

系列阅读

参考资料:OTTL 语法(v0.162.0) · 观测云 OpenTelemetry 接入 · DataKit Pipeline · DataKit 文档

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台