monitoring-observability

Monitoring & Observability

概述

该技能覆盖可观测性的三大支柱——追踪（traces）、指标（metrics）和日志（logs），以及告警、仪表盘和健康检查模式。它聚焦于 OpenTelemetry 作为厂商中立的可观测性标准、面向可查询性的结构化日志、用于微服务调试的分布式追踪，以及基于 SLO 的告警以减少噪音。

适用场景：为生产环境可见性对应用进行埋点、搭建监控基础设施、调试分布式系统、配置真正有用的告警，或为运维和产品团队构建仪表盘。

核心原则

在边界处埋点——追踪每一次外部调用（HTTP、数据库、队列、缓存）。内部函数追踪会增加噪音；边界追踪才能揭示系统行为。
结构化优于非结构化——每条日志必须是带关联 ID、服务名和上下文的 JSON。非结构化日志在规模下不可搜索。
对症状而非原因告警——当用户受影响时（错误率、延迟 SLO 突破）才告警，而不是某个特定服务器指标飙升时。基于症状的告警可减少 80% 噪音。
跨信号关联——一个 trace ID 应串联单个请求的日志、追踪和指标。没有关联，调试分布式问题只能靠猜测。
为错误率做预算——定义 SLO（99.9% 可用性 = 每月 43 分钟停机预算）。当错误预算消耗过快时告警，而不是对单个错误告警。

关键模式

模式 1：OpenTelemetry 埋点（Node.js）

适用时机： 任何需要追踪、指标和日志关联的生产 Node.js 服务。

实现要点（代码见原文）：初始化 NodeSDK，配置 resource（服务名、版本、环境）、OTLPTraceExporter 与 PeriodicExportingMetricReader（导出间隔 30 秒），启用 getNodeAutoInstrumentations 并关闭噪音较大的 fs 埋点、为 HTTP 配置 requestHook 捕获请求头。使用 @opentelemetry/api 的 trace 创建自定义 span，为业务逻辑（如订单处理、取单、扣款）添加属性并在错误时设置状态与记录异常。OpenTelemetry 提供厂商中立的埋点，自动埋点捕获 HTTP、数据库和 gRPC 调用，自定义 span 添加业务上下文（订单 ID、支付金额）使追踪可操作。

模式 2：带关联的结构化日志

适用时机： 每个产生日志的应用。

实现要点（代码见原文）：使用 Pino 创建 logger，通过 mixin 自动从当前活动 span 注入 traceId、spanId、traceFlags；配置 redact 脱敏敏感字段（authorization、password、token、apiKey）；始终记录结构化数据而非字符串插值；错误日志附带 err、orderId、operation 等上下文；使用 child logger 为请求级上下文（requestId、path、method、userAgent）创建子日志器。结构化日志可查询，可按 orderId 过滤、通过 traceId 与追踪关联、按 operation 聚合错误率；字符串插值日志需正则提取字段，在规模下会失效。

模式 3：基于 SLO 的告警

适用时机： 建立减少噪音、聚焦用户影响的生产告警。

实现要点（代码与 YAML 见原文）：Prometheus 告警规则示例包括可用性 SLO（99.9% 成功率）错误预算燃烧过快告警、延迟 SLO（99% 请求低于 500ms）告警，以及 Google SRE 书中的多窗口多燃烧率告警模式；应用层使用 @opentelemetry/api 的 metrics 创建请求计数器和请求时长直方图，并通过中间件在响应 finish 时记录方法、路由、状态码、成功与否等属性。传统阈值告警（CPU > 80%、错误 > 10）会产生噪音；基于 SLO 的告警询问“用户是否受影响”和“错误预算消耗多快”，只在需要行动时才触发。

模式 4：健康检查与就绪探针

适用时机： 任何部署到 Kubernetes 或位于负载均衡器后的服务。

实现要点（代码见原文）：提供 /healthz 存活探针（仅检查进程能否响应，绝不检查依赖）和 /readyz 就绪探针（检查数据库、Redis 等关键依赖，返回 pass/fail/warn、延迟、消息、uptime 和版本，失败时返回 503）。Kubernetes 用存活探针重启卡住的进程、用就绪探针停止向未就绪实例发送流量；若存活探针检查数据库，会在数据库故障时重启健康 Pod，导致级联故障。

Grafana 仪表盘速查

提供仪表盘 JSON 面板示例：请求速率（按状态分组的 rate 时间序列）、错误率百分比（stat 面板，含绿/黄/红阈值）、P99 延迟（histogram_quantile 时间序列）。

反模式

表格列出常见反模式与更好做法：生产环境用 console.log（应使用 pino/winston 输出 JSON）；对每个 5xx 告警（应按 SLO 突破/错误预算燃烧率告警）；存活探针检查数据库（存活只检查进程，就绪才检查依赖）；无 trace 上下文传播（使用 W3C traceparent 头并在所有客户端注入）；100% 追踪采样（头部采样 10-20% 或对错误使用尾部采样）；记录 PII（在 logger 配置中脱敏）；50 个面板的仪表盘（遵循四大黄金信号：速率、错误、时长、饱和度）。

检查清单

OpenTelemetry SDK 在所有其他导入之前初始化
为 HTTP、数据库和队列客户端启用自动埋点
在业务逻辑边界添加带相关属性的自定义 span
结构化 JSON 日志并带 trace ID 关联
在 logger 配置中脱敏敏感字段
存活探针仅检查进程（不检查依赖）
就绪探针检查所有关键依赖
为可用性和延迟定义 SLO
告警基于错误预算燃烧率而非原始阈值
每个服务有含四大黄金信号的仪表盘
为生产规模配置追踪采样策略
日志聚合管道发送到集中式存储

技能介绍