2. 结构化日志基础：JSON 格式与传统日志的对比与配置

在微服务与云原生架构中，日志不再是简单的“打印字符串”。传统日志（如纯文本行）难以被机器解析、聚合与检索，而结构化日志将每条日志记录为键值对集合，通常以 JSON 格式输出，使日志成为可查询、可分析的数据资产。本节从概念、对比到主流日志库的 JSON 配置，为你建立结构化日志的完整认知。

2.1 什么是结构化日志（JSON 格式）

结构化日志是指每条日志记录都遵循预定义的字段结构，而非自由文本。最常见的序列化格式是 JSON，因为它天然支持嵌套、数组与多种数据类型，且被几乎所有日志收集系统（如 ELK、Loki、Splunk）原生支持。

以下是一条典型的结构化日志（JSON 格式化后）：

{
  "timestamp": "2025-04-07T10:23:45.123+08:00",
  "level": "ERROR",
  "logger": "com.example.payment.PaymentService",
  "thread": "http-nio-8080-exec-3",
  "message": "支付接口调用超时",
  "context": {
    "orderId": "ORD20250407102345",
    "userId": "u_10086",
    "amount": 299.99,
    "retryCount": 2
  },
  "exception": {
    "class": "java.net.SocketTimeoutException",
    "message": "Read timed out",
    "stackTrace": "at ..."
  }
}

2.2 结构化日志 vs 传统日志

传统日志通常以自由文本形式输出，例如：

2025-04-07 10:23:45 ERROR [http-nio-8080-exec-3] PaymentService - 支付接口调用超时 | orderId=ORD20250407102345

这种格式虽然人类可读，但在自动化处理中存在明显短板。下表从多个维度对比两种日志模式：

2.3 常见日志库的 JSON 格式化配置

主流日志库均支持通过 Layout 或 Formatter 输出 JSON 格式。以下分别给出 Java（Log4j2、Logback）和 Python（logging）的配置示例。

2.3.1 Log4j2 — JSON Layout

Log4j2 内置 JsonLayout，可直接输出结构化 JSON。在 log4j2.xml 中配置：

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <JsonLayout complete="false" compact="true">
        <KeyValuePair key="service" value="payment-service"/>
        <KeyValuePair key="environment" value="production"/>
      </JsonLayout>
    </Console>
  </Appenders>
  <Loggers>
    <Root level="info">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>

• complete="false"：每条日志独立 JSON 对象，不包裹数组。
• compact="true"：压缩输出，不换行。
• KeyValuePair：添加固定业务标签。

2.3.2 Logback — 配合 logstash-logback-encoder

Logback 本身不提供 JSON Layout，但社区标准方案是 logstash-logback-encoder。在 logback-spring.xml 中配置：

<configuration>
  <appender name="JSON_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
      <includeContext>false</includeContext>
      <customFields>{"service":"payment-service","env":"production"}</customFields>
    </encoder>
  </appender>

  <root level="INFO">
    <appender-ref ref="JSON_CONSOLE"/>
  </root>
</configuration>

2.3.3 Python logging — 自定义 JSON Formatter

Python 标准库 logging 不内置 JSON 输出，但可通过自定义 Formatter 实现。以下是一个生产级实现：

import json
import logging
from datetime import datetime, timezone

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_entry = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        if record.exc_info and record.exc_info[0]:
            log_entry["exception"] = {
                "type": record.exc_info[0].__name__,
                "message": str(record.exc_info[1])
            }
        # 合并 extra 字段
        if hasattr(record, 'extra_fields'):
            log_entry.update(record.extra_fields)
        return json.dumps(log_entry, ensure_ascii=False)

# 使用示例
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logger = logging.getLogger("payment")
logger.addHandler(handler)
logger.setLevel(logging.INFO)

logger.info("支付成功", extra={"extra_fields": {"orderId": "ORD123", "amount": 99.9}})

2.4 结构化日志的架构位置

下图展示了结构化日志在微服务架构中的流转路径：从应用生成 JSON 日志，到采集器（Filebeat/Fluentd）传输，最终进入日志存储与可视化系统。

2.5 关键配置参数速查

下表汇总了三个日志库中与 JSON 输出相关的核心参数，方便你在实际项目中快速参考：