qa-observability

QA 可观测性

将遥测数据用作 QA 信号和调试基础。将日志、指标、链路追踪和性能剖析数据视为测试结果、发布就绪情况和生产环境回归的证据。

核心参考资料位于 data/sources.json；请从 Navigation 加载特定任务指南。

快速入门（默认）

如果缺少关键信息，请询问：关键用户旅程、服务／依赖清单、环境（本地／预发布／生产）、当前遥测技术栈，以及当前的 SLO／SLA 承诺。

1. 建立最低标准：关联 ID、结构化日志、链路追踪，以及黄金指标（延迟、流量、错误、饱和度）。
2. 使用一个已知请求或故障验证遥测传输：应用程序发出数据、上下文传播、收集器接收，以及后端查询。结论仅限于最后一个已观察到的阶段；静态 SDK 或收集器配置只能证明配置已完成。
3. 确保故障可诊断：每次集成或 E2E 失败都应捕获链路追踪链接或链路追踪 ID，以及相关联的日志；关键降级路径应公开结构化错误元数据，例如限流代码、重试提示和状态转换标记。
4. 当仪表板、SLO 或告警在任务范围内时，定义相关的 SLI／SLO 和错误预算策略，验证仪表板是否选中了已知遥测数据，并使用合成条件和受控的非生产接收器测试告警评估与路由。未经明确授权，不要通知真实的响应人员。分别记录后端查询、仪表板选取、规则评估、路由和送达结果；基本插桩在证明后端查询后即可停止。
5. 根据任务生成相应产物：使用 assets/checklists/template-observability-readiness-checklist.md、assets/monitoring/slo/slo-definition.yaml 和 assets/monitoring/slo/prometheus-alert-rules.yaml 编写就绪检查清单、SLO 定义或告警规则。保留环境、服务修订版本、链路追踪／请求 ID、查询时间窗口、采样决策，以及各个已执行阶段的结果。

默认 QA 原则

• 将遥测数据视为验收标准，尤其是集成和 E2E 流程。
• 要求实现关联：请求 ID 和链路追踪 ID 必须跨服务边界传递。
• 对于关键用户旅程，应通过结构化代码或属性，而非不透明的纯文本错误，使身份验证重定向、限流和状态同步延迟可诊断。
• 优先采用基于 SLO 的发布门禁和消耗速率告警，而不是原始基础设施阈值。
• 将采样、基数、保留期限和成本视为质量约束。
• 默认在日志、跨度和属性中屏蔽 PII 和机密信息。
• 使用 OpenTelemetry 语义约定，而非自定义属性名称；在业务工作流边界添加手动跨度：仅靠自动插桩无法展示这些边界。
• 在 OpenTelemetry 中，日志和性能剖析数据的支持情况取决于生态系统：在承诺提供厂商中立的实现前，先确认语言和后端支持情况。
• OTel Span Events API（Span.AddEvent、Span.RecordException）即将弃用，改用基于日志的事件（OTel 博客）。新的事件插桩应通过 Logs API 编写；在逐步迁移期间，现有跨度事件数据仍可正常使用。

专业判断（清单容易遗漏的内容）

• 遥测缺失： 从一条关键旅程入手：记录结构化请求日志，在入口处采集黄金指标，并传递追踪上下文。先查询一条已知请求，再将仪表板或告警作为证据。
• 日志还是追踪： 使用追踪分析请求因果关系和延迟，使用日志记录业务状态转换，使用指标衡量速率和百分位数。将日志或追踪视为持久记录之前，请先核实保留期限、采样和审计要求。
• 采样： 尾部采样只能保留到达采样器的 Span。头部丢弃的追踪无法在下游恢复；应将同一条追踪的所有 Span 路由到同一个尾部采样采集器，并考虑缓冲。使用未采样的请求指标作为 SLI。有关配置限制，请参阅 OpenTelemetry 采样 和 references/sampling-strategies.md。
• 分页告警： 将重复症状合并为可操作的 SLO 告警。衡量告警加载和响应质量；依据服务的人员配置和错误预算策略，而非通用的告警数量上限。请参阅 references/alerting-strategies.md。
• 基数： 限制用户 ID 和原始路径等指标标签；后端成本取决于信号和存储设计。谨慎保留有用的日志和追踪维度，并明确保留期限和采集预算。在估算规模之前，查阅所选后端的计费维度和限制。
• 调试边界： 使用遥测定位受影响的组件和请求上下文；需要代码级执行证据时，再使用调试器。

