mcpField
S
software-instrumentation

software-instrumentation

github.com/axross开发138 次安装1 天前更新
代码仓库

关于 software-instrumentation

这是一套与工具无关的软件观测指导，涵盖日志、指标、追踪、错误报告和产品事件追踪。它帮助团队规范埋点决策，具体厂商配置则交由相应工具处理。

主要功能

  1. 01按生产问题选择信号
  2. 02错误处理与报告指导
  3. 03结构化日志规范
  4. 04指标类型、标签与封装
  5. 05产品事件命名、身份与同意机制

适用场景

  1. 01规划新操作的遥测
  2. 02审查错误捕获和日志实践
  3. 03添加服务健康指标
  4. 04追踪功能使用与转化事件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/axross/skills --skill software-instrumentation

安装后在 Claude Code 中输入/software-instrumentation确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
error-handling.md
error-tracking.md
logging.md
metrics.md
product-event-tracking.md

详细介绍

软件埋点

在为软件添加埋点以便观察其行为时，使用此能力——添加或审查用于发出遥测信号（日志、错误、跟踪或产品事件）的代码，或配置这些信号所流向的工具。良好的埋点能让生产事故从猜测变成查证。

本指南刻意不依赖具体工具。它提到的是角色——你的结构化日志记录器、你的错误跟踪工具（错误报告服务）、你的分析工具——而不是特定 SDK；代码片段使用 logger.info(...)、reportError(...) 和 trackEvent(...) 等占位函数名，可映射到项目采用的任何实现。应用规则时，请替换成具体名称；保留其结构。

这类替换正是特定供应商的能力发挥作用之处。依赖哪个软件包、哪个选项控制收集哪些数据、如何将源映射上传到服务，以及其构建时令牌可能出现在哪里，这些都是供应商相关的问题，本技能不会解答；这些问题由已安装的跟踪工具自身的埋点能力负责。请结合使用：本技能决定埋点什么，供应商的能力则决定如何实现。

可观测性建立在三种信号类型之上——日志、指标和跟踪——并通过规范的错误处理和专用的错误跟踪工具让这些信号发挥作用。产品事件与它们并列：同样是测量，但关注的是用户行为而非系统健康，并有各自的命名、身份和同意规则。以下每个参考文档各自负责其中一项；请加载与本次更改相关的文档。

本文中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”，应按 RFC 2119 中的说明进行解释。

选择信号

选择能够回答你预期在生产环境中提出的问题的信号，而不是最容易添加的信号。以下流程会将需求引导至相应信号及其负责的参考文档；跟踪通过错误跟踪工具的跟踪集成进行埋点，因此归入错误跟踪范畴。

flowchart TD
  Q{What do you need to answer?} --> R1[Record that a specific operation happened, and how far it got]
  Q --> R2[Count or aggregate a rate over time - request rate, latency, error rate]
  Q --> R3[Follow one request across service or module boundaries]
  Q --> R4[Measure user behavior - a feature used, a funnel step, a conversion]
  R1 --> S1[Log line - see Logging]
  R2 --> S2[Metric - see Metrics]
  R3 --> S3[Trace - see Error Tracking, trace/replay sampling]
  R4 --> S4[Product event - see Product Event Tracking]

意外故障不在此流程中，因为它不属于这些选项之一：将其报告给错误跟踪工具（参见“错误处理”和“错误跟踪”），并通过规范的日志记录提供故障发生前的线索。

错误处理

请参阅 error-handling.md，了解：

  • try-catch 块应放置在哪里，以及错误如何传播到根调用点
  • 捕获错误后的决策流程——重新抛出控制流信号、报告意外故障，然后恢复或重新抛出
  • 在提前返回、重定向或进入回退路径之前报告捕获的错误
  • 顶层错误边界，以及如何编写可采取行动的错误消息

错误跟踪

请参阅 error-tracking.md，了解：

  • 如何通过一个项目封装层或初始化/配置文件集成错误报告服务
  • 如何添加捕获调用，以及哪些故障值得捕获，哪些属于普通控制流
  • 面包屑、跟踪/回放采样和埋点边界
  • 如何避免将机密和个人身份信息 (PII) 放入遥测事件上下文

日志记录

请参阅 logging.md，了解：

  • 何时值得记录某项操作，以及何时日志只会造成噪声
  • 日志级别的决策流程，以及如何选择级别（info / warn / debug；对于没有错误跟踪工具的项目，error 为保留级别）
  • 如何配置一个共享的根日志记录器，并从中派生模块级子日志记录器
  • 结构化上下文对象以及“Started / Completed”消息约定

指标

请参阅 metrics.md，了解：

  • 判断健康信号何时应成为指标，而不是日志行
  • 选择计数器、仪表盘或分布，并声明单位
  • 限制标签的基数，以及绝不能用作标签的标识符
  • 通过一个受控、非阻塞且不会抛出异常的封装器发送数据

产品事件跟踪

请参阅 product-event-tracking.md，了解：

  • 由哪个模块统一管理分析 SDK，以及前置的类型化事件架构
  • 如何命名、添加或重命名事件，使其经得起重新设计，并在同一个边界处规范化名称和键
  • 事件属性与用户属性、基数，以及绝不能放入负载的内容
  • 仅在成功时记录的事实和意图事件、必要的结果诊断，以及服务端场景
  • 身份调用、注销时重置、会话定义，以及经用户同意后再初始化
  • 如何在测试中断言事件，以及如何迁移或弃用事件而不清空图表

评论

支持 Markdown