前言¶
功能上线后，值班同学往往只能靠零散日志或事后翻代码还原现场。可观测性（日志、指标、链路、告警）如果和特性开发脱节，第一次用户报障就会变成「考古」而不是查数。
下面介绍 SkillHub 上的 ObservabilityAndInstrumentation（坐标 @user_3c6cb52e/observability-and-instrumentation-sh-k1xmdy，版本 1.0.0）。它把「先定义值班要问什么、再选信号、再落地埋点与验收」写进 SKILL.md，供 Cursor、Claude Code、Codex 等 Agent 在相关任务里按同一套步骤执行，而不是每次从零拼凑最佳实践。
这是什么¶
ObservabilityAndInstrumentation 是社区来源（community）的 Agent Skill，发布者为 user_3c6cb52e，在 SkillHub 分类为 it-ops-security，标签 requires_api_key=false，无需 API Key。Skill 包采用通用 SKILL.md 格式，声明支持 Claude Code、Codex、Hermes Agent、OpenClaw、QClaw、WorkBuddy 等多平台（platform: multi-platform），许可证为 MIT。
SkillHub 页面简介与包内描述一致，均为可观测性与埋点相关专用技能说明；具体能力以包内 SKILL.md 正文为准（通过官方下载地址安装后可读）。
核心功能¶
经从 SkillHub 注册表安装并核对包内 SKILL.md，该 Skill 主要指导 Agent 完成以下工作（均为文档内写明的能力，非运行时服务）：
-
界定使用边界：适用于即将上生产的功能、新服务/端点/后台任务/外部集成、告警规则评审、涉及 I/O、重试、队列或跨服务调用的 PR；并明确不用于正在发生的故障排障（应使用
debugging-and-error-recovery等其它 Skill）、性能剖析、上线日检查清单等场景。 -
埋点前定义「正常」：要求先写出 2～4 条值班工程师会问的问题，再为每个问题选择日志、指标或链路中的一种或多种信号（文档给出「指标看是否异常、链路看位置、日志看原因」的对应关系）。
-
结构化日志：稳定事件名、JSON 字段、统一日志级别语义；强制关联 ID（
requestId/x-request-id）；禁止记录密钥、令牌或未脱敏 PII。 -
指标（RED / USE）：对端点与外部依赖使用 RED（Rate、Errors、Duration）；对资源使用 USE；强调直方图与 p95/p99，限制标签基数（禁止 user ID、原始 URL、错误文案等作为 label）。
-
分布式追踪：以 OpenTelemetry 为主（含 Node SDK 与 auto-instrumentation 示例），在异步边界传播上下文，并说明采样策略。
-
告警：按用户可感知的症状告警而非单纯资源原因；每条告警需可执行、带 runbook、有阈值与持续时间，并区分 page 与 ticket 两级严重度。
-
验收清单：文档末尾提供检查项（on-call 问题与信号映射、结构化日志、RED 指标、链路贯通、告警试火、在 staging 仅靠遥测定位注入故障等）。
包内文末提到可参考 references/observability-checklist.md；当前从 SkillHub 下载的 1.0.0 包中仅含 SKILL.md 与 _meta.json，未包含该引用文件，使用时以主文档为准。
安装与启用¶
SkillHub 官方安装说明见 skillhub.cn/install/skillhub.md。页面关键词亦提示：根据该文档安装 observability-and-instrumentation-sh-k1xmdy。
1. 安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可执行（完整安装含默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2. 安装本 Skill 到当前 Agent 的 skills 目录¶
安装时必须用 --dir 指向当前客户端识别的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。
skillhub install observability-and-instrumentation-sh-k1xmdy --dir <你的 skills 目录>
常见路径（来自官方安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/
安装成功后，CLI 会从 https://api.skillhub.cn/api/v1/download?slug=observability-and-instrumentation-sh-k1xmdy 拉取包并解压到指定目录。具体是否需重启客户端以加载新 Skill，以你所用 Agent 的文档为准；官方安装页提醒错误目录会导致技能不被识别。
SkillHub 技能页还提供「将提示词发送给你的 AI 安装该 skills」的方式，适合在对话中让 Agent 按平台说明完成安装。
典型用法¶
启用后，在「为新功能加埋点」「评审可观测性不足的 PR」「设计告警」等任务中，可直接引用 Skill 名称或让 Agent 读取已安装的 SKILL.md。下面两段来自包内可复现的示例思路。
先写值班问题，再选信号（埋点前的模板）：
FEATURE: checkout payment retry
QUESTIONS ON-CALL WILL ASK:
1. What fraction of payments succeed on first attempt vs after retry?
2. When a payment fails permanently, why? (provider error? timeout? validation?)
3. Is the payment provider slower than usual?
→ Every signal below must help answer one of these.
结构化日志与关联 ID（Express 中间件片段，文档中的推荐写法）：
app.use((req, res, next) => {
req.id = req.headers['x-request-id'] ?? crypto.randomUUID();
req.log = logger.child({ requestId: req.id });
res.setHeader('x-request-id', req.id);
next();
});
OpenTelemetry 启动（文档要求在其他模块之前 import）：
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
const sdk = new NodeSDK({
serviceName: 'checkout-service',
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
经过上面的步骤，Agent 应按 Skill 中的 RED/USE、告警症状原则与 Verification 清单，输出具体改动建议或 PR 评审意见，而不是只增加 console.log。
适用场景与注意¶
适合谁：负责后端/平台、需要在发版前补齐可观测性的开发者；以及希望 Agent 在代码评审或新功能开发中统一埋点标准的团队。
平台与依赖：Skill 本身不调用外部 API（requires_api_key=false）。文档中的 TypeScript、Prometheus prom-client、OpenTelemetry 示例需与你的技术栈自行对齐；其它语言应遵循同一原则（结构化、关联 ID、RED/USE、低基数标签）。
与其它 Skill 的关系：正文多次引用 debugging-and-error-recovery、performance-optimization、shipping-and-launch、security-and-hardening 等名称；这些包不会随本 Skill 自动安装，需单独在 SkillHub 搜索安装。
元数据差异：SkillHub 列表分类为 it-ops-security，包内 front matter 的 category 为「开发者工具」，以你使用的注册表展示为准即可。
社区数据（SkillHub 页面，2026-10-21 抓取）：评分 100000，下载 1091 次，安装计数页面显示为 0；安装量以你本地 CLI 操作为准。
结尾¶
ObservabilityAndInstrumentation 把可观测性从「事后补日志」收成可执行的 Agent 流程：先问题、再信号、再日志/指标/链路/告警，最后用清单验收。若你在 SkillHub 上检索 IT 运维与安全类技能，可用坐标 @user_3c6cb52e/observability-and-instrumentation-sh-k1xmdy 定位。
- SkillHub 页面：https://www.skillhub.cn/skills/user_3c6cb52e/observability-and-instrumentation-sh-k1xmdy
- API 条目：https://api.skillhub.cn/user_3c6cb52e/observability-and-instrumentation-sh-k1xmdy
- 安装说明：https://skillhub.cn/install/skillhub.md
