OTTL 实战手册：10 个即用型遥测数据转换模式

OTTL（OpenTelemetry Transformation Language）是 Collector transform 处理器使用的声明式语言，专门用于在数据流动过程中就地修改 Span、指标与日志——掌握它，等于掌握了在"不改应用代码"的前提下清洗、丰富、重塑遥测数据的能力。

核心要点速览

• OTTL 语句按上下文（span/log/metric）执行，支持函数组合与条件判断；
• 最常用场景：脱敏、降噪、规范化、富化、分类——本文 10 例全覆盖；
• 所有转换发生在 Collector 侧，应用零改动，灰度风险低；
• 观测云用户可用 DataKit Pipeline 实现同类处理，文末给出对照。

模式 1：URL 中的敏感参数脱敏

HTTP 属性里常带 client_id、client_secret 等凭据，用正则替换抹掉：

transform/redact:
  trace_statements:
    - context: span
      statements:
        - replace_pattern(attributes["http.url"], "client_id=[^&]+", "client_id=[REDACTED]")
        - replace_pattern(attributes["http.url"], "client_secret=[^&]+", "client_secret=[REDACTED]")

处理前 https://example.com?client_id=test-id&client_secret=cd76c...，处理后敏感值统一变成 [REDACTED]——满足合规又不影响 URL 结构分析。

模式 2：丢弃无关日志

健康检查、心跳日志纯占存储，按内容过滤：

transform/drop_noise:
  error_mode: ignore
  log_statements:
    - context: log
      statements:
        - delete_all_where(attributes, "health", true)  # 示意：标记后配合 filter 处理器丢弃

实际生产更常用 filter 处理器直接按 body 或属性条件丢弃整条日志。

模式 3：日志正文解析

非结构化日志用 OTTL 提取字段：

transform/parse:
  log_statements:
    - context: log
      statements:
        - extract_patterns(body, "(?P<user>\\w+) logged in from (?P<ip>[\\d.]+)")
        - set(attributes["user"], body["user"])
        - set(attributes["client_ip"], body["ip"])

日志从一团文本变成可检索的结构化字段。

模式 4：属性键名规范化

老旧系统送来的属性键风格混乱（user id、service-version），统一改为下划线风格：

transform:
  error_mode: ignore
  trace_statements:
    - context: span
      statements:
        - replace_all_patterns(attributes, "key", "[ -]", "_")

replace_all_patterns 作用于全部键名，无需穷举每个属性——处理遗留系统的利器。

模式 5：过滤高基数指标

某些指标带了请求级标签（如每次调用一个 ID），会把时序库撑爆。用条件语句按指标名或标签特征丢弃，保留聚合价值高的指标——与高基数问题一文配合阅读。

模式 6：JSON 正文解析为属性

应用把 JSON 当字符串打进日志？ParseJSON 直接展开：

- context: log
  statements:
    - merge_maps(attributes, ParseJSON(body), "upsert") where IsString(body) and Len(body) > 0

JSON 的每个字段都成为可查询的日志属性。

模式 7：复用服务端 Span 的判断条件

给 span.kind == SERVER 的 Span 批量打标（如统一设置环境标签），用条件表达式一次覆盖所有入口 Span，避免逐服务配置。

模式 8：K8s 元数据提升到资源级

k8sattributes 处理器附带的 Pod 标签默认挂在记录级，用 OTTL 提升到 Resource 层（如 resource.attributes["team"] = attributes["k8s.pod.labels.team"]），让"按团队聚合指标"这类查询成为可能。

模式 9：响应耗时分档打标

按延迟把请求分为 fast/normal/slow 三档写入属性：

- set(attributes["perf_tier"], "slow") where duration > 2000000000
- set(attributes["perf_tier"], "fast") where duration < 200000000

分档标签之后可直接做聚合统计与告警条件。

模式 10：按环境过滤日志

多环境共用一个 Collector 时，按 resource.attributes["deployment.environment"] 把 dev 环境的 DEBUG 日志挡在门外，只让生产数据进入存储。

观测云落地：OTTL 与 DataKit Pipeline 的分工

观测云体系中，类似的数据处理由 DataKit Pipeline 承担：grok 提取字段、drop_key 删除字段、cover/replace 做脱敏，函数式脚本灵活度与 OTTL 相当，且支持在 DataKit 侧预处理后直传观测云，省掉自建 Collector 转换层的运维负担。

实操建议：

• 已有 OTel Collector 体系：转换逻辑放 Collector（OTTL），DataKit 只做 OTLP 接收与转发；
• 直连 DataKit 架构：用 Pipeline 完成解析与脱敏，配合观测云内置的敏感数据扫描规则（70+ 预置规则）兜底；
• 两套语法不要混用同一环节，处理链路越长越难排查。

常见问题（FAQ）

Q：OTTL 处理出错会影响数据流吗？ error_mode: ignore 下单条语句失败不影响整体；propagate 模式则会把错误数据丢弃——生产建议先用 ignore 观察再收紧。

Q：OTTL 能处理指标吗？ 可以，metric_statements 上下文支持改指标名、删属性、按条件丢弃数据点。

Q：性能开销大吗？ 转换是 CPU 密集操作，高流量下需监控 Collector 的 CPU 与处理延迟（见《监控 OpenTelemetry Collector》），必要时横向扩容。

Q：DataKit Pipeline 能实现 OTTL 全部功能吗？ 覆盖绝大多数清洗、解析、脱敏场景；个别 Span 语义级操作（如改 span.kind）需在 Collector 完成。选型按团队现有架构定。

系列阅读

• 上一篇：《OpenTelemetry 采样详解》
• 下一篇：《监控 OpenTelemetry Collector》
• 相关：《OTTL 转换语言详解》 · 《OpenTelemetry 敏感数据脱敏》 · 《返回索引》