1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | otel-ottl |
| 作者/维护者 | Dash0（GitHub 官方组织 dash0hq，OpenTelemetry 原生可观测性厂商） |
| 来源链接 | https://github.com/dash0hq/agent-skills/tree/main/skills/otel-ottl |
| 许可证 | Apache-2.0（仓库根目录声明，GitHub API 确认） |
| GitHub Stars / Forks | 80 / 11（GitHub API 获取；为 agent-skills 技能合集仓库整体数据，含 4 个 OpenTelemetry 相关技能，非本子技能个体数据，详见第 7 章前说明） |
| 最新版本 | npm 包 @dash0/agent-skills v1.3.1；本技能自身 metadata 版本 1.0.0 |
| 安装方式 | npx skills add 一条命令、Claude Code 插件市场、npm 包引入，或手动复制目录 |
2. 功能介绍与亮点
otel-ottl 教 Agent 如何编写和调试 OpenTelemetry Transformation Language（OTTL）表达式——这是 OpenTelemetry Collector 里 transform、filter、attributes、routing 等多种组件共用的数据变换语言，用来在数据落地前过滤、改写、脱敏或路由遥测数据。核心内容包括：
- 完整语法参考：路径表达式（
span.attributes["http.method"]）、枚举常量、比较/逻辑运算符 - 函数库速查：区分“转换类函数”（返回新值，如
ToUpperCase、Concat）与“编辑类函数”（原地修改，如set、delete_key），并提供完整函数参考文件 - 三步验证工作流：先用
otelcol validate校验语法，再接debugexporter 核对实际输出，最后才切换到生产 exporter - 专门的敏感数据脱敏指南（替换/掩码/哈希/删除/丢弃五种脱敏策略）与高基数属性归一化指南
- 明确区分编译期错误与运行期错误，并给出
error_mode三种取值（ignore/propagate/silent）的适用场景对照
内容完全由 Markdown 文档构成，不含需要执行的可疑脚本；本子技能自 2026-02-26 首次提交以来持续维护，最近一次专属提交为 2026-07-24，仓库整体每天都有提交（含 CI 门禁的评测流水线）。
3. 适用场景
固定分类：DevOps 与基础设施
- 编写或调试 Collector 中 transform/filter 处理器 OTTL 表达式的后端、SRE 工程师
- 需要对遥测数据做实时脱敏（如屏蔽数据库语句中的敏感字段）或降低高基数属性的团队
- 排查 OTTL 表达式编译失败或运行时静默出错（
error_mode配置不当）的场景
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | README/INSTALL.md 提供 /plugin marketplace add dash0hq/claude-marketplace 一条命令安装 |
| Codex | ✅ 原生支持 | INSTALL.md 给出克隆到 ~/.agents/skills/ 的自动发现路径 |
| OpenClaw | ✅ 原生支持 | INSTALL.md 专列 Openclaw 章节，给出克隆到 ~/.openclaw/skills/ 的安装步骤 |
| Hermes Agent | ❓ 未验证 | 已抓取材料未点名 Hermes Agent；npx skills add 通用安装方式按 Agent Skills 规范面向任意兼容工具，但无具名确认 |
（仅基于已抓取的 README 与 INSTALL.md 判断，未为兼容性单独发起搜索）
5. 推荐理由
OTTL 表达式一旦写错，轻则数据变换不生效，重则在生产环境静默丢数据或误删关键字段——而这类语法多数通用编码 Agent 训练数据覆盖有限。otel-ottl 把语法、函数库、验证流程和脱敏/降基数等高频实操场景整理成一份可直接加载的参考，并配套“先本地验证再上生产”的工作流，减少 Agent 凭记忆瞎猜表达式的风险。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Dash0 为已完成 1.1 亿美元 B 轮融资、由 Instana 原团队创立的 OpenTelemetry 原生可观测性厂商，官方出品；所属技能合集整体 80 stars，规模尚小，暂无独立于厂商自身之外的大规模第三方讨论 |
| 可用性 | 9 | npx skills add 一条命令或插件市场安装，文档采用主文件+分主题参考文件的结构，覆盖语法/函数/错误处理/性能/脱敏多个维度；本子技能近 3 个月内持续有专属提交；无需任何付费依赖 |
| 安全性 | 9 | 见下方安全检查清单 |
综合评分：8.3（三项均值）
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① shell 命令及权限范围 | 技能本身为纯 Markdown 参考内容，不含需要执行的脚本；验证工作流建议运行上游官方 otelcol 命令行工具，由用户自行安装运行 |
| ② 联网外发数据 | 技能本身不发起任何网络请求 |
| ③ API key/凭据 | 不涉及，纯语法与配置知识查询 |
| ④ 可疑指令 | 已通读 SKILL.md 全文，未发现越权操作或隐藏指令 |
| ⑤ 作者信誉 | Dash0 官方 GitHub 组织，多名具名工程师持续提交，仓库设有 CI 评测门禁 |
| ⑥ License | Apache-2.0，仓库根目录明确声明 |
| ⑦ 维护时间 | 本子技能最近一次专属提交在 2026-07-24，仓库整体最近一次提交为当天 |
7. 跟同类 Skills 相比的优势
（dash0hq/agent-skills 是 4 个 OpenTelemetry 相关技能的合集仓库，整体 80 stars 代表全部技能的合计数据，不代表 otel-ottl 单个子技能的个体热度）
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
| Honeycomb otel-instrumentation | 教应用代码里如何打点（Span/属性/异常事件），覆盖 7 种语言 SDK | 关注“如何产生遥测数据”，不涉及数据产生后在 Collector 侧如何过滤、改写或脱敏 |
| OllyGarden otel-collector | 按组件（receiver/processor/exporter 等）查询 Collector 权威配置项与稳定性等级 | 关注“某个组件该怎么配”，遇到 OTTL 表达式本身的写法会明确指向另一专属技能，不覆盖 OTTL 语法与函数细节 |
| 直接查阅 opentelemetry-collector-contrib 官方文档 | 分散在各处的函数签名与组件说明 | 缺少统一整理的“语法→函数→验证→常见模式”结构，需要工程师自行拼凑多处文档并判断适用版本 |
现有同类技能分别覆盖“如何产生数据”（instrumentation）与“组件怎么配”（collector），otel-ottl 补的是两者之间的转换与治理层——数据产生之后、落地之前，如何过滤、脱敏、改写。
8. 用户评价
该技能目前在 Reddit、Hacker News 等第三方平台尚无具名用户评价。所属 dash0hq/agent-skills 仓库的 Issue 记录显示多次围绕其他子技能（如 otel-instrumentation 的日志格式细节）的具体改进讨论，反映仓库整体有真实使用反馈循环，但尚未见到专门针对 otel-ottl 的第三方讨论。
9. 其他补充
同一仓库下还有 otel-collector（Collector 部署配置）、otel-instrumentation（应用侧埋点）、otel-semantic-conventions（属性命名规范）三个姊妹技能，安装机制相同，可按需单独或整体安装。文档以英文撰写，接受社区 Pull Request。
10. 安装使用方式
方式一（推荐）：skills CLI，通用
npx skills add https://github.com/dash0hq/agent-skills --skill otel-ottl方式二：Claude Code 插件市场
/plugin marketplace add dash0hq/claude-marketplace
/plugin install dash0-agent-skills@dash0方式三：手动安装
将 skills/otel-ottl 目录复制到 .claude/skills/ 等 Agent 技能目录即可使用。安装后无需重启，下次描述“写一个 OTTL 表达式”“Collector 里怎么脱敏这个字段”等需求时会自动加载。
11. 注意事项
- 本技能只覆盖 OTTL 语言本身的语法与用法，不包含 Collector 各组件的配置项细节（对应 otel-collector 技能）或应用侧埋点写法（对应 otel-instrumentation 技能）
- 验证工作流依赖用户自行安装的
otelcol命令行工具，技能本身不会自动执行任何命令 - Codex、OpenClaw 已有明确安装路径，Hermes Agent 兼容性尚无可验证材料，请自行测试后使用