Java 日志体系与工程实践完整指南

// 永远这样写（用门面，不直接用实现类）
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger log = LoggerFactory.getLogger(OrderService.class);

// 好处：切换日报实现只改依赖，不撞代码
log.info("create order, order={}", orderId);

if (log.isDebugEnabled()) log.debug("detail pay={}", producePayload);  // 条件判断省序列化

log.info("user {} login from {}", userId, ip); // 懒拼，优于字符串拼接

<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>[%d{HH:mm:ss.SSS}] [%thread] %-5level %logger{40} - %msg%n</pattern>
    </encoder>
  </appender>
  <!-- 按大小尺寸+时间戳滚动 -->
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
          <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
          <maxHistory>30</maxHistory>
      </rollingPolicy>
  </appender>
  <root level="INFO"><appender-ref ref="CONSOLE"/><appender-ref ref="FILE"/></root>
</configuration>

// 入口设置（过滤器/AOP/网关）
MDC.put("traceId", TraceUtils.gen());
try {
    // 整个请求链路都带上 traceId
    log.info("handling request");
} finally {
    MDC.clear();
}

// pattern 中引用 MDC key
<pattern>[%d][%p][%X{traceId}] %logger - %msg%n</pattern>
// 每次 log 都自动带上 traceId，日志天然可串

<!-- logback 异步 Appender -->
<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
  <queueSize>512</queueSize>          <!-- 队列容量 -->
  <discardingThreshold>0</discardingThreshold> <!-- 永不丢弃 -->
  <appender-ref ref="FILE"/>
</appender>

// Log4j2 更彻底：全部异步（LMAX Disruptor 无锁队列）
<!-- log4j2.xml 关键配置 -->
<Configuration>
  <Appenders>
    <Async name="AsyncFile">
      <appender-ref ref="RollingFile"/>
    </Async>
  </Appenders>
</Configuration>

// 用 SLF4J + LogstashEncoder 输出 JSON
logger.info("order created, {}, {}, {}", orderId, userId, amount);

// 输出为：
{"@timestamp":"2026-09-26T15:00:00","level":"INFO",
 "logger":"com.demo.OrderService","message":"order created",
 "mdc":{"traceId":"a1b2c3"},"orderId":"10086","userId":"42","amount":"99.9"}

<encoder class="net.logstash.logback.encoder.LogstashEncoder">
  <customFields>{"app":"order-service","env":"prod"}</customFields>
</encoder>

统一字段规范（约定优于配置）：
  app、env、level、traceId、spanId、service、host、timestamp、message、error
  · 敏感字段不入日志（手机号、token、密钥要脱敏/不打印）
  · error 结构：errorClass + errorMessage + stackTrace

<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
    <fileNamePattern>logs/app.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
    <maxFileSize>100MB</maxFileSize>
    <maxHistory>30</maxHistory>
    <totalSizeCap>5GB</totalSizeCap>
</rollingPolicy>

应用（结构化 JSON）
  → Agent（Filebeat / Fluent Bit / OpenTelemetry Collector）
  → 存储（Elasticsearch / Loki / ClickHouse）
  → 查询告警（Kibana / Grafana / Alertmanager）

要点：
  1. Agent 独立进程，与应用故障隔离
  2. 采集端要处理"追尾/回传/断点续传"
  3. 日志平台要设索引生命周期（ILM），防止无限增长