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

OTTL（OpenTelemetry Transform Language）是 OpenTelemetry Collector 中用于对遥测数据做声明式转换的领域语言，通过 transform processor 对 Span、指标数据点和日志记录的字段进行读取、修改、删除与条件化处理——过去要写自定义 processor 才能做的事，现在几行 OTTL 语句即可完成。

核心要点速览

• OTTL 语句 = 函数(参数) 形式，作用于「上下文」中的数据（Span/日志记录/数据点）；
• 路径（Path）指向数据字段，如 attributes["http.method"]、status.code；
• 典型用途：字段重命名、属性删除/提取、状态修正、按条件改写；
• 观测云用户可用 Pipeline 函数脚本实现同等加工，在采集侧或平台侧完成。

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

遥测数据从应用到后端的路上，常需要「微调」：把不规范的字段名归一到语义约定、删掉敏感属性、根据内容设置状态。OTTL 为这些转换提供统一、声明式的表达方式，避免每个需求都要编译一个自定义 processor。

数据在管道里长什么样？

OTTL 操作的对象是流经 pipeline 的遥测数据结构：Trace 中的 Span（含 attributes、status、events）、Metric 中的数据点、Log 中的记录。每种结构都有自己的「上下文（context）」，OTTL 通过上下文访问具体字段。

OTTL 语法要素

语句（Statements）

语句是转换的最小单位，形式为 函数(目标, 参数...)，按顺序执行：

set(status.code, 1) where attributes["http.status_code"] == 200
delete_key(attributes, "http.request.header.authorization")

表达式与字面量

支持布尔、数字、字符串字面量，比较与逻辑运算符（==、!=、and、or），以及枚举值（如 STATUS_CODE_OK）。

路径（Path）与上下文（Context）

路径用于定位字段：attributes["key"] 访问属性，resource.attributes["service.name"] 访问资源属性，name、status.code 访问 Span 内建字段。上下文决定路径的起点（span/log/metric 各有不同）。

条件（where）

where 子句让语句只在条件满足时执行，是实现「按内容改写」的关键。

典型用法示例

processors:
  transform:
    trace_statements:
      - context: span
        statements:
          # 统一状态：HTTP 4xx 不算服务端错误
          - set(status.code, 1) where attributes["http.status_code"] >= 400 and attributes["http.status_code"] < 500
          # 删除敏感属性
          - delete_key(attributes, "http.request.header.cookie")
          # 从 URL 提取路由模板
          - set(attributes["http.route"], ExtractPatterns(attributes["url.path"], "^/api/(?P<route>\\w+)"))

更多实战配方见《OTTL 实战手册》。

观测云视角：Pipeline 实现同等加工

观测云用户的转换逻辑一般写在 Pipeline 而非 Collector 侧：

架构建议：能用 DataKit/Pipeline 在采集侧完成的加工，就不放到多层 Collector 里，管道层级越少，排障和升级越简单。

常见问题（FAQ）

Q：OTTL 和 filter processor 有什么区别？ filter 负责「整条数据要不要丢弃」，OTTL（transform）负责「对数据内容做改写」。两者常配合使用：先改写成规范形态，再按规范字段过滤。

Q：OTTL 性能好么？ OTTL 语句经过编译执行，性能优于通用脚本，但大规模复杂规则仍有 CPU 成本——规则越简单越好，重加工任务建议下沉到平台侧。

Q：语句执行出错会怎样？ 默认错误处理策略会跳过该语句继续执行（可在配置中调整 error_mode）。上线前建议用样例数据做验证。

Q：观测云 Pipeline 支持 OTTL 语法吗？ Pipeline 使用自己的函数脚本语法而非 OTTL，但能力等价；已有 OTTL 规则可平移到 Pipeline 函数实现。

系列阅读

• 上一篇：《自定义 OpenTelemetry Collector》
• 下一篇：《OTLP 协议详解》
• 相关：《OTTL 实战手册》 · 《OpenTelemetry 语义约定》 · 《返回索引》