如何在logback.groovy中启用AppOptics的ao.traceId实现请求日志追踪

第一步：排查日志框架生效链路 #

• Grails 3.0.16默认基于SLF4J + Logback实现日志体系，但如果项目存在原生log4j 1.2的依赖引入，会导致logback.groovy配置完全不生效，日志实际走log4j原生规则，自然无法输出你添加的%X{ao.traceId}占位符。
• 快速验证方法：启动时添加JVM参数-Dlogback.statusListenerClass=ch.qos.logback.core.status.OnConsoleStatusListener，观察控制台是否打印当前logback.groovy里配置的appender初始化日志，如果无输出，说明配置未加载。
• 依赖修正操作：在build.gradle中全局排除原生log4j依赖，避免框架冲突：

configurations.all {
    exclude group: 'log4j', module: 'log4j'
}

第二步：确认AppOptics Agent的Trace上下文注入正常 #

• AppOptics Java Agent只会在请求被纳入APM追踪范围时，才会把ao.traceId值写入SLF4J的MDC上下文，不会全局默认注入。
• 你当前的javaagent.json未配置追踪相关的开关阻断项，需要额外检查：
  • 确认agent启动日志中APM追踪模块加载成功，无类加载冲突报错
  • 确认触发的请求属于应用托管路径，没有被配置为排除追踪的规则
  • 排查异步场景的上下文丢失问题：如果使用自定义线程池、Tomcat异步Servlet，没有将MDC上下文快照传递到执行线程，会导致子线程日志无法读取到TraceId值。

第三步：修正Logback配置实现TraceId正常输出 #

• 你当前的pattern格式存在可优化空间，当MDC无对应值时会输出空字符串造成格式混乱，可参考以下修正后的logback.groovy配置：

appender("dailyAppender", RollingFileAppender) {
    file = "logs/stacktrace.log"
    append = true
    rollingPolicy(TimeBasedRollingPolicy) {
        fileNamePattern = "logs/stacktrace.%d{yyyy-MM-dd}.log"
        if ( currentEnvironment == Environment.TEST) {
            maxHistory = maxHistoryDays
            cleanHistoryOnStart = true
        }
    }
    encoder(PatternLayoutEncoder) {
        // 增加默认值兜底，空值时输出明确标识
        pattern = "%date [%thread] %-5level %logger{15} [ao-trace:%X{ao.traceId:-未捕获}]- %msg%n"
    }
}

常见踩坑说明 #

• 确保logback.groovy文件存放路径为Grails默认的grails-app/conf/目录，放错路径会被框架默认日志配置覆盖
• 如果使用log4j 1.2桥接逻辑，不要混用log4j原生的占位符语法，统一使用SLF4J规范的MDC取值规则
• 触发验证时，优先调用会被APM识别的同步Web请求，不要用静态资源、健康检查类请求测试TraceId输出

内容的提问来源于stack exchange，提问作者Atif Hussain