monitoring-observability

监控与可观测性

当核心问题是**“我们有什么资料包、系统应注意什么，以及什么情况应该通知人工介入？”**时，使用此技能。

这项工作的目的不是提供一份 Prometheus / Grafana / Datadog 教程。 而是规范资料包，选定一种主要的可观测性模式，定义最小且实用的信号方案，并在这项技能演变为调试、性能调优、发布执行或分析报告前，将相邻工作转交出去。

处理不熟悉的资料包前，请阅读 references/intake-packets-and-route-outs.md。 处理混合了遥测设置、事件诊断或产品分析的请求前，请阅读 references/modes-and-boundaries.md。 审核仪表板、告警和责任归属缺口时，请阅读 references/alert-dashboard-checklist.md。 选择最小发布范围时，请阅读 references/telemetry-rollout-matrix.md。

何时使用此技能

• 新服务、工作进程、API 或多服务系统在上线前需要健康信号、告警、仪表板或类似 SLO 的覆盖
• 现有技术栈已有仪表板 / 告警 / 遥测，但可信度较低，需要进行保留 / 修复 / 删除 / 添加审查
• 团队需要在选择供应商或后端细节之前，确定要检测、关联、保留或采样的内容
• 数据、营销、分析或管道工作需要监控新鲜度 / 架构 / 体量 / 血缘，而不是再做一次人工信任检查
• 游戏或 live-ops 工作需要了解崩溃、会话、构建或启动事件，但不涉及解读引擎性能分析器
• 跨职能可靠性需求涉及后端、产品 / 运营、营销管道和游戏 live-ops，但尚不清楚下一步由谁负责

何时不使用此技能

• 资料包主要是日志，工作是找出第一个可采取行动的故障 → log-analysis
• 工作是针对代码 Bug 或回归进行复现 → 隔离 → 验证 → debugging
• 已有测量结果，主要工作是找出瓶颈或进行调优 → performance-optimization
• 主要工作是执行发布、推广、回滚或部署后流程安排 → deployment-automation
• 工作涉及 LLM 专属追踪、评估或提示词可观测性 → langsmith
• 工作是解读 Unity/Unreal/Godot 帧时间采集结果 → game-performance-profiler
• 任务只是使用经过整理的 BigQuery 数据制作仪表板 / 报告 → looker-studio-bigquery

指令

第 1 步：梳理资料包

给出工具建议前，先记录最简实用的接收信息。

记录：

• 范围：服务/API | 工作进程/队列 | 数据/管道 | 仪表板/审查 | 游戏/live-ops | 混合 | 未知
• 请求类型：新建设置 | 审查/审计 | 事件跟进 | 迁移 | 上线准备 | 未知
• 当前资料包：架构说明 | 告警规则 | 仪表板清单 | 事件摘要 | 遥测配置 | 过时报告问题 | 崩溃/会话简报 | 无
• 用户/业务影响：延迟 | 错误 | 数据过时 | 缺少可见性 | 崩溃/会话风险 | 告警噪声 | 未知
• 责任归属：应用团队 | 平台/SRE | 数据/运营 | live-ops | 共同负责 | 未知

快速梳理：

Surface: data/pipeline
Request type: review/audit
Current packet: stale dashboard complaint + job ownership notes
Impact: stale data and trust erosion
Ownership: data/ops + dashboard consumer owner

第 2 步：从接收资料包入手

使用 references/intake-packets-and-route-outs.md。

选择用户当前实际拥有的资料包：

• 服务 / 可靠性资料包
• 遥测基础资料包
• 数据 / 管道资料包
• 审查 / 审计资料包
• 游戏 / live-ops 资料包
• 暂无可用资料包

此步骤的输出：

## Intake Packet
- Current packet:
- Why it is enough (or not enough):
- Missing context to collect next:

规则：如果当前资料包已能缩小下一步决策范围，就不要强行进行供应商比较或重写遥测技术栈。

步骤 3：选择一个主要可观测性模式

从 references/modes-and-boundaries.md 中选择一个主要模式。

主要模式：

• service-reliability
• telemetry-foundation
• data-pipeline-observability
• game-liveops-visibility
• review-gap-audit
• unknown-needs-better-packet

规则：选择一个主要模式，可选一个次要模式。 不要把发布遥测、过时仪表板审计、崩溃可见性和通用埋点混在同一个回答中。

步骤 4：明确核心监控问题

在列出工具或指标之前，先说明系统必须回答什么问题。

良好示例：

