otel-ottl

OpenTelemetry 转换语言（OTTL）

OTTL 可在 Collector 组件中转换或筛选遥测数据。本技能固定使用 collector-contrib v0.163.0。函数、路径、默认值和功能门的可用性因版本而异；如果用户使用的版本不同，请对照相应的上游标签进行核实。

v0.162.0 和 v0.163.0 中 OTTL 功能门的日期状态见 references/functions.md。

工作流

1. 选择组件。 transform 会重写数据，filter 会丢弃数据，tail_sampling 会决定是否保留链路，routing 会将遥测数据发送到管道。组件决定其可用的上下文和函数。
2. 选择可用的最低层级上下文。 较低层级的上下文可以读取其父级（例如，span 可以读取 resource.attributes），但父级无法读取子级。对于数据点属性，请使用 datapoint，而不要遍历 metric.data_points。
3. 核实每个发出的函数，然后编写语句。 在 references/functions.md 中确认每个函数的准确标识符和签名。如果找不到某个标识符，请将其视为不受支持，而不要推导或替换成看似合理的名称。set 或 delete_key 等编辑器会修改数据，并且可能带有 where 条件。ParseJSON 和 IsMatch 等转换器会返回值，不会修改数据。
4. 明确设置错误行为。 ignore 会记录语句错误并继续；silent 会继续执行但不记录错误；propagate 会返回错误，并可能导致组件丢弃载荷。Transform 和 filter 默认使用 ignore；transform 的默认错误功能门已于 v0.162.0 移除，因此在 --feature-gates 中指定它会导致启动失败（历史记录：otel-collector 技能中的 transform 特殊情况）；filter 的功能门则已稳定，无法禁用。Routing 在其 beta 默认错误功能门启用时也默认使用 ignore。对于 routing，ignore 会将发生错误的载荷发送到 default_pipelines；请配置此回退，否则载荷会被丢弃。
5. 端到端验证。 验证准确的 Collector 版本（从 v0.163 起，validate 也会解析 routing connector 条件），然后发送已知遥测数据并检查 file-exporter 输出。请使用 telemetrygen recipe。

set(span.attributes["env"], "prod") where resource.attributes["env"] == nil

仅加载任务所需内容

• 上下文 — 精确路径、层级、枚举和请求元数据。
• 函数 — 编辑器／转换器签名及各版本的可用性。
• 快速参考 — 组件 YAML、示例、转义、故障排除和安全骨架。

对于单个路径或函数，请只阅读相关章节，而不要加载完整目录。

安全性与正确性检查

• 转换前，先对可选或多态输入进行保护：where x != nil、IsString(x) 或相应的类型检查。
• 对仅处理 JSON 对象的场景，在调用 ParseJSON 前同时检查类型和形状，例如 IsString(log.body) and IsMatch(log.body.string, "(?s)^\\s*\\{.*\\}\\s*$")。RE2 的 (?s) 标志允许对象包含换行符。解析后再检查 IsMap，无法阻止数组或标量 JSON 被解析。
• 对固定版本的请求，请根据对应的发布标签确认所有选用的路径和函数； 不要假定此技能 v0.163 基准中列出的函数在较早版本中存在。对于 v0.156 的 JSON 对象解析， ParseJSON、IsString 和 IsMatch 均可使用，不受 v0.157 的 alpha lambda 功能门控限制。
• 请求元数据为只读，且可能包含凭据。仅复制明确列入允许列表的非敏感键。OTLP 元数据路由需要在接收器上设置 include_metadata: true。 HTTP/客户端标头的拼写形式可能保留原样（otelcol.client.metadata["X-Tenant"][0]）； gRPC 元数据键为小写（otelcol.grpc.metadata["x-tenant"][0]）。
• 自 v0.156 起，路由 request 上下文已弃用；请使用 otelcol.client.metadata 或 otelcol.grpc.metadata。
• 针对日志记录的共享资源或范围数据重写，需要设置 flatten_data: true，并启用 alpha transform.flatten.logs 功能门控。此操作会复制并重新分组数据；请勿意外启用。
• 自 v0.161 起，set(target, nil) 不再是无操作：ottl.set.allowNil 功能门控在 v0.161 中进入 beta 阶段，并在 v0.162 中稳定（无法禁用）。nil 值会清空 map、slice 或 pcommon.Value 目标（会创建一个值为空的属性键），并在标量目标上报错。如果目标在输入缺失时必须保持不变，请使用 where source != nil 保护。
• 对标识符进行哈希并不一定能将其匿名化。保留个人数据的确定性哈希前，请遵循组织的数据处理政策。

常见语法陷阱

• 在 Collector YAML 中，将 OTTL 替换反向引用 ${1} 写作 $${1}。像 $1REDACTED 这样的替换内容会被视为字面值，且不会报错，但捕获内容替换会静默失败。
• Go RE2 不接受较大的计数重复模式，例如 (.{1024}).*；请使用带 nil/类型保护的 Substring 和 Len，或对 map 使用 truncate_all。
• 当前的 span 事件路径使用 spanevent.*，而非 span_event.*。缓存路径需限定上下文，例如 span.cache["parsed"]。
• 当 YAML 中的 map 字面量包含冒号后的空格时，包含该字面量的 OTTL 语句必须加引号，例如 'set(log.attributes["a"], {"foo": "bar"})'；否则 YAML 会将 : 解析为映射。
• 自 v0.159 起，多态 pcommon.Value 路径会根据其底层类型进行比较；map 和 slice 仅支持相等和不等比较，而原始值也支持大小比较。
• 使用 Decode(value, "base64")；Base64Decode 已在 v0.161 中移除。
• OTTL 字符串中的正则表达式转义符需双写（\\d、\\s、\\.）。

上游来源

• OTTL 软件包
• Transform 处理器
• Filter 处理器
• Routing 连接器