필사 모드: 结构化日志设计 — 做出故障时真正派得上用场的日志

// 差: 值被熔进了消息字符串里
logger.info(`user ${userId} checkout failed after ${ms}ms: ${err.message}`)
// -> 要数同一类事件就得写正则，而 err.message 一变正则就废了

// 好: 消息是常量，会变的值全部作为字段
logger.error(
  {
    event: 'checkout.failed',
    user_id: userId,
    order_id: orderId,
    duration_ms: ms,
    payment_provider: 'tosspay',
    err: { type: err.name, code: err.code, message: err.message },
  },
  'checkout failed'
)

# payment 服务留的是不带偏移量的 KST，checkout 服务留的是 UTC
grep 'payment accepted' payment.log | tail -1
# 2026-07-26T13:02:11.004 payment accepted order_id=A-99183

grep 'checkout completed' checkout.log | tail -1
# 2026-07-26T04:02:11.118Z checkout completed order_id=A-99183

# 明明是同一件事，却看起来差了 9 小时。没有办法把两份日志排在同一个界面里。

import pino from 'pino'

export const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  timestamp: pino.stdTimeFunctions.isoTime, // 带偏移量的 ISO 8601
  formatters: {
    level: (label) => ({ level: label }), // 用 "info" 而不是 30
  },
  base: {
    'service.name': process.env.OTEL_SERVICE_NAME,
    'service.version': process.env.SERVICE_VERSION,
    'deployment.environment': process.env.APP_ENV,
  },
})

// 错误处理器: 按责任归属划分级别
app.use((err, req, res, next) => {
  const status = err.status ?? 500
  const fields = {
    event: 'http.request.failed',
    http_status: status,
    route: req.route?.path,
    err: { type: err.name, code: err.code, message: err.message },
  }

  if (status >= 500) {
    req.log.error(fields, 'request failed') // 我们的责任
  } else if (status === 429) {
    req.log.warn(fields, 'request throttled') // 劣化
  } else {
    req.log.info(fields, 'request rejected') // 客户端的责任
  }

  res.status(status).json({ error: err.publicMessage ?? 'request failed' })
})

curl -sD - -o /dev/null https://checkout.internal/v1/orders \
  -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
  -H 'tracestate: acme=t61rcWkgMzE'

# 00                                 版本
# 4bf92f3577b34da6a3ce929d0e0e4736   追踪 ID (16 字节，整个请求中保持一致)
# 00f067aa0ba902b7                   父跨度 ID (8 字节，每一跳调用都不同)
# 01                                 标志位 (最后一位为 1 表示已被采样)

import { context, trace } from '@opentelemetry/api'
import { AsyncLocalStorage } from 'node:async_hooks'

const requestStore = new AsyncLocalStorage()

// 在请求入口处只植入一次上下文
export function requestContext(req, res, next) {
  const requestId = req.headers['x-request-id'] ?? crypto.randomUUID()
  res.setHeader('x-request-id', requestId)
  requestStore.run({ requestId, tenantId: req.auth?.tenantId }, () => next())
}

// 所有日志调用都会经过的薄封装
export function ctx(fields = {}) {
  const store = requestStore.getStore() ?? {}
  const span = trace.getSpan(context.active())
  const sc = span?.spanContext()
  return {
    ...fields,
    request_id: store.requestId,
    tenant_id: store.tenantId,
    trace_id: sc?.traceId,
    span_id: sc?.spanId,
    trace_sampled: sc ? Boolean(sc.traceFlags & 1) : undefined,
  }
}

logger.error(ctx({ event: 'checkout.failed', order_id: orderId }), 'checkout failed')

# 每行平均 1.2KB，每秒 4,000 行
python3 -c "print(f'{1.2*1024*4000*86400/1e9:.1f} GB/day')"
# 424.7 GB/day

# 假设保留 30 天，含索引的单价按每 GB 2.5 个货币单位计算
python3 -c "print(f'{424.7*30*2.5:,.0f} per month')"
# 31,853 per month

export const logger = pino({
  redact: {
    paths: [
      'req.headers.authorization',
      'req.headers.cookie',
      'req.headers["x-api-key"]',
      'req.body.password',
      'req.body.card_number',
      '*.email',
      '*.phone',
      'user.ssn',
    ],
    censor: '[REDACTED]',
  },
})

const KEEP_RATIO = 0.05

// 用 trace_id 做确定性判定 — 一次请求的日志要么全留要么全丢
function keepLowSeverity(traceId) {
  if (!traceId) return true
  const bucket = parseInt(traceId.slice(-4), 16) / 0xffff
  return bucket < KEEP_RATIO
}

export function emit(level, fields, msg) {
  const enriched = ctx(fields)
  const alwaysKeep = level === 'error' || level === 'warn' || enriched.trace_sampled
  if (!alwaysKeep && !keepLowSeverity(enriched.trace_id)) return
  logger[level](enriched, msg)
}

# 只要挂上了 exemplar，就能从这张图的点上直接跳到追踪
histogram_quantile(
  0.99,
  sum by (le, route) (rate(http_request_duration_seconds_bucket{job="checkout-api"}[5m]))
)