Scala 可观测性实战：结构化日志、链路追踪与指标

日志（Log）：发生了什么（事件）
  散落的、带上下文的、可搜索的事件流
  → 回答「发生了什么、何时」

追踪（Trace）：一次请求的完整路径
  trace/span 串联跨服务调用
  → 回答「哪个环节慢、哪次调用失败」

指标（Metric）：系统的数字脉搏
  延迟/吞吐/错误率/资源的聚合数字
  → 回答「系统健康吗、趋势如何」

协同：
指标告警 → 发现异常 → 追踪定位到服务/环节 → 日志看细节

结构化日志 = JSON 一行一条：
{ "time": "...", "level": "WARN", "logger": "...",
  "message": "...", "requestId": "...", "userId": "...",
  "durationMs": 123, "status": 500 }

字段规范（统一才有聚合价值）：
□ 必带：time/level/message/logger
□ 贯穿：requestId/traceId/userId（跨日志关联）
□ 业务：自定义业务字段（订单号、操作类型）
□ 性能：不要打大量高基数字段（如每次输出时间戳的秒值）

反模式：
✗ 散落字符串拼接：log.info("user " + id + " failed")
✓ 结构化字段：log.info("user failed", "userId" -> id)

SLF4J：日志门面（统一 API）
Logback：实现（配置灵活）
Logstash/logstash-logback-encoder：JSON 编码器

Logback 配置要点：
□ appender：Console（本地）+ File/JSON（生产）
□ 级别：dev=DEBUG，prod=INFO（WARN/ERROR 进告警）
□ 滚动：按大小/时间滚动，保留 N 天
□ 异步：AsyncAppender 提升吞吐（注意丢日志风险）

MDC（Mapped Diagnostic Context）：
□ 线程本地键值 → 每条日志自动带上下文（requestId/userId）
□ 关键：异步线程要手动传递 MDC（见第 6 节）

import org.slf4j.MDC
MDC.put("requestId", requestId)
log.warn("balance check failed", Map("userId" -> uid))
MDC.remove("requestId")

核心概念：
□ trace：一次用户请求的完整调用树
□ span：调用树里的一步（服务内部/跨服务调用）
□ traceId：整条链共享
□ parentId：父子关系（嵌套/跨服务）
□ span 属性：url/状态/耗时/错误

传播机制：
□ 服务 A 调 B：A 生成 span → 注入 traceId/parentId 到请求头
□ B 收到：从请求头提取 → 续接 parent → 记录 span
□ 标准头：traceparent（W3C）/ b3

跨进程传播工具：
□ 客户端注入：OkHttp/Http4s 的 OTel instrumentation
□ 消息队列：消息头带 trace 上下文（Kafka/AMQP）

span 示例：
GET /timeline (trace=ab12)
  ├─ DB query  (span, 45ms)
  ├─ Redis get (span, 2ms)
  └─ 调用推荐服务 (span, 120ms, HTTP)

OTel 组件：
□ SDK：Tracer/Meter/Logger 统一 API
□ Instrumentation：自动埋点（HTTP/DB/Redis/消费者）
□ Exporter：发到后端（Jaeger/Tempo/Grafana/OTLP）
□ Context：trace 上下文在线程内传播

Scala 侧集成：
□ OpenTelemetry Java SDK（Java/Scala 通用）
□ http4s / cats-effect 有 OTel 集成（Http4s OTel、Cats effect otel）
□ ZIO：zio-opentelemetry（原生 fiber 上下文贯穿）

关键点：
□ 自动埋点覆盖大部分「框架层调用」
□ 业务关键路径可手动加 span（定义业务语义）
□ 采样策略在 Exporter 层控制（见第 8 节）

// 手动 span（业务语义）
val span = tracer.spanBuilder("create-post").startSpan()
try { doWork() } finally { span.end() }

问题：Fiber 切换线程 → trace 上下文（线程本地）丢失
  → 异步代码的 span 断了、日志的 traceId 没了

解决：
□ Cats Effect IO：io.cede / parTraverse 会跨线程
  → 需要「上下文贯穿」：把 trace 上下文放进 fiber 环境
□ OTel Java agent：支持增强（自动传递）
□ 纯函数式方案：把上下文放进 Effect 环境（ZIO Environment / IOLocal）

IOLocal（Cats Effect）：
  IO 的「本地上下文」→ 随 fiber 传递，天然跨线程
  → 用来携带 requestId/traceId 比 MDC 更安全

MDC 在异步的替代：
□ 不用线程本地存上下文，用 Effect 环境/IOLocal
□ 日志输出时从上下文读取，写入 MDC 或 JSON 字段

import cats.effect.IOLocal
val requestId: IOLocal[String] = IOLocal.unsafe("unknown")
requestId.set("req-123").flatMap { _ =>
  ioParTraverse(jobs)  // 跨线程，但 requestId 随 fiber 传递
}

Micrometer：指标门面（统一 Meter API）
Prometheus：时序存储 + 查询
Grafana：可视化 + 告警

常用指标：
□ 业务：请求 QPS、错误率、处理时长（histogram）
□ 资源：JVM 内存/GC、连接池、线程池
□ 依赖：下游调用延迟/错误

Counter/Histogram/Gauge：
□ Counter：累加（请求数、错误数）
□ Histogram：分布（延迟 P50/P99）
□ Gauge：瞬时值（连接数、队列深度）

import io.micrometer.core.instrument.Metrics

val reqTimer = Metrics.timer("http.requests", "path" -> "/timeline")
val t = reqTimer.start()
try { handle() } finally { t.stop() }

// Prometheus 抓取：/metrics 端点暴露

指标命名与标签：
□ 命名：点分（http.requests, db.query.time）
□ 标签：path/status/type（注意标签基数别爆炸）
□ 基数控制：不要用 userId 当标签（高基数 → 存储爆炸）

采样（Trace）：
□ 全量采样成本高 → 按比例采样（10% 默认）
□ 重要服务/错误 span 必采（错误永远采，不采样本）
□ 尾采样：聚合后按「整条 trace 是否异常」决定保留

脱敏：
□ 日志：password/token/身份证 → 脱敏（正则替换）
□ trace 属性：请求体/响应体默认不打（隐私）
□ 指标标签：不携带敏感维度

告警联动：
□ 指标告警（p99 超阈、错误率超阈）→ 触发
□ 追踪入口查样本 → 定位环节
□ 日志查 requestId → 看细节
□ 告警要带「跳转链接」（到 trace/日志）

采样策略示例：
默认 10% 采样；ERROR span 100% 保留
→ 成本 10% × 正常流量，但所有故障 100% 可追踪

场景：接口 /timeline P99 从 200ms 飙到 2s，用户投诉

第 1 步（指标）：
  告警：http.requests.p99 /timeline > 1s
  → 明确「接口慢」，时间窗口定位到 14:02 起

第 2 步（追踪）：
  打开该接口的 trace 样本
  → 发现「推荐服务调用 span 平均 1.4s」→ 定位到下游

第 3 步（日志）：
  用 traceId 过滤推荐服务的日志
  → 发现「Redis 连接池超时」重复 WARN
  → 根因：Redis 连接池被某批慢查询占满

第 4 步（修复 + 验证）：
  扩大连接池 + 加慢查询告警
  → 指标回落 p99 250ms，日志不再 WARN