3、结构化日志基础：什么是结构化日志？JSON格式、日志级别、字段设计原则

3.1 从文本日志到结构化日志的演进

传统日志是纯文本字符串，人类可读但机器难以解析。在分布式系统中，日志需要被采集、过滤、聚合、告警和关联分析，纯文本日志的局限性日益突出。

3.2 JSON 格式：结构化日志的事实标准

JSON（JavaScript Object Notation）因其轻量、自描述、跨语言支持，成为结构化日志最广泛采用的序列化格式。一个典型的 JSON 日志条目如下：

{
  "timestamp": "2025-03-21T14:32:10.123Z",
  "level": "ERROR",
  "logger": "com.example.order.Service",
  "message": "订单支付超时",
  "service.name": "order-service",
  "trace_id": "abc123def456",
  "span_id": "span789ghi012",
  "order_id": "ORD-20250321-0042",
  "amount": 299.99,
  "duration_ms": 5230,
  "exception": {
    "type": "java.util.concurrent.TimeoutException",
    "message": "等待支付确认超过5秒",
    "stacktrace": "java.util.concurrent.TimeoutException: ..."
  }
}

JSON 格式的优势在于：

• 自描述性：字段名即语义，无需额外文档
• 嵌套结构：支持对象和数组，表达复杂上下文
• 类型保留：字符串、数字、布尔值、null 原生区分
• 生态成熟：所有编程语言、日志框架、采集工具均支持

3.3 日志级别：从 DEBUG 到 FATAL

日志级别是结构化日志的必选字段，用于标识事件的严重程度。OpenTelemetry 日志数据模型（LogRecord）沿用了业界通用的级别体系：

3.4 字段设计原则：让日志成为可查询的数据

结构化日志的字段设计直接决定后续的可观测性能力。以下原则来自 OpenTelemetry 语义约定（Semantic Conventions）及一线生产经验：

3.4.1 必选字段（Minimum Required）

• timestamp — 事件发生时间，RFC3339 格式，精度到毫秒或微秒
• level — 日志级别，字符串或数值
• message — 人类可读的描述，支持模板参数
• service.name — 服务标识，用于跨服务过滤

3.4.2 可观测性关联字段

• trace_id / span_id — 与分布式链路追踪关联
• resource — 基础设施信息（主机、容器、集群）
• attributes — 业务自定义键值对，用于过滤和聚合

3.4.3 字段命名规范

3.4.4 字段值类型约束

• 字符串：用于标识符、消息、名称，长度建议不超过 1024 字符
• 数值：用于时长、计数、金额，避免字符串化
• 布尔值：用于开关状态、成功/失败标志
• 对象：用于异常堆栈、请求参数，深度不超过 3 层
• 数组：用于标签列表、批量 ID，元素数量不超过 100

3.5 结构化日志与 OpenTelemetry 的协同关系

下图展示了结构化日志在 OpenTelemetry 体系中的位置，以及它与 Trace、Metric 的数据关联方式：

结构化日志是连接 Trace 和 Metric 的“粘合剂”。当一条日志携带了 trace_id，运维人员可以从日志直接跳转到对应的分布式调用链；当日志包含 duration_ms 等数值字段，可以聚合为业务指标。

3.6 实战：从零构建一条符合 OpenTelemetry 规范的结构化日志

以下示例使用 Python 的 structlog 库，展示如何输出符合 OpenTelemetry 语义的结构化日志：

import structlog
import json
from datetime import datetime, timezone

# 配置结构化日志处理器
structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()
    ],
    context_class=dict,
    logger_factory=structlog.PrintLoggerFactory(),
)

logger = structlog.get_logger()

# 在业务代码中记录日志
def process_order(order_id: str, amount: float):
    logger.info("order.received", 
                order_id=order_id, 
                amount=amount,
                service_name="order-service")
    
    try:
        # 模拟支付处理
        result = pay(order_id, amount)
        logger.info("order.paid", 
                    order_id=order_id,
                    payment_id=result["payment_id"],
                    duration_ms=result["duration_ms"])
    except Exception as e:
        logger.error("order.payment_failed",
                     order_id=order_id,
                     amount=amount,
                     exception={
                         "type": type(e).__name__,
                         "message": str(e)
                     })

输出示例（单行 JSON）：

{"event": "order.received", "level": "info", "timestamp": "2025-03-21T14:32:10.123Z", "order_id": "ORD-20250321-0042", "amount": 299.99, "service_name": "order-service"}

3.7 常见陷阱与避坑指南