Java 日志开发实践整理

// 上下文全靠字符串拼接，检索只能依赖全文匹配
log.info("Order " + orderId + " status changed from " + oldStatus + " to " + newStatus + " for user " + userId);

log.atInfo()
    .setMessage("order status changed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("fromStatus", oldStatus)
    .addKeyValue("toStatus", newStatus)
    .addKeyValue("userId", userId)
    .log();

<!-- 推荐：只依赖 SLF4J API -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
</dependency>

<!-- 运行时绑定具体实现（Spring Boot 默认 Logback） -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
</dependency>

// 入口日志：记录消息消费起始
@KafkaListener(topics = "order-events")
public void onMessage(OrderEvent event) {
    log.atInfo()
        .setMessage("order event received")
        .addKeyValue("orderId", event.getOrderId())
        .addKeyValue("eventType", event.getType())
        .log();
    process(event);
}

// 关键状态变化
log.atInfo()
    .setMessage("order status changed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("fromStatus", "PENDING")
    .addKeyValue("toStatus", "PAID")
    .log();

// 影响业务结果的决策分支
if (stockCheckResult.isInsufficient()) {
    log.atWarn()
        .setMessage("order rejected: insufficient stock")
        .addKeyValue("orderId", orderId)
        .addKeyValue("skuId", skuId)
        .addKeyValue("requested", quantity)
        .addKeyValue("available", stockCheckResult.getAvailable())
        .log();
    return OrderResult.rejected("INSUFFICIENT_STOCK");
}

// 外部调用失败
log.atError()
    .setMessage("payment gateway call failed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("externalService", "payment-gateway")
    .addKeyValue("statusCode", response.getStatus())
    .setCause(e)
    .log();

// 禁止：密码、Token 进入日志
log.info("User login: username={}, password={}", username, password);         // 不建议这样写
log.info("Request headers: {}", request.getHeaders());                         // 可能含 Authorization
log.debug("Response body: {}", objectMapper.writeValueAsString(responseBody)); // 可能含个人信息

// 禁止：高频循环里的成功日志（每秒数千次）
for (Item item : items) {
    process(item);
    log.info("item processed: {}", item.getId()); // 噪声，应去除或降为 DEBUG + 采样
}

// 禁止：无业务含义的 entry / exit
log.debug("Entering calculateDiscount()");
log.debug("Exiting calculateDiscount()");

// 禁止：健康检查成功写入日志（每秒一次，纯噪声）
@GetMapping("/health")
public ResponseEntity<String> health() {
    log.info("Health check passed"); // 应改为指标
    return ResponseEntity.ok("UP");
}

// 禁止：循环计数器写入日志
for (Order order : orders) {
    process(order);
    log.info("processed order #{}", order.getId()); // 1000 次/分钟，应改为 Counter 指标
}

// 使用 Micrometer 计数器代替循环日志
private final Counter ordersProcessedCounter;

public OrderService(MeterRegistry registry) {
    this.ordersProcessedCounter = Counter.builder("orders.processed")
        .tag("type", "standard")
        .register(registry);
}

public void processBatch(List<Order> orders) {
    for (Order order : orders) {
        process(order);
        ordersProcessedCounter.increment(); // 指标，不产生日志
    }
    // 批处理完成时再写一条日志
    log.atInfo()
        .setMessage("batch order processing completed")
        .addKeyValue("totalCount", orders.size())
        .log();
}

log.info("User authenticated successfully for userId={}, ip={}, ua={}", userId, ip, userAgent);

log.atInfo()
    .setMessage("authentication succeeded")
    .addKeyValue("userId", userId)
    .addKeyValue("ip", ip)
    .addKeyValue("userAgent", userAgent)
    .log();

// 禁止：同一语义用了三种写法，导致检索和仪表盘规则分裂
log.atInfo().addKeyValue("order_id", orderId)...   // 下划线写法
log.atInfo().addKeyValue("OrderId", orderId)...    // 大驼峰写法
log.atInfo().addKeyValue("orderId", orderId)...    // 小驼峰写法（团队约定统一用这种）

// 正确：全项目只用一种写法
log.atInfo()
    .setMessage("payment initiated")
    .addKeyValue("orderId", orderId)          // 稳定字段名
    .addKeyValue("externalService", "alipay")
    .addKeyValue("durationMs", elapsed)
    .addKeyValue("statusCode", 200)
    .log();

// 合规场景下记录 userId，按政策做掩码
String maskedUserId = userId.substring(0, 3) + "****" + userId.substring(userId.length() - 2);
log.atInfo()
    .setMessage("user login succeeded")
    .addKeyValue("userId", maskedUserId)
    .addKeyValue("ip", clientIp)
    .log();

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RequestIdFilter extends OncePerRequestFilter {

    private static final String REQUEST_ID_HEADER = "X-Request-Id";
    private static final String MDC_KEY = "requestId";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String requestId = Optional.ofNullable(request.getHeader(REQUEST_ID_HEADER))
                .filter(s -> !s.isBlank())
                .orElse(UUID.randomUUID().toString());
        MDC.put(MDC_KEY, requestId);
        response.setHeader(REQUEST_ID_HEADER, requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove(MDC_KEY); // 确保线程归还线程池时 MDC 已清理
        }
    }
}

// ERROR：业务流程失败，需要人工介入
log.atError()
    .setMessage("order payment failed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("externalService", "payment-gateway")
    .setCause(e)
    .log();

// WARN：命中降级，系统仍可继续，但需要后续跟进
log.atWarn()
    .setMessage("inventory service degraded: using cached result")
    .addKeyValue("skuId", skuId)
    .addKeyValue("cacheAge", cacheAgeMs)
    .log();

// INFO：关键业务事件，正常流程
log.atInfo()
    .setMessage("order created")
    .addKeyValue("orderId", orderId)
    .addKeyValue("userId", maskedUserId)
    .addKeyValue("totalAmount", amount)
    .log();

// DEBUG：开发诊断细节，生产默认关闭
log.atDebug()
    .setMessage("discount rule evaluated")
    .addKeyValue("ruleId", rule.getId())
    .addKeyValue("matched", matched)
    .addKeyValue("discountRate", rate)
    .log();

// 禁止：用 ERROR 记录业务校验失败（不需要人工介入）
log.error("Invalid request: missing orderId"); // 应该用 WARN 或 INFO

// 禁止：用 INFO 记录调试细节（噪声过高）
log.info("Checking discount rule #{} for user {}", ruleId, userId); // 应该用 DEBUG

// 禁止：用 WARN 记录已造成业务中断的失败
log.warn("Failed to deduct balance, order cannot proceed"); // 已影响业务，应该用 ERROR

// 面向开发者：包含技术细节
log.atError()
    .setMessage("database connection pool exhausted")
    .addKeyValue("poolSize", pool.getMaxConnections())
    .addKeyValue("activeConnections", pool.getActiveConnections())
    .addKeyValue("waitQueueSize", pool.getWaitQueueSize())
    .setCause(e)
    .log();

// 面向 DevOps：包含系统状态和依赖
log.atWarn()
    .setMessage("upstream service timeout: using fallback response")
    .addKeyValue("service", "recommendation-service")
    .addKeyValue("timeoutMs", timeout)
    .addKeyValue("fallbackUsed", true)
    .log();

// 面向支持团队：业务友好，不含技术细节
log.atInfo()
    .setMessage("order processing delayed: payment verification in progress")
    .addKeyValue("orderId", orderId)
    .addKeyValue("estimatedCompletionMinutes", 5)
    .log();

logging:
  group:
    payment: com.example.payment,com.example.gateway
  level:
    payment: DEBUG   # 一次性调整整个支付模块

# 在线将 payment 包调到 DEBUG，无需重启
curl -X POST http://localhost:8080/actuator/loggers/com.example.payment \
     -H “Content-Type: application/json” \
     -d '{“configuredLevel”: “DEBUG”}'

// 禁止：只打 message，堆栈丢失
log.error("Payment failed: {}", e.getMessage());

// 禁止：把上下文硬塞进异常字符串
log.error("Payment failed for order={}, service={}: {}", orderId, service, e.getMessage());

// 正确：setCause(e) 保留完整堆栈，addKeyValue 提供可检索上下文
log.atError()
    .setMessage("payment gateway call failed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("externalService", "payment-gateway")
    .addKeyValue("statusCode", response.getStatus())
    .setCause(e)
    .log();

try {
    paymentGateway.charge(request);
} catch (GatewayTimeoutException e) {
    // 抛出业务异常时，把原始异常作为 cause 保留
    throw new PaymentFailedException("payment timed out", e);
}

// 在最外层统一记录，cause chain 完整
log.atError()
    .setMessage("order payment failed")
    .addKeyValue("orderId", orderId)
    .setCause(e) // PaymentFailedException，cause 指向 GatewayTimeoutException
    .log();

// 只在最终失败时记录，排障时不知道为什么会走到这里
log.atError()
    .setMessage("order creation failed")
    .addKeyValue("orderId", orderId)
    .setCause(e)
    .log();

// 1. 请求进入时的入口日志
log.atInfo()
    .setMessage("order creation request received")
    .addKeyValue("orderId", orderId)
    .addKeyValue("userId", maskedUserId)
    .addKeyValue("itemCount", request.getItems().size())
    .log();

// 2. 关键校验结果
if (!inventoryCheck.isAvailable()) {
    log.atWarn()
        .setMessage("order creation blocked: insufficient inventory")
        .addKeyValue("orderId", orderId)
        .addKeyValue("requestedSku", inventoryCheck.getSkuId())
        .addKeyValue("availableQty", inventoryCheck.getAvailable())
        .log();
    throw new InsufficientInventoryException(inventoryCheck.getSkuId());
}

// 3. 外部调用的关键结果
log.atInfo()
    .setMessage("payment authorization obtained")
    .addKeyValue("orderId", orderId)
    .addKeyValue("authId", paymentAuth.getAuthorizationId())
    .addKeyValue("authorizedAmount", paymentAuth.getAmount())
    .log();

// 4. 最终失败（包含完整上下文）
log.atError()
    .setMessage("order creation failed: inventory reservation timeout")
    .addKeyValue("orderId", orderId)
    .addKeyValue("step", "inventory-reservation")
    .addKeyValue("elapsedMs", elapsed)
    .setCause(e)
    .log();

<configuration>

  <!-- 同步文件 Appender -->
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/app.log</file>
    <encoder>
      <pattern>%d{ISO8601} %-5level [%X{traceId},%X{requestId}] %logger{36} - %message %kvp%n</pattern>
    </encoder>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
      <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>30</maxHistory>
    </rollingPolicy>
  </appender>

  <!-- 异步包装：把 FILE 包进队列，业务线程不等写盘 -->
  <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="FILE"/>
    <queueSize>512</queueSize>          <!-- 队列满则触发背压，不宜设太大 -->
    <discardingThreshold>0</discardingThreshold> <!-- 0 表示队列 80% 满时不主动丢 TRACE/DEBUG -->
    <includeCallerData>false</includeCallerData>  <!-- 采集类名/行号代价高，按需开启 -->
    <neverBlock>false</neverBlock>      <!-- false：队列满时阻塞业务线程；true：直接丢弃 -->
  </appender>

  <root level="INFO">
    <appender-ref ref="ASYNC_FILE"/>
  </root>

</configuration>

// 禁止：高频循环中的成功日志
for (Order order : orders) { // 假设每秒处理数千个
    process(order);
    log.info("order processed: {}", order.getId()); // 噪声过高
}

// 推荐：只在异常或批处理完成时记录
log.atInfo()
    .setMessage("batch order processing completed")
    .addKeyValue("totalCount", orders.size())
    .addKeyValue("successCount", successCount)
    .addKeyValue("failedCount", failedCount)
    .log();

logging:
  structured:
    format:
      file: ecs  # 直接输出 JSON，无需采集器解析

// 错误示例：即使日志级别关闭，toString() 和序列化仍会执行
log.debug("Request body: {}", objectMapper.writeValueAsString(request));

// 正确示例 1：使用 isDebugEnabled() 守卫
if (log.isDebugEnabled()) {
    log.debug("Request body: {}", objectMapper.writeValueAsString(request));
}

// 正确示例 2：使用 Supplier 延迟求值（SLF4J 2.0+）
log.atDebug()
    .setMessage(() -> "Request body: " + serializeExpensive(request))
    .log();

// 正确示例 3：使用 Marker 控制特定日志的开关
Marker sensitiveData = MarkerFactory.getMarker("SENSITIVE");
log.atInfo().addMarker(sensitiveData)
    .setMessage("user PII accessed")
    .addKeyValue("userId", maskedUserId)
    .log();

// 在 logback-spring.xml 中可单独控制此 Marker
// <logger name="com.example" level="INFO">
//   <markerFilter marker="SENSITIVE" onMatch="DENY" onMismatch="NEUTRAL"/>
// </logger>

// 特定用户或环境的日志全量保留
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class DynamicSamplingFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String userId = request.getHeader("X-User-Id");
        boolean isDebugUser = "debug-user-123".equals(userId);

        if (isDebugUser) {
            // 特定用户全量保留，允许输出 DEBUG
            MDC.put("logLevel", "DEBUG");
        }

        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove("logLevel");
        }
    }
}

<configuration>

  <!-- TurboFilter 在日志事件创建前执行，开销极低 -->
  <turboFilter class="ch.qos.logback.classic.turbo.DynamicMDCFilter">
    <defaultThreshold>INFO</defaultThreshold>
    <!-- MDC 中 logLevel=DEBUG 的请求允许输出 DEBUG -->
    <mdcValueThresholdPairs>
      <mdcValueThresholdPair>
        <value>DEBUG</value>
        <threshold>DEBUG</threshold>
      </mdcValueThresholdPair>
    </mdcValueThresholdPairs>
  </turboFilter>

  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{ISO8601} %-5level [%X{traceId},%X{requestId}] %logger{36} - %message %kvp%n</pattern>
    </encoder>
  </appender>

  <root level="TRACE">
    <appender-ref ref="CONSOLE"/>
  </root>

</configuration>

<!-- logback-spring.xml -->

<!-- stdout：INFO、WARN -->
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <target>System.out</target>
  <encoder class="co.elastic.logging.logback.EcsEncoder"/>
</appender>

<!-- stderr：只接收 ERROR 及以上 -->
<appender name="ERROR_CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <target>System.err</target>
  <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
    <level>ERROR</level>
  </filter>
  <encoder class="co.elastic.logging.logback.EcsEncoder"/>
</appender>

<root level="INFO">
  <appender-ref ref="CONSOLE"/>
  <appender-ref ref="ERROR_CONSOLE"/>
</root>

// 禁止：catch 后什么都不做
try {
    paymentService.charge(request);
} catch (PaymentException e) {
    // 异常被静默吞掉，排障无从下手
}

// 禁止：只打印到标准输出，不进入日志系统
try {
    paymentService.charge(request);
} catch (PaymentException e) {
    e.printStackTrace(); // 不进入集中式日志平台
}

// 禁止：记录的内容和抛出的异常完全一样，没有增加上下文
try {
    paymentService.charge(request);
} catch (PaymentException e) {
    log.error("Payment failed: {}", e.getMessage()); // 无新增信息
    throw e;
}

// 正确：增加业务上下文后重新抛出，或在顶层统一记录
try {
    paymentService.charge(request);
} catch (PaymentException e) {
    log.atError()
        .setMessage("payment processing failed")
        .addKeyValue("orderId", orderId)
        .addKeyValue("paymentMethod", request.getMethod())
        .setCause(e)
        .log();
    throw new OrderProcessingException("Failed to process payment for order " + orderId, e);
}

// 禁止：无法知道哪个服务、哪个请求、什么状态码
log.error("Communication error");

// 禁止：信息量不足，无法定位问题
log.warn("Something went wrong");

// 正确：明确动作、目标、结果
log.atError()
    .setMessage("inventory service call failed")
    .addKeyValue("service", "inventory-service")
    .addKeyValue("statusCode", 503)
    .addKeyValue("retryCount", 3)
    .addKeyValue("orderId", orderId)
    .setCause(e)
    .log();

// 禁止：过度日志（每个方法 entry/exit + 每个变量变化）
log.debug("Entering processOrder()");
log.debug("orderId = {}", orderId);
log.debug("Calling validateOrder()");
log.debug("Exiting validateOrder(), result = {}", valid);
log.debug("Calling calculatePrice()");
// ... 数十行类似日志

// 禁止：日志饥饿（整个关键流程只有一行，无异常堆栈）
log.info("Order processed"); // 成功失败？耗时？哪些步骤？无从得知

// 正确：关键边界 + 结构化上下文
log.atInfo()
    .setMessage("order processing completed")
    .addKeyValue("orderId", orderId)
    .addKeyValue("durationMs", elapsed)
    .addKeyValue("stepsCompleted", List.of("validation", "pricing", "inventory-reserve", "payment"))
    .log();

// 禁止：容器内写文件，Pod 重启后丢失
File logFile = new File("/var/log/app/debug.log");
Files.writeString(logFile.toPath(), logLine); // 容器文件系统不是持久化存储

// 正确：输出到 stdout/stderr，由平台采集
log.info("Debug information: {}", details); // 配置 ConsoleAppender 即可

<!-- logback-spring.xml -->
<configuration>

  <!-- 从 application.yml 读取 myapp.log-service.host，默认 localhost -->
  <springProperty scope="context" name="logHost"
                  source="myapp.log-service.host"
                  defaultValue="localhost"/>

  <!-- 从 application.yml 读取 myapp.log-service.port，默认 5044 -->
  <springProperty scope="context" name="logPort"
                  source="myapp.log-service.port"
                  defaultValue="5044"/>

  <appender name="LOGSTASH" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
    <destination>${logHost}:${logPort}</destination>
    <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
  </appender>

  <root level="INFO">
    <appender-ref ref="LOGSTASH"/>
  </root>

</configuration>

myapp:
  log-service:
    host: log-collector.internal
    port: 5044

<configuration>

  <!-- 开发环境：彩色控制台，DEBUG 级别 -->
  <springProfile name="dev">
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
        <pattern>%cyan(%d{HH:mm:ss.SSS}) %magenta(%thread) %-5level %logger{36} - %msg%n</pattern>
      </encoder>
    </appender>
    <root level="DEBUG">
      <appender-ref ref="CONSOLE"/>
    </root>
  </springProfile>

  <!-- 生产环境：JSON ECS 输出，INFO 级别 -->
  <springProfile name="prod">
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder class="co.elastic.logging.logback.EcsEncoder"/>
    </appender>
    <root level="INFO">
      <appender-ref ref="CONSOLE"/>
    </root>
  </springProfile>

  <!-- 多环境组合：staging 或非 production 环境都生效 -->
  <springProfile name="staging | !production">
    <logger name="com.example.payment" level="DEBUG"/>
  </springProfile>

</configuration>

# application-dev.yml
logging:
  level:
    root: DEBUG

# JVM 启动参数推荐
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/log/app/heapdump.hprof
-Xlog:gc*:file=/var/log/app/gc.log:time,uptime,level,tags:filecount=5,filesize=50m
-Xlog:jni+resolve=off

-Xlog:gc*:stdout:time,uptime,level,tags