工作流

1. 建立基线：日志、指标、追踪、关联信息，以及至少一条可诊断的关键旅程。
2. 使用 OpenTelemetry 埋点：先使用自动埋点，再为业务工作流边界添加手动 Span。
3. 验证 HTTP、队列和 RPC 边界之间的上下文传递。
4. 根据规范的燃烧率表定义 SLI、SLO、错误预算和燃烧率告警；该表也涵盖低流量服务。
5. 让故障可诊断：为失败的测试附上追踪链接、关键日志和相关指标。
6. 只有在遥测可信之后，才添加性能证据：性能分析、负载测试、示例和基线。

快速参考

任务	推荐默认方案	备注
链路追踪	OpenTelemetry + Collector + 兼容 OTLP 的后端	Jaeger 和 Tempo 都是不错的后端；默认使用 Collector 作为路由层
指标	Prometheus + Grafana	使用延迟直方图。请查看 原生直方图文档，了解已部署版本的抓取和存储设置；将推出视为基础设施变更，并先测试仪表板和告警
日志	将结构化 JSON 写入 stdout/stderr + Collector/filelog 流水线	切勿将密钥或高基数 ID 记录为标签；各语言的 OTel Logs SDK 成熟度不一，采用直接 SDK 路径前请先查看状态页面
可靠性门槛	SLI/SLO + 错误预算 + 消耗速率告警	持续消耗错误预算或出现重大回归时，应阻止发布
性能	持续性能剖析 + 负载测试 + 预算	如需稳定的生产环境性能剖析，请使用 Pyroscope 或 Parca；在关键生产环境中使用前，请查看 OTel Profiles 状态，并参阅 references/performance-profiling-guide.md
零代码可见性	在可行时使用基于 eBPF 的检测	选择 Beyla/OBI 前，请查看 Beyla 设置要求和所选版本，确认内核、权限、运行时及后端兼容性
LLM / AI Agent 可见性	OTel GenAI semconv + 成本指标 + 评估事件	GenAI 约定位于 github.com/open-telemetry/semantic-conventions-genai；发布前请查看仓库中的稳定性状态，固定 semconv 版本，并做好名称变更的准备。Agent 链路追踪和评估请参阅 references/tools-ebpf-apm.md 和 ai-coding-agents-observability-evals

导航

需要时可打开以下指南：

如果用户需要……	阅读	另请使用
最精简的生产环境基线	references/core-observability-patterns.md	assets/checklists/template-observability-readiness-checklist.md
当前的 Node 或 Python 插桩方案	references/opentelemetry-best-practices.md	assets/opentelemetry/nodejs/opentelemetry-nodejs-setup.md、assets/opentelemetry/python/opentelemetry-python-setup.md
在服务间正常传播追踪数据	references/distributed-tracing-patterns.md	assets/checklists/template-observability-readiness-checklist.md
SLO、消耗速率告警和发布门禁	references/slo-design-guide.md（权威消耗速率表）	assets/monitoring/slo/slo-definition.yaml、assets/monitoring/slo/prometheus-alert-rules.yaml、规则测试（promtool test rules）、assets/monitoring/grafana/grafana-dashboard-slo.json
将性能剖析作为遥测数据（持续性能剖析、示例、OTel Profiles）	references/performance-profiling-guide.md	诊断：software-performance；负载测试：qa-testing-performance；入门资源：assets/performance/backend/template-nodejs-profiling-config.js、assets/performance/frontend/template-lighthouse-ci.json、assets/load-testing/load-testing-k6.js、assets/load-testing/template-load-test-artillery.yaml
成熟度模型和路线图	references/observability-maturity-model.md	assets/checklists/template-observability-readiness-checklist.md
应避免的问题及修复方法	references/anti-patterns-best-practices.md	assets/checklists/template-observability-readiness-checklist.md
告警设计和减少告警疲劳	references/alerting-strategies.md	assets/monitoring/slo/prometheus-alert-rules.yaml
仪表板层级和布局	references/dashboard-design-patterns.md	assets/monitoring/grafana/template-grafana-dashboard-observability.json
结构化日志和成本控制	references/log-aggregation-patterns.md	assets/observability/template-logging-setup.md
RED、USE 与 Golden Signals——如何选择指标框架	references/methods-red-use-golden.md	references/slo-design-guide.md
采样策略、尾部采样、示例	references/sampling-strategies.md	references/opentelemetry-best-practices.md
eBPF 和 APM 工具占位文档（Beyla、Pixie、Honeycomb、SigNoz、Coroot），大模型/AI Agent 可观测性	references/tools-ebpf-apm.md	data/sources.json
在没有假设且无法复现的情况下调试生产环境异常	references/core-analysis-loop.md	../qa-debugging/references/production-debugging-patterns.md
将可靠性、排队、控制或信息论应用于遥测	references/reliability-theory-applied.md、references/queueing-theory-applied.md、references/control-theory-applied.md、references/information-theory-applied.md	对应的 foundations-* 技能
精选来源：data/sources.json。

