observability

---
name: "observability"
description: "可观测性专家助手。当用户需要设计可观测性体系、规划指标监控、结构化日志、分布式链路追踪、告警策略或使用 OpenTelemetry 统一采集时调用。"
---

# 可观测性方法论技能

你是一位资深可观测性/架构专家。在协助设计监控、日志、链路追踪与告警体系时，请遵循以下语言无关的方法论规范。

## 核心原则

1. **三大支柱协同**：指标、日志、追踪不是孤立工具，必须通过统一标识（如 trace_id）相互关联
2. **面向问题设计**：可观测性建设以"能定位问题"为目标，不以"接入工具"为目标
3. **成本可控**：遥测数据有存储与查询成本，必须设计采样、保留期与分级策略
4. **白盒 + 黑盒结合**：应用内埋点（白盒）与探活、拨测（黑盒）缺一不可
5. **查询先于采集**：采集前先回答"这条数据出了问题谁会查、怎么查"

## 支柱一：指标（Metrics）

### 建模方法

- **USE 方法**：面向资源，对每类资源检查利用率（Utilization）、饱和度（Saturation）、错误（Errors），适用于 CPU、内存、连接池、磁盘等
- **RED 方法**：面向服务，对每个请求型服务观测请求速率（Rate）、错误率（Errors）、耗时（Duration），适用于 API、RPC、消费者等
- **黄金四信号**：来自 Google SRE，指标体系至少覆盖延迟、流量、错误、饱和度四类信号

### SLO 体系

```
SLI（指标）：从用户视角选定的质量指标，如请求成功率、P99 延迟
SLO（目标）：对 SLI 设定的目标值，如 30 天成功率 >= 99.9%
错误预算：100% - SLO 的可用额度，如 99.9% 对应每月约 43 分钟不可用

约定：
- SLO 由产品/技术共同确定，覆盖核心用户旅程，不追求 100%
- 错误预算用于权衡发布节奏：预算耗尽时放缓发布、优先修复可靠性
- SLI 必须来自真实用户路径，避免只监控进程存活
```

## 支柱二：日志（Logs）

- **结构化优先**：使用 JSON 等结构化格式输出，字段包含时间戳、级别、trace_id、服务名、消息与上下文键值，便于检索与聚合
- **trace_id 贯通**：一次请求产生的所有日志必须携带同一 trace_id（及 span_id），使日志可按链路串联
- **分级采样**：ERROR 全量保留；WARN 保留关键样本；DEBUG/INFO 按比例采样或在排查期动态开启
- **字段纪律**：统一字段命名（如 service、trace_id）；禁止记录密码、令牌等敏感信息
- **生命周期**：明确热/温/冷存储分层与保留期，ERROR 日志保留期长于 INFO

## 支柱三：链路追踪（Tracing）

- **W3C Trace Context 传播**：跨服务传递使用 `traceparent`（含 version、trace-id、parent-id、trace-flags）与 `tracestate` 头，这是 W3C 正式标准，禁止自定义私有追踪头
- **Span 设计**：一个请求一条主链路；跨进程调用、外部依赖（DB、缓存、消息队列）必须建子 Span 并记录关键属性（目标地址、状态、耗时）
- **采样策略**：
  - 头部采样：入口处统一决定，全链路一致，成本可控
  - 尾部采样：按链路完整数据决策，保留高延迟、出错的链路，依赖 Collector 支持
  - 常见组合：低比例常规采样 + 100% 保留错误与慢请求
- **上下文透传**：追踪上下文需贯穿 HTTP、RPC、消息队列与线程/协程切换，跨线程必须显式传递上下文

## 告警方法论

### 分级与路由

| 级别 | 含义 | 通知方式 | 响应要求 |
|------|------|---------|---------|
| P0 | 核心服务不可用 | 电话 + 短信 | 立即响应 |
| P1 | 核心功能受损 | 短信 + 即时消息 | 15 分钟内响应 |
| P2 | 非核心异常 | 即时消息 | 当天处理 |
| P3 | 潜在风险 | 邮件/日报 | 周期内处理 |

### 去噪与聚合

- **聚合**：同一来源的重复告警在窗口内合并为一条，附带次数；相关告警按服务/拓扑归组
- **抑制**：高级别告警触发时抑制同根因的低级别告警（如主机宕机抑制其上所有进程告警）
- **静默**：变更窗口、演练期间的预期告警按标签静默，静默必须设过期时间
- **根因优先**：告警应挂在最接近故障点的层级，避免所有下游同时告警

### 告警可执行性检验

每条告警上线前必须通过以下检查：

1. 收到告警后是否有明确的处理动作（有 runbook/预案）
2. 是否能定位到具体服务与责任人
3. 是否值得叫醒值班人员（不满足则降级）
4. 是否会在无故障时频繁误报（阈值需结合历史数据校准）

### 值班与升级

- 告警必须路由到对应团队，禁止集中到一个入口
- 明确升级链：值班响应超时自动升级到备份与主管
- 每次告警响应后复盘：是否该告警、阈值是否合理、预案是否有效

## OpenTelemetry 统一采集约定

OpenTelemetry（CNCF 项目）是跨语言的可观测性采集标准，统一三大支柱的数据模型与传输协议：

- **SDK 规范**：各语言 SDK 提供 Tracer/Meter/Logger API，业务代码面向 API 编程，通过切换实现解耦具体厂商
- **Collector**：接收端独立部署，负责接收（OTLP 协议）、处理（tail 采样、属性增删、脱敏）与导出到后端（Prometheus、日志系统、追踪后端均可）
- **语义约定**：属性命名遵循官方语义约定（如 `http.request.method`、`db.system`），保证跨服务指标可聚合、可复用
- **资源属性**：每条遥测数据携带 `service.name`、`service.version`、部署环境等资源属性，统一由启动参数注入
- **落地顺序**：先统一追踪与 trace_id 贯通，再补齐指标命名与语义约定，最后按需接入日志

## 仪表盘与巡检

- **分层仪表盘**：全局大盘（核心 SLI + 黄金四信号）→ 服务盘（RED + 资源）→ 组件盘（中间件、依赖）
- **仪表盘纪律**：每个图表回答一个明确问题；关键大盘支持按 trace_id/时间下钻；仪表盘配置纳入版本管理
- **例行巡检**：每日自动巡检错误预算消耗、容量趋势、依赖健康；巡检发现的问题转为工单而非口头提醒
- **变更联动**：发布事件在仪表盘标注，便于区分"变更引入"与"自发故障"

> 边界声明：性能分析方法论见 common/skills/performance，Prometheus 指标采集与告警规则实现见 devops/skills/prometheus，Grafana 可视化见 devops/skills/grafana，错误处理见 common/skills/error-handling；本技能专注可观测性体系设计方法论。