用途
OTTL（OpenTelemetry Transformation Language）用于在 OpenTelemetry Collector 组件内部转换或筛选遥测数据。本技能面向需要编写或调试 OTTL 语句的场景，例如在 transform 中重写数据、在 filter 中丢弃数据、在 tail_sampling 中决定是否保留 trace，以及在 routing 中把遥测数据分发到不同 pipeline。
本技能锚定 collector-contrib v0.162.0。函数、路径、默认值和 feature gate 的可用性随版本变化；当用户版本不同时，应依据对应的上游 tag 进行核对。
主要能力
- 组件选择：transform 负责重写，filter 负责丢弃，tail_sampling 决定是否保留 trace，routing 负责将遥测数据发送到 pipeline。组件决定其可用的上下文与函数。
- 上下文选择：优先选择可用的最低层级上下文。低层级上下文可以读取其父级（例如 span 可以读取 resource.attributes），但父级不能读取子级。对于数据点属性应使用 datapoint，而不是遍历 metric.data_points。
- 函数校验：在编写语句前，需在 references/functions.md 中确认每个函数的准确标识符与签名。若某标识符不存在，应视为不支持，而不是推导或替换为看似合理的名称。
- 编辑器与转换器区分：set、delete_key 等编辑器会修改数据，并可带 where 条件；ParseJSON、IsMatch 等转换器返回值，不修改数据。
- 错误行为设置：ignore 记录语句错误并继续；silent 不记录日志直接继续；propagate 返回错误，可能导致组件丢弃负载。transform 与 filter 默认 ignore；transform 的 default-error gate 在 v0.162.0 中已被移除，因此在 --feature-gates 中命名它会导致启动失败；filter 的 gate 已稳定且无法禁用。routing 同样默认 ignore，其 beta 的 default-error feature gate 处于启用状态。对于 routing，ignore 会把出错的负载发送到 default_pipelines，需要配置该回退，否则负载会被丢弃。
- 端到端验证：确认确切的 Collector 版本，然后发送已知遥测数据并检查 file-exporter 输出，可使用 telemetrygen 配方。
示例：
set(span.attributes["env"], "prod") where resource.attributes["env"] == nil
使用方式
按需加载内容：
- Contexts：确切的路径、层级、枚举与请求元数据。
- Functions：编辑器/转换器签名与版本可用性。
- Quick reference：组件 YAML、配方、转义、故障排查与安全骨架。
若只需单个路径或函数，只读取相关章节，而不加载完整目录。
安全与正确性检查点
- 在转换前对可选或多态输入做守卫：where x != nil、IsString(x) 或相应的类型检查。
- 仅处理 JSON 对象时，在调用 ParseJSON 前同时守卫类型与形状，例如 IsString(log.body) 与 IsMatch(log.body.string, "(?s)^\s*\{.\}\s$")。RE2 的 (?s) 标志允许包含换行的美化输出对象。解析后再检查 IsMap 并不能阻止数组或标量 JSON 被解析。
- 在版本锚定的请求中，需针对该 release tag 确认每个所选路径与函数；不要假设本技能 v0.162 锚点中列出的函数在更早版本中存在。对于 v0.156 的 JSON 对象解析，ParseJSON、IsString 与 IsMatch 无需 v0.157 的 alpha lambda feature gate 即可使用。
- 请求元数据为只读，且可能包含凭据。只复制明确列入允许清单且非敏感的键。OTLP 元数据路由需要在 receiver 上设置 include_metadata: true。HTTP/client header 拼写可能保留其形式（otelcol.client.metadata["X-Tenant"][0]）；gRPC 元数据键为小写（otelcol.grpc.metadata["x-tenant"][0]）。
- routing 的 request context 自 v0.156 起已弃用；应使用 otelcol.client.metadata 或 otelcol.grpc.metadata。
- 对共享 resource 或 scope 数据进行日志记录特定的重写，需要 flatten_data: true 以及 alpha 的 transform.flatten.logs gate。这会复制并重新分组数据，不要意外启用。
- 自 v0.161 起，set(target, nil) 不再是空操作：ottl.set.allowNil gate 在 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-event 路径使用 spanevent.，而不是 span_event.。缓存路径带上下文限定，例如 span.cache["parsed"]。
- 当 YAML 中 : 后带空格时，任何包含映射字面量的 OTTL 语句都需加引号，例如 'set(log.attributes["a"], {"foo": "bar"})'；否则 YAML 会把 : 解析为映射。
- 自 v0.159 起，多态 pcommon.Value 路径按其底层类型比较；map 与 slice 仅支持相等与不等，原始值还支持排序。
- 使用 Decode(value, "base64")；Base64Decode 在 v0.161 中已被移除。
- OTTL 字符串内的正则转义需双写（\d、\s、\.）。
适用场景
适用于在 OpenTelemetry Collector 中编写、审查或调试 OTTL 语句，涉及 transform、filter、tail_sampling、routing 等组件，以及需要按版本核对函数与路径可用性的场景。
限制
本技能锚定 collector-contrib v0.162.0，其他版本需自行核对上游 tag。资料未提供官方文档链接、安装命令、收费信息或平台支持范围，相关内容暂未提供。