前言¶
功能上線後，值班同學往往只能靠零散日誌或事後翻代碼還原現場。可觀測性（日誌、指標、鏈路、告警）如果和特性開發脫節，第一次用戶報障就會變成「考古」而不是查數。
下面介紹 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
