日志与可观测性

适用于日志、指标和追踪三大支柱的系统可观测性设计模式。

三大支柱

每个支柱在相互关联时效果最佳。在每条日志中嵌入 trace_id，以便从日志条目跳转到完整的分布式追踪。

结构化日志

始终以结构化的 JSON 格式输出日志 —— 不要使用自由文本字符串。

必需字段

上下文增强

在中间件层级附加上下文，使下游日志自动继承：

app.use((req, res, next) => {
  const ctx = {
    trace_id: req.headers['x-trace-id'] || crypto.randomUUID(),
    request_id: crypto.randomUUID(),
    user_id: req.user?.id,
    method: req.method,
    path: req.path,
  };
  asyncLocalStorage.run(ctx, () => next());
});

库推荐

选择原生输出结构化 JSON 的日志库。避免需要后期处理的日志工具。

日志级别

规则： 生产环境默认日志级别为 INFO 及以上。若记录 ERROR，应有人响应处理。每个 FATAL 都应触发告警。

分布式追踪

OpenTelemetry 设置

优先使用 OpenTelemetry 而非厂商专用 SDK：

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  serviceName: 'order-service',
  traceExporter: new OTLPTraceExporter({
    url: 'http://otel-collector:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

跨度创建

const tracer = trace.getTracer('order-service');

async function processOrder(order: Order) {
  return tracer.startActiveSpan('processOrder', async (span) => {
    try {
      span.setAttribute('order.id', order.id);
      span.setAttribute('order.total_cents', order.totalCents);
      await validateInventory(order);
      await chargePayment(order);
      span.setStatus({ code: SpanStatusCode.OK });
    } catch (err) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
      span.recordException(err);
      throw err;
    } finally {
      span.end();
    }
  });
}

上下文传播

• 使用 W3C Trace Context (traceparent 头部) —— OTel 默认方式
• 在 HTTP、gRPC 和消息队列间传播
• 对异步工作器：将 traceparent 序列化至任务负载中

追踪采样

无论采用何种策略，始终对 100% 的错误追踪进行采样。

指标收集

RED 方法（请求驱动）

监控每个服务端点的以下三项：

USE 方法（资源驱动）

用于基础设施组件（CPU、内存、磁盘、网络）：

监控栈

markdown

name: Logging Observability

version: 0.1.0

description: 用于实现可观测性的日志与监控最佳实践

summary: 一套完整的日志、指标、链路追踪和告警设计指南，适用于微服务架构

category: observability

tags:

- logging

- metrics

- tracing

- alerting

- dashboard

- best practices

工具概览

推荐方案： 优先采用 OTel Collector → Prometheus + Grafana + Loki + Jaeger 组合。仅当运维成本显著高于收益时，再考虑迁移到 SaaS 平台。

告警设计

严重性等级

告警疲劳预防策略

• 告警关注症状而非原因 — 如“错误率 > 5%”，而非“Pod 重启”
• 支持多窗口、多燃烧速率检测 — 同时捕捉突发峰值与缓慢上升趋势
• 强制关联操作手册链接 — 每个告警必须附带诊断与修复指引
• 每月审查一次 — 删除或调整从不触发或持续触发的告警
• 合并相关告警 — 使用抑制规则防止子级告警泛滥
• 合理设置阈值 — 若告警每日触发且被忽略，应提高阈值或直接删除

仪表盘模式

总览仪表盘（“作战室”）

• 所有服务的总请求量（每秒）
• 全局错误率（百分比）及趋势线
• p50 / p95 / p99 延迟
• 按严重性分类的活跃告警数量
• 图表上叠加部署标记

服务级仪表盘（按服务）

• 每个端点的 RED 指标（Rate, Errors, Duration）
• 依赖健康状态（上游/下游成功率）
• 资源使用情况（CPU、内存、连接数）
• 错误列表（按出现次数排序，显示最近一次时间）

可观测性检查清单

每个服务必须具备：

• [ ] 使用结构化 JSON 格式记录日志，保持统一 schema
• [ ] 请求中传播关联 ID / trace ID
• [ ] 每个外部接口暴露 RED 指标
• [ ] 提供健康检查端点（/healthz 和 /readyz）
• [ ] 支持 OpenTelemetry 的分布式链路追踪
• [ ] 为 RED 指标和资源使用情况配置仪表盘
• [ ] 对错误率、延迟、饱和度设置告警，并附带操作手册链接
• [ ] 日志级别可在运行时动态调整，无需重新部署
• [ ] PII 数据脱敏已验证并经过测试
• [ ] 定义日志、指标、链路追踪的数据保留策略

反模式

绝对禁止事项

1. 绝不能记录密码、令牌、API Key 或任何密钥 — 即使是 DEBUG 级别也不行
2. 绝不能在生产环境使用 console.log / print — 必须使用结构化日志器
3. 绝不能将用户 ID、邮箱或请求 ID 作为指标标签 — 会导致标签基数爆炸
4. 绝不能创建没有操作手册链接的告警 — 无法执行的告警会削弱团队信任
5. 绝不能仅依赖日志 — 必须结合指标和链路追踪才能实现完整可观测性
6. 绝不能默认记录请求/响应体 — 必须明确开启，并确保 PII 已脱敏
7. 绝不能忽视日志量级 — 应设定日志配额，并在服务超过每日限额时发出告警
8. 绝不能在异步流程中跳过上下文传播 — 断裂的链路追踪比无追踪更糟糕