**logback-mdc-ttl 技术文档**-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01262/article/details/143044607

logback-mdc-ttl 技术文档

logback-mdc-ttl logback扩展，集成transmittable-thread-local支持跨线程池的mdc跟踪项目地址: https://gitcode.com/gh_mirrors/lo/logback-mdc-ttl

项目简介 logback-mdc-ttl 是一个专为解决日志追踪跨线程池问题设计的 logback 扩展模块。它巧妙地利用了 Transmittable ThreadLocal (TTL) 技术，确保在使用线程池这样的异步执行环境中，能够顺利传递 MDContext 的数据，满足分布式系统或者高并发场景下的日志一致性需求。该扩展支持 Java 9 及以下版本。

一、安装指南

Maven 依赖添加

首先，确保你的项目是基于Maven管理的。然后，在pom.xml文件的 <dependencies> 节点下加入以下依赖：

<dependency>
    <groupId>com.ofpay</groupId>
    <artifactId>logback-mdc-ttl</artifactId>
    <version>1.0.2</version>
</dependency>

确保这个版本与你的项目兼容，如果后期有更新，请访问 Maven Central 或项目 GitHub 仓库以获取最新版本信息。

Java 启动参数配置

为了启用 Transmittable ThreadLocal 功能，你需要调整 Java 的启动参数，添加如下两条指令：

-Xbootclasspath/a:/path/to/transmittable-thread-local-2.x.x.jar
-javaagent:/path/to/transmittable-thread-local-2.x.x.jar

替换 /path/to/ 部分为你实际存储 transmittable-thread-local jar 文件的路径，并确保版本号与logback-mdc-ttl兼容。

二、项目使用说明

配置Logback

修改你的 Logback 配置文件（通常是 logback.xml），以包含 TtlMdcListener。这一步使得 MDC 上下文能够在不同线程间正确传输。

<configuration>
    <!-- 其他配置 -->

    <!-- 添加此监听器以支持跨线程池的MDC -->
    <contextListener class="com.ofpay.logback.TtlMdcListener"/>
    
    <!-- 配置日志模式，展示 MDC 中的数据，例如 uuid -->
    <property scope="context" name="APP_PATTERN"
              value='%d{yyyy-MM-dd HH:mm:ss.SSS}|%X{uuid}|%level|%logger{10}|%message%n' />

    <!-- ... -->
</configuration>

记得将 %X{uuid} 替换成你实际需要跟踪的 MDC 键值。

三、项目API使用文档

该项目主要提供了对 logback 的增强接口，尤其是TtlMdcListener。你通常不需要直接调用API，而是通过配置文件间接使用。但是，了解其背后的机制有助于深入理解其运作原理：

TtlMdcListener：关键组件，负责在应用程序启动时设置监听器，确保每个线程都能访问到正确的 MDC 上下文，即使是在跨越线程池边界时。
使用 TransmittableThreadLocal：在你的业务代码中，你应该像使用常规的 ThreadLocal 一样使用 TTL 版本的变量，无需特别编码来处理跨线程传递逻辑，此部分操作已在底层实现。