1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | otel-instrumentation |
| 作者/维护者 | Honeycomb（GitHub 官方组织，可观测性厂商） |
| 来源链接 | https://github.com/honeycombio/agent-skill/tree/main/honeycomb/skills/otel-instrumentation |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars / Forks | 17 / 7（GitHub API 获取；为 agent-skill 技能合集仓库整体数据，含 9 个技能与 2 个 agent，非本子技能个体数据，详见第 7 章前说明） |
| 最新版本 | 插件版本 1.1.0（仓库 .claude-plugin/plugin.json 获取） |
| 安装方式 | Claude Code / Codex 插件市场一键安装，或手动复制技能目录 |
2. 功能介绍与亮点
otel-instrumentation 教工程师如何用 OpenTelemetry（一个开放、厂商中立的可观测性标准）给自己的应用代码打点，而不是教你在某个平台里怎么点鼠标查数据。核心内容包括：
- OTLP 环境变量与 SDK 初始化配置（覆盖 Go、Python、Node.js、Java、Ruby、.NET、Rust 多语言参考文件）
- 一套判断“该不该为这段代码创建新 Span”的决策表（是否重要、是否可聚合），避免埋点过多或过少两种常见错误
- 自定义 Span、属性（Attributes）、异常事件（Exception Events）的写法与常见踩坑（如“静默鉴权失败”——漏配 Header 导致数据悄悄丢失且无报错）
- 头部采样（Head Sampling）与尾部采样（Tail Sampling）的取舍说明，附具体数学换算示例
- AWS Lambda 场景的专门参考（OTel Layer 与手动 SDK 配置的取舍、forceFlush 处理等）
内容完全由 Markdown 文档与参考资料构成，不含需要执行的可疑脚本；仓库最近一次围绕本技能的提交发生在 6 天前，持续有具名工程师维护。
3. 适用场景
固定分类：DevOps 与基础设施
- 已引入或计划采用 OpenTelemetry 的工程师，编写 Span 与属性埋点时用 Agent 加载获取标准化实操指导
- 排查“打了点却查不到数据”一类静默失败问题的团队
- 需要在采样成本与调试完整性之间做权衡决策的 SRE/DevOps 工程师
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——仓库提供
.claude-plugin清单，claude plugin marketplace add honeycombio/agent-skill一条命令安装 - Codex：✅ 原生支持——README 明确提供
codex plugin marketplace add honeycombio/agent-skill安装命令 - OpenClaw：❓ 未验证——README 列出的受支持工具（Cursor、Cline、Windsurf、Amazon Q 等）未点名 OpenClaw
- Hermes Agent：❓ 未验证——同上，未见明确点名
（仅基于已抓取的 README 与仓库结构判断，未为兼容性单独发起搜索）
5. 推荐理由
Honeycomb 官方出品的 OpenTelemetry 仪表化实操指南，教你写出可查询的追踪埋点。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Honeycomb 为官方可观测性厂商出品，技能随插件被 Claude Code/Codex/Cursor 等十余种工具收录分发；仓库 issue/PR 记录显示有非员工的外部工程师（如 ML 工程师、其他公司 CTO）实际使用并反馈问题，但尚未见大规模第三方独立讨论 |
| 可用性 | 9 | 一条命令安装，SDK 配置、多语言代码示例、常见踩坑均有独立参考文件；最近一次内容更新在 6 天内；Honeycomb 提供免费层（每月 2000 万事件），无需付费即可上手 |
| 安全性 | 9 | 技能本身为纯 Markdown 指导内容，不含需执行的可疑脚本；发送遥测数据到 Honeycomb 是该技能的既定透明目的，非隐蔽外发；API Key 通过标准环境变量传递；MIT 完全开源可审计 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① shell 命令及权限范围 | 内容为配置指导与代码示例，不含需要执行的 shell 脚本 |
| ② 联网外发数据 | 遥测数据发往 Honeycomb API 是该技能的核心透明目的，用户可见可控 |
| ③ API key/凭据 | 通过标准环境变量 OTEL_EXPORTER_OTLP_HEADERS 提供，文档明确提示常见配置失误 |
| ④ 可疑指令 | 通读全文及多份参考文件，未发现越权操作或隐蔽指令 |
| ⑤ 作者信誉 | Honeycomb 官方 GitHub 组织，多名具名员工（含 OpenTelemetry 治理委员会成员）持续提交 |
| ⑥ License | MIT，明确 |
| ⑦ 维护时间 | 最近一次针对本技能的提交在 6 天内 |
7. 跟同类 Skills 相比的优势
（honeycombio/agent-skill 是多技能合集仓库，仓库整体 17 stars 代表全部 9 个技能与 2 个 agent 的合计数据，不代表 otel-instrumentation 单个子技能的个体热度）
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
| Dynatrace DQL Essentials | Dynatrace 平台专有查询语言语法教学 | 教你怎么查已收集好的数据，不涉及如何在应用代码里打点采集数据 |
| Datadog dd-apm | Datadog APM 追踪排查工作流 | 聚焦特定平台的排查流程，不覆盖从零用开放标准搭建仪表化的过程 |
| Grafana OSS | 开源可视化仪表盘搭建 | 面向仪表盘配置与展示，不涉及应用代码层的 Span/属性写法 |
现有同类技能大多聚焦“如何在某个平台里查询或展示已有数据”，otel-instrumentation 补的是更上游的一层——用开放、可移植的 OpenTelemetry 标准把数据正确采集出来，换到任何兼容 OTLP 的后端都能复用。
8. 用户评价
- GitHub 用户 phitoduck（一名 ML 工程师）在 Issue #31 中提出
span.record_exception()已被弃用、应改用什么方式记录异常的具体问题，反映真实动手使用场景（issues/31） - GitHub 用户 queen-of-code（另一家公司的联合创始人兼 CTO）在 Issue #20 中报告 Cursor 平台的安装步骤在某次更新后失效，属实际部署中发现的问题（issues/20）
9. 其他补充
仓库文档以英文为主；除本技能外，合集还包含 observability-fundamentals（概念基础）、production-investigation（生产排查工作流）、slos-and-triggers 等 8 个技能，以及 2 个自主排查用的 agent；接受社区 Pull Request，近期已有多名外部贡献者提交过功能改进。
10. 安装使用方式
方式一（推荐）：Claude Code 插件市场
claude plugin marketplace add honeycombio/agent-skill
claude plugin install honeycomb方式二：OpenAI Codex
codex plugin marketplace add honeycombio/agent-skill方式三：手动安装
将 honeycomb/skills/otel-instrumentation 目录复制到 .claude/skills/ 等 Agent 技能目录即可使用；若需连接自己的 Honeycomb 租户发送真实遥测数据，需另行设置 OTEL_EXPORTER_OTLP_ENDPOINT 与 OTEL_EXPORTER_OTLP_HEADERS（含 API Key）。安装后无需重启，下次触发相关提问（如“帮我加 tracing”）即会加载。
11. 注意事项
- 本技能只教如何用 OpenTelemetry 打点与配置，不包含 Honeycomb 平台本身的查询/排查能力（那属于同合集内的 query-patterns、production-investigation 等技能）
- 若使用其平台专属的 MCP Server 深度联动功能，需要 Honeycomb 账号；但仅使用本技能的 OTel 仪表化知识本身不强制要求付费
- 跨 Agent 兼容性目前只验证了 Claude Code 与 Codex，OpenClaw / Hermes Agent 用户请自行测试后使用