structured-logging

Structured Logging Skill — 结构化日志

何时使用

• 新项目立项（日志格式从一开始定型）
• 调试"为什么 SRE 让我加 trace ID"
• 处理"日志体积爆炸 / 检索缓慢"
• 排查跨服务调用的请求链路
• 满足合规（PII / GDPR）的日志脱敏

一、核心原则

1. 机器优先：JSON 格式，键值对。人类用 jq / Loki / ES query 看
2. 每条日志带 context：service / version / env / trace_id / user_id / request_id
3. 大写 level 严格语义：DEBUG < INFO < WARN < ERROR < FATAL
4. 永不日志即吞噬：catch 后必须含 cause 或 rethrow
5. 结构化字段稳定：键名固定、不要混用 userId / user_id / uid
6. PII 默认脱敏：邮件 / 手机 / 身份证 / 卡号永远过滤 redactor

二、JSON 日志标准字段

{
  "ts": "2026-05-06T07:00:00.123Z",
  "level": "info",
  "service": "checkout-api",
  "version": "v2.3.1",
  "env": "production",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "request_id": "req_abc123",
  "user_id": "u_456",
  "msg": "order created",
  "order_id": "ord_789",
  "amount_cents": 12345,
  "currency": "USD",
  "duration_ms": 87
}

字段约定：

• ts ISO 8601 UTC（带 Z）
• level 小写：debug / info / warn / error / fatal
• msg 简短描述（不含变量值；变量在结构化字段里）
• trace_id / span_id 遵循 W3C Trace Context（OpenTelemetry 标准）

反模式：

// ❌ 字符串拼接
{ "msg": "user 123 created order 456 for $123.45" }

// ✅ 结构化
{ "msg": "order created", "user_id": 123, "order_id": 456, "amount_cents": 12345 }

理由：检索 user_id=123 比正则匹配 string 快几个数量级，且不受 msg 文案变化影响。

三、Log Level 语义（严格）

Level	含义	例子	生产开启？
DEBUG	开发诊断	"entering function X with args"	❌
INFO	正常事件	"user logged in" / "order created"	✅
WARN	异常但已恢复	"retrying after 5xx" / "fallback to cache"	✅
ERROR	失败需关注	"DB query failed" / "5xx returned"	✅（有告警）
FATAL	进程终止	"config invalid, shutting down"	✅（罕见）

关键：

• ERROR 应触发告警 → 慎用，不要给瞬时网络抖动打 ERROR
• INFO 日志 = 业务事件；不是函数追踪（用 trace 替代）
• DEBUG 日志生产关闭，但保留代码（dev / staging 启用）

四、Context 透传

Go (1.21+ slog)

import "log/slog"

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

// 带 context 的 logger（每个请求基础信息）
reqLogger := logger.With(
    "request_id", reqID,
    "user_id", userID,
    "trace_id", traceID,
)

reqLogger.Info("order created", "order_id", orderID, "amount_cents", 12345)