observability-and-instrumentation · 让功能上线后能追到问题

作者提供的示例，实际效果取决于你的输入和使用工具。

输入

需要定位导出在哪个阶段失败；允许记录 request_id、匿名团队 ID、阶段、耗时、错误码；禁止报告正文。

输出

编辑示例 · 未运行

logger.info({
  event: "report_export_finished",
  request_id: requestId,
  team_id: pseudonymousTeamId,
  stage: "render",
  duration_ms: elapsedMs,
  outcome: "failed",
  error_code: "RENDER_TIMEOUT"
});

指标：按 outcome 统计成功率，按 stage 统计耗时；request_id 用于日志关联，不作为高基数指标标签。
复测：分别走成功和超时路径，确认可追到同一请求且无正文泄漏。

为代码补充日志、指标、追踪和告警，回答生产中发生了什么。

具体任务

为报告导出失败设计结构化日志：为代码补充日志、指标、追踪和告警，回答生产中发生了什么。

为关键故障建立告警：选择用户受影响的指标、持续窗口、负责人和关联排查手册，减少噪声。

必需材料

关键用户路径及服务边界

现有日志、指标、追踪设施

可选材料

采样与吞吐约束

敏感字段清单

使用门槛

先定义哪些可观察信号能说明功能成功或失败。

这个 Skill 额外提供的方法

为要回答的问题选择日志、指标和 trace，关联请求路径而不是随处添加无意义输出。

编辑示例（未运行）

为报告导出失败设计结构化日志

任务：请根据下面的示例材料完成为报告导出失败设计结构化日志，把判断依据和待确认事项写清楚。

输入：
需要定位导出在哪个阶段失败；允许记录 request_id、匿名团队 ID、阶段、耗时、错误码；禁止报告正文。

结果片段：
```javascript
logger.info({
  event: "report_export_finished",
  request_id: requestId,
  team_id: pseudonymousTeamId,
  stage: "render",
  duration_ms: elapsedMs,
  outcome: "failed",
  error_code: "RENDER_TIMEOUT"
});
```

指标：按 outcome 统计成功率，按 stage 统计耗时；request_id 用于日志关联，不作为高基数指标标签。
复测：分别走成功和超时路径，确认可追到同一请求且无正文泄漏。

为要回答的问题选择日志、指标和 trace，关联请求路径而不是随处添加无意义输出。 该片段是编辑示例，用于说明交付形态，未运行上游技能。

首次任务

请使用「让功能上线后能追到问题」完成「为报告导出失败设计结构化日志」。
任务要求：为要回答的问题选择日志、指标和 trace，关联请求路径而不是随处添加无意义输出。

我的必需材料：
- 关键用户路径及服务边界：[请填写或粘贴]
- 现有日志、指标、追踪设施：[请填写或粘贴]

请基于上述实际材料输出：预期交付是与问题对应的埋点、关联字段和查询或告警建议。验收时应走一次成功与失败路径，确认能从记录中还原行为；只有“增加了一条日志”不足以证明问题已经可定位。缺少依据的地方单列为待确认，不编造事实；未执行的操作或测试明确标为未执行。

验收要求：
1. 成功与失败都能关联完整路径。
2. 敏感字段被排除或脱敏。
3. 告警能够导向负责人与具体排查动作。

验收方法

成功与失败都能关联完整路径

敏感字段被排除或脱敏

告警能够导向负责人与具体排查动作

依赖与准备

需要项目已有日志库与监控栈；跨服务追踪可能需 OpenTelemetry，外部平台凭据与数据出站权限单独配置。

使用边界

不要把密码、令牌、完整请求正文或私人数据写入遥测。

遥测平台外传、采样与保留期必须符合项目的数据权限。

排错

日志很多却找不到同一请求：统一关联 ID 并跨服务传递，检查缺失的边界。

指标系统成本突然增加：检查高基数标签，避免用户 ID、URL 全参数进入时序维度。

固定来源

https://github.com/addyosmani/agent-skills/blob/bcab6a1b8503100e8618c3b4e32cc78de43de769/skills/observability-and-instrumentation/SKILL.md

先看看示例

输入

输出

方法说明