1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | observability-and-instrumentation |
| 所属仓库 | addyosmani/agent-skills（子技能，合集仓库） |
| 作者/维护者 | Addy Osmani（Google 工程师，Web 性能与前端工具领域知名开发者） |
| 来源链接 | https://github.com/addyosmani/agent-skills/tree/main/skills/observability-and-instrumentation |
| 许可证 | MIT（GitHub API 确认，来自仓库整体） |
| GitHub Stars / Forks | 仓库整体 81,000 ★ / 8,738 forks（GitHub API，2026-07-31）；合集仓库星数不代表本子技能自身热度 |
| 最新版本 | 仓库整体 Release 0.6.5（2026-07-26，GitHub Releases API） |
| 安装方式 | npx skills add addyosmani/agent-skills --skill observability-and-instrumentation |
2. 功能介绍与亮点
面向“生产行为不可见、出问题只能靠考古”这一痛点，把埋点方法论拆成可直接照抄的流程：
- 先问问题再埋点：要求先写下值班工程师会问的 2–4 个具体问题，再决定埋哪些信号，避免“埋了很多点却答不上关键问题”
- 三种信号分工：结构化日志答“这一次具体发生了什么”、指标答“多频繁/多快”、追踪答“时间花在哪一跳”，各自给出成本模型与代码示例
- 结构化日志规范：事件名+机器可读字段取代字符串拼接、四级日志对应值班动作、强制 correlation ID 贯穿单次请求、明文禁止记录密钥/令牌/完整 PII
- RED/USE 双指标框架 + 基数红线：请求类服务用 Rate/Errors/Duration，资源类用 Utilization/Saturation/Errors；明确禁止把用户 ID、原始 URL 等无界值当作指标标签
- OpenTelemetry 分布式追踪落地代码：自动埋点、手动 span、跨异步边界上下文传播、采样策略均给出具体片段
- 告警四条铁律：只对症状告警、必须可执行、必须带 runbook 链接、只设 page/ticket 两档，避免噪音训练团队忽略
- 与同仓库
debugging-and-error-recovery、performance-optimization、shipping-and-launch在正文开头明确划清各自不覆盖的范围，避免功能重叠
内容为纯 Markdown 指导+代码片段（非自动执行），配套独立参考文件 references/observability-checklist.md。
3. 适用场景
所属分类：DevOps 与基础设施
适合独立开发者与小团队工程师在功能上线前规划日志/指标/追踪埋点，或在“生产出过问题但看不出发生了什么”复盘时补齐可观测性；也适合 Code Review 阶段用来检查 PR 是否遗漏必要的遥测代码。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | ✅ 原生支持 | 官方 /plugin marketplace add 安装路径 |
| Codex | ✅ 支持 | README 推荐的 npx skills add 安装器（vercel-labs/skills）文档列出 Codex 路径 |
| OpenClaw | ✅ 支持 | 同一安装器 Supported Agents 表格列出 OpenClaw |
| Hermes Agent | ✅ 支持 | 同一安装器 Supported Agents 表格列出 Hermes Agent |
5. 推荐理由
多数可观测性指南要么绑定具体 APM 厂商，要么泛泛而谈“要做监控”。本技能给出与厂商无关的方法论：先倒推值班问题再决定埋点、明确基数红线与告警铁律、代码示例可迁移到任意技术栈，纯 Markdown 零配置即可照抄。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | 该子目录暂无已合并的独立外部贡献 PR；曾有两名外部开发者各自尝试为可观测性这一功能点提交新增/扩展提案，均未被合并；仓库整体 8 万+ ★ 属整个合集，不代表本子技能自身热度 |
| 可用性 | 9 | 纯 Markdown 零配置，复制即用；配套参考清单文件可正常访问无死链；子目录最近一次实质更新 2026-06-11，维护活跃；无付费依赖 |
| 安全性 | 9 | 不执行 shell、不联网外发；不要求 API Key/凭据；正文本身明文要求“绝不记录密钥/令牌/完整 PII”，属安全最佳实践指导；作者身份可查证，License 明确 |
综合评分：8.0
安全检查清单：①无 shell 执行 ②无网络外发（纯文档指导） ③不要求 API Key/凭据 ④未见可疑指令，且正文自带防泄漏红线 ⑤作者信誉良好 ⑥License 明确（MIT） ⑦最近维护 2026-06-11，活跃。
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 差异 |
|---|---|---|
| redis-observability（redis-agent-skills） | Redis 官方出品，聚焦 Redis 自身指标（内存/连接/慢查询）与告警阈值 | 只覆盖单一数据库产品的运维监控，不涉及应用层日志规范、追踪埋点、告警设计方法论 |
| agent-observability-replay-trace（datadog-labs-agent-skills） | Datadog 官方出品，针对已埋点的生产 trace 做“改代码→重放→比对”调试循环 | 面向埋点完成之后的调试环节且绑定 Datadog 平台；本技能是厂商无关的埋点方法论，覆盖“怎么埋”而非“埋完之后怎么调” |
| cloud-monitoring-metric-selection（google-skills） | Google Cloud 官方出品，指导在 GCP Cloud Monitoring 里挑选指标类型 | 绑定 GCP 产品与控制台操作；本技能不依赖任何具体云厂商或 APM 平台，代码示例可跨技术栈迁移 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。仓库内曾有外部开发者分别提交过一次新增可观测性技能的提案与一次扩展本技能内容的提案，两者均处于未合并状态。
9. 其他补充
配套 references/observability-checklist.md 提供精简版自检清单，含上线前的“仪表化门禁”（pre-launch instrumentation gate），可作为 Code Review 时的快速核对表。
10. 安装使用方式
- 推荐方式：
npx skills add addyosmani/agent-skills --skill observability-and-instrumentation - Claude Code 插件市场：
/plugin marketplace add addyosmani/agent-skills后/plugin install agent-skills@addy-agent-skills - 手动安装：复制
skills/observability-and-instrumentation/目录及引用的references/observability-checklist.md文件 - 安装后无需重启；涉及“加日志”“加监控”“加追踪”“生产问题排查不出原因”等意图时自动触发
11. 注意事项
- 本技能只提供方法论、代码示例与检查清单，不会替用户接入实际的日志/指标/追踪后端（Prometheus、OpenTelemetry Collector 等仍需自行部署）
- 手动安装需连带复制
references/文件，否则文中引用失效；官方安装器无此问题 - 作为合集仓库中的一个子技能，单独安装不含其余子技能（如同仓库互补的
debugging-and-error-recovery、shipping-and-launch需单独安装）