SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场backend-observability

backend-observability

部署与运维

查看项目

更新于 10-16 09:16

技能介绍

用途

本技能用于在编写后端代码时正确地进行观测性插桩（instrumentation），使后续的监控与追踪工具有可用的信号。它定位为「监控栈的构建期对应物」：Sentry 插件负责安装 SDK，debug-sentry-monitor 负责事后分诊，audit-langfuse-llm 负责审计 LLM 追踪，而本技能关注的是在构建期就正确埋点，从而让上述工具获得有效信号，并让凌晨三点的故障可被排查。

适用触发场景：为新代码添加日志 / 追踪 / 指标；审查已有插桩；修复「无法判断生产环境发生了什么」的问题。

不适用：安装 SDK（应使用 Sentry / Langfuse 插件）；事后分诊（应使用 monitor / audit 类技能）。

主要能力

关联（correlation）— 低自由度，需严格照做

一次生产事故可被排查的前提，是能够从错误、链路、日志、用户中任意一项跳转到其余各项。因此要求让每一层共享同一个 id：

  • 在入口点（HTTP 中间件、边缘函数、任务启动处）生成或传播 request id（或 OTel trace_id），并将其放入异步上下文（AsyncLocalStorage / context var），而不是作为参数层层传递。
  • 将其标记到所有地方：每一行日志、Sentry 的 setTag("request_id", id) / setContext，以及 Langfuse trace（trace.id 或 metadata）。在 LLM 出错时，把 Langfuse trace URL 附加到 Sentry 事件上，从而直接从错误跳转到 prompt/response。
  • 设置已脱敏的用户 / 会话 / 租户作用域（Sentry.setUser，Langfuse userId/sessionId）。

结构化日志纪律 — 高自由度

  • 结构化而非字符串堆砌：输出带稳定字段（level、msg、request_id、event、domain ids）的 JSON，每行一个事件，使用平台日志器（pino / structlog / slog），而非裸 console.log。
  • 日志级别要有含义：error = 需要人工介入；warn = 降级但已处理；info = 状态转换 / 业务事件；debug = 仅开发用，生产关闭。已处理的流程不要记为 error。
  • 生产环境不得遗留 console.log——它不可搜索、无级别，且存在 PII 泄露风险。应移除或转换为带级别的结构化日志。
  • 记录决策而非噪音：在边界处记录所走分支及关键输入/输出，而非每一行。

PII / 密钥脱敏（不可协商）— 低自由度，需严格照做

  • 绝不记录 token、密码、API key、完整 PAN、认证头或原始请求体。在日志器 / 传输层进行脱敏（deny-list keys + 模式清洗），避免被逐调用绕过。
  • 配置 Sentry 的 beforeSend / 数据清洗，以及 Langfuse 的掩码，从事件 / 追踪中剥离 PII。假定放入 span / breadcrumb 的任何内容都可能被保留。
  • 对 LLM 追踪：需明确决定 prompt / completion 是否可能包含 PII；若司法辖区要求，发送前应掩码或哈希。

追踪 / span（包裹什么）— 高自由度

  • 包裹边界与缓慢 / 易失败的工作：入站请求、出站 HTTP/DB/队列调用、LLM 调用、后台任务。不要包裹每一个函数。
  • 按操作命名 span（http.server、db.query、llm.generate），添加属性（route、status、行数、model），遵循 OTel 语义约定，包括 LLM span 的 GenAI 约定（model、输入/输出 token、cost、latency、temperature）。
  • 采样：无需 100%。对正常流量做头部采样（例如 10–20%），但始终保留错误与慢速离群值。记录采样率，它是成本 / 可见性的调节旋钮。

LLM 专项（Langfuse）— 高自由度

  • 每次生成捕获：prompt、response、model、输入/输出 token、cost、latency，以及所运行的 eval / score。将多步 agent 归入同一 trace，使用嵌套 span。
  • 将 Langfuse trace_id 链接进外层 request id，并在失败时链接进 Sentry，使 Sentry 中的 LLM 错误一键直达完整追踪。
  • 为 trace 打上 userId / sessionId / release 标签，以便 audit-langfuse-llm 按群组切片质量。

告警与 SLO（信号而非噪音）— 高自由度

  • 对用户能感知的症状告警（错误率飙升、p95 延迟、checkout/login 失败、LLM eval 评分下降），而非每一个错误。
  • 定义少量 SLO（可用性、延迟、关键流程成功率），按燃烧率告警，而非原始计数。
  • 每条告警都要指明负责人与第一步动作，通过 sentry-create-alert 或对应渠道路由。

使用方式

技能以「仅规划（plan-only）」方式运作，推理流程如下：

  1. Observe：观察已存在哪些 id、日志、span 和 PII。
  2. Interpret：能否从错误 ↔ 链路 ↔ 日志 ↔ 用户中任意一项互相跳转？
  3. Classify：归类为 add-correlation / convert-console / redact / wrap-span / alert。
  4. Severity：未关联的生产 500 比缺失的 debug 字段优先级更高。

技能的自由度标注为 MIXED：包裹什么、对什么告警为高自由度；关联 id、PII 脱敏与完成标准（DoD）为低自由度，须严格照做。

报告前需自检：是否已关联（同一 request/trace id 出现在日志、Sentry、Langfuse）、是否已脱敏（日志器 + beforeSend 的 deny-list，而非逐调用指望）、是否已分级（生产无 console.log，已处理路径不记为 error）、负责人是否正确（仅规划审计 → plan-error-handling；调查 Sentry 问题 → debug-sentry-monitor）。

文中给出的示例：Observe 阶段发现 Sentry 中的 checkout 500 没有 request_id、pino 记录了 cart id、未使用 Langfuse；Interpret 阶段发现无法从错误跳转到日志、webhook 仍在用 console.log；Classify 阶段处置为在日志上加 ALS request_id 并 Sentry.setTag、把 console 转为 pino、脱敏 Authorization；Verify 阶段确认 Sentry 事件与日志行共用一个 id、beforeSend 剥离了该头部。

完成标准（DoD）— 低自由度，不可跳过

  • 共享的 request/trace id 出现在每一行日志、Sentry 作用域和 Langfuse trace 上。
  • 从一次生产错误可 ≤2 次点击到达追踪、日志和用户。
  • 日志结构化 + 级别正确；生产无 console.log 遗留。
  • PII / 密钥脱敏在日志器 + Sentry beforeSend + Langfuse masking 处强制执行。
  • Span 覆盖边界并使用 OTel 规范命名 / 属性；错误绝不被采样丢弃。
  • LLM 生成记录 model/tokens/cost/latency 并回链到 request id。
  • 告警针对用户感知症状触发并指定负责人，而非对每一个错误告警。

适用场景与限制

适用于构建期正确埋点、审查插桩、修复生产环境可观测性缺失。不适用于 SDK 安装或事后分诊。技能与其他技能组合使用：Sentry 插件（sentry-sdk-setup、sentry-setup-ai-monitoring、sentry-create-alert、sentry-otel-exporter-setup）、Langfuse 插件（langfuse）与 audit-langfuse-llm、debug-sentry-monitor / debug-error、data-pipeline、workflow-spec-tdd。资料中未提供具体的收费、价格、平台支持范围等细节。