• “用户可感知的 API 故障会在客户报告之前触发我们的告警吗？”
• “我们是否知道周一的增长仪表板何时过时、过时原因，以及谁负责修复？”
• “能否按构建版本／平台对发布活动中的崩溃进行归类，并在社交媒体报告激增前升级处理？”
• “当前告警能否将响应人员引导至一个有用的仪表板／运行手册，而不是三个嘈杂的症状？”

避免使用“改进监控”这类含糊表述。

步骤 5：制定一个最小信号计划

使用 references/telemetry-rollout-matrix.md。

针对所选模式，定义：

• 仪表板／告警路径必须回答的核心问题
• 证据来源：指标、日志、追踪、黑盒检查、崩溃工具、新鲜度检查、血缘视图
• 立即告警与稍后创建工单、仅在仪表板中展示的阈值
• 每类告警或仪表板的负责人
• 仅包含最先实施的 1–3 个阶段

规则：

• 优先针对症状告警，而不是内部原因。
• 对同一事件，优先发送一个明确的告警，而不是多个分层告警。
• 限制标签数量；将高基数细节放入日志／追踪。
• 需要人工操作的告警必须包含运行手册／仪表板链接。
• 如果告警投递可能静默失败，必须将元监控视为一等事项。

步骤 6：明确转交路径

当任务性质发生变化时，移交工作。

常见转交路径：

• 根因日志取证 → log-analysis
• 以正确性为先的回归问题排查 → debugging
• 瓶颈诊断或调优 → performance-optimization
• 发布执行／部署后回滚路径 → deployment-automation
• LLM 追踪／评估／提示词可观测性 → langsmith
• KPI 解读／利益相关方证据摘要 → data-analysis
• 基于 BigQuery 的仪表板展示层 → looker-studio-bigquery
• 引擎分析器解读 → game-performance-profiler

步骤 7：返回可观测性简报

# Observability Brief

## Scope
- Surface:
- Request type:
- Intake packet:
- Primary mode:
- Confidence:

## Core Monitoring Question
- ...

## Signal Plan
- Metrics / checks:
- Logs / traces / crash context:
- Dashboards / views:
- Alert policy:

## Ownership
- Primary owner:
- Secondary owner(s):

## First Implementation Slice
1. ...
2. ...
3. ...

## Route-outs
- ...

示例

示例 1：发布前的新 API

输入：“我们下周要发布一个新 API。请告诉我应该埋点什么，以及哪些情况应该触发告警。”

**预期形式：**归类为 service-reliability，使用当前的发布／就绪情况资料包，定义 RED／黄金信号相关问题以及黑盒覆盖范围、告警阈值，并给出一个最小实施阶段。

示例 2：增长仪表板总是过时

输入：“我们的周一早间增长仪表板有一半时间都是过时的。我们需要的是可观测性，而不是再加一次电子表格检查。”

**预期形式：**归类为 data-pipeline-observability，涵盖新鲜度／架构／数据量／血缘／所有权，并区分仪表板可信度检查与 KPI 解读工作。

示例 3：审查／差距审计

输入：“我们有大量告警和仪表板，但没人相信它们。哪些应该保留，哪些应该删除？”

**预期形式：**归类为 review-gap-audit，使用告警／仪表板检查清单，给出保留／修复／删除／新增的决策，并指出嘈杂的告警、无负责人的面板以及缺失的元监控。

示例 4：转交至发布执行

输入：“我们刚刚完成部署，需要一份包含健康检查的逐步回滚／升级清单。”

**预期形式：**将执行工作流转交给 deployment-automation，同时可酌情说明少数重要的部署后可观测性问题。

示例 5：转交日志取证

输入：“这是故障日志。请找出根本原因。”

**预期方式：**不要将此用作主要工作流；转交给 log-analysis，并且仅在确定首个可操作故障后，才提出可观测性后续工作。

最佳实践

1. 从数据包和核心监控问题入手，而不是从供应商入手。
2. 保持一种主要模式，并选取最小的实现切片。
3. 对症状发出告警，而不是对所有可能的原因发出告警。
4. 明确责任归属、运行手册和仪表板链接。
5. 将过时数据／管道可信度视为可观测性工作的重中之重。
6. 将游戏实时运营可见性与引擎分析器解读分开。
7. 诚实地开展审查／审计工作：应删除失效的仪表板和嘈杂的告警，而不只是记录下来。
8. 每当前端入口边界发生变化时，同步精简的发现入口。

参考资料

• Google SRE — 分布式系统监控
• OpenTelemetry — 可观测性入门
• Prometheus — 告警
• Grafana — 仪表板最佳实践