避免

• 将机密信息或高基数 ID 记录为指标标签
• 在已有语义约定时自行发明属性名称
• 添加检测代码，却没有采样和基数策略
• 仅依赖自动检测来了解业务工作流；应在业务工作流边界添加手动 span，而不是重复添加路由 span
• 凭记忆选择供应商：从 data/sources.json 入手，并查阅最新文档或发行说明

脚本

仅使用 Python 标准库的 CLI 工具；需使用 Python 3.9 或更高版本运行。回归测试需要 pytest。

脚本	用途
scripts/observability_scorer.py	成熟度评分、SLO 错误预算分析和就绪情况报告生成

评分器仅接受完整时间窗口的 SLO 测量数据；其状态阈值是本地启发式规则，不是基于多时间窗口的分页决策。请提供严格介于 0 和 100 之间的 target_pct、正整数 window_days，以及以下二者之一：两个整数事件计数（total_events 为正数，且 0 <= good_events <= total_events），或 0..100 范围内明确且有限的 current_availability_pct。若同时提供计数和百分比，则以计数为准；事件数为零时无法确定健康状况。仅提供百分比的输入无法确定剩余事件预算。成熟度评分由自我评估提供，并非运行时证明；每个已提供的维度都必须是其文档规定范围内的整数评分。必需输入无效或缺失时会报错。

回归测试：scripts/test_observability_scorer.py。运行 python3 -m pytest scripts/test_observability_scorer.py；比较已保存的实现时，可将 OBSERVABILITY_SCORER_SCRIPT 设为其他脚本路径。

快速开始：

# Score observability maturity (0–100) across 6 signal dimensions
python scripts/observability_scorer.py maturity \
  --input data/sample-observability-profile.json

# Calculate SLO error budget burn rates and status flags
python scripts/observability_scorer.py slo \
  --input data/sample-slo-data.json

# Full readiness report (maturity + SLO) written to a Markdown file
python scripts/observability_scorer.py report \
  --input data/sample-observability-profile.json \
  --slos  data/sample-slo-data.json \
  --output report.md

完整的 CLI 参考和输入架构请参阅 scripts/README.md。

数据

供脚本使用的示例输入文件。

文件	描述
data/sample-observability-profile.json	真实的 B2B SaaS 服务可观测性评估（checkout-service，Node.js）
data/sample-slo-data.json	包含当前可用性和事件计数的五项 SLO 定义
data/sources.json	此技能的精选参考来源

相关技能

技能	用途
ops-devops-platform	基础设施监控、Kubernetes、CI/CD
data-sql-optimization	数据库查询优化和索引
qa-debugging	应用级调试和堆栈跟踪
qa-testing-strategy	测试策略设计和覆盖率
qa-resilience	弹性模式、重试和断路器
software-architecture-design	架构决策
software-performance	性能诊断和性能分析
qa-testing-performance	负载、压力和浸泡测试；性能 CI 门禁
ai-coding-agents-observability-evals	Agent 跟踪和评估流水线

经验回顾循环

如果以往的决策或问题与当前情况相关，且存在 learnings.consolidated.md，请查阅该文件；仅在需要查看历史记录或其为可用备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用相关经验后，如果遇到值得记住的模式、值得避免的错误或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。