agentleFS
LinuxSuRenLinuxSuRen/my-dsh-skills/skills/observability-design/SKILL.md

observability-design

Skill2 starsChanged 39 days agoMITView on GitHub

可观测性设计规范:功能与插桩同步交付、埋点前先写 on-call 问题、metrics/trace/log 三信号分工、结构化日志、AI 变更挂 gen_ai 元数据与前后对照指标。大量 AI 代码下人类把控的第三道闸门(上线后可回放)。

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

可观测性设计规范

核心原则:无法观测的代码就是无法运维的代码。AI 时代代码产出速度远超人的理解速度,把握控力从"读完全部代码"转移到"系统行为可回放"——这是合并评审之后的人类第三道闸门。Google 的生产级 AI 代码质量研究正是靠"每行上线代码可观测"才完成的。

1. 插桩同步交付

  • 新功能的插桩(日志/指标/追踪)与功能代码同一个 PR 交付,像测试一样对待——"以后补埋点"等于没有。
  • 改造存量功能时,本次触及的链路至少补齐出入口日志与一个健康指标,不做全量翻新。

2. 先写问题,再写埋点

  • 动手埋点前,先写下 on-call 工程师半夜被叫醒时会问的 2-4 个问题(如"上传为什么卡住""设备掉线了吗""这条命令发出去没有")。
  • 每个信号必须能回答其中之一;答不任何问题的埋点删掉——为埋而埋的信号只会稀释真正的告警。
  • 用户报障路径必须有对应观测面:每个对外错误码都能在日志里搜到(与 user-facing-errors 的 [CODE] cause 可搜索前缀打通)。

3. 三信号分工

信号回答的问题用法
metric出事了(that)聚合数值 + 阈值告警:速率、错误率、时延、队列深度;告警必须是可行动的
trace在哪(where)请求/任务 ID 贯穿跨进程调用链,出入口 span 必带耗时与结果
log为什么(why)事件明细,供回放与归因
  • 跨服务调用必须传递 request id / trace id,否则排查时只能对时间戳猜。
  • 告警风暴治理:同源告警聚合、边沿触发(见 edge-offline-pipeline-dev 的告警状态机)。

4. 结构化日志

  • 事件用稳定事件名 + 键值字段,不用自然语言插值:upload_retry file=x attempt=3 wait=30s 而非 retrying upload for x after failure——前者可 grep 可聚合。
  • 分级沿用 arch-dev-workflow 的日志分层:stdout 分级(高频 debug)、关键链路出入口必须 info、持久化业务/审计日志分离。
  • 禁止把高频循环内的明细打 info;禁止无字段纯文本日志进关键路径。
  • 技术根因只进日志,用户只见错误码+提示(user-facing-errors);脱敏与留痕是同一件事的两面。

5. AI 变更的可观测

  • AI 参与的批量改动挂元数据:遵循 OpenTelemetry GenAI 语义约定(gen_ai.*:模型、请求/响应 token、工具调用),使"哪次行为由哪个模型在什么上下文产生"与系统运行指标在同一条 trace 可关联;无 OTel 设施时至少在审计日志里记(模型/工具、任务摘要、时间、变更范围)。
  • 前后对照指标:AI 大批量改动合并后,对该区域建立前后对照——回滚率、事故/告警增量、性能(CPU/内存/时延)、静态分析新增告警数;连续观察一个周期,异常即触发复查。
  • agent 自身的执行行为同样可观测:任务耗时、返工次数、验证失败的改动占比——用结果指标而非体感评估 AI 工作流(人对 AI 增益的自评系统性失真,METR RCT 实测自评 +20% 而实际 -19%)。

6. 检查清单(功能上线前)

  1. 出入口都有日志且带 trace/request id?
  2. 失败路径有日志(不只是成功路径)?
  3. 每个对外错误码都能在日志中搜到现场?
  4. 至少一个健康指标 + 可行动的告警阈值?
  5. 埋点能回答写下的那 2-4 个 on-call 问题?
  6. AI 批量改动的区域已纳入前后对照观察?

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.