简介这是一款面向Java开发者的轻量级分布式日志标记与链路追踪工具专为微服务、Dubbo RPC等分布式场景设计可帮研发人员在排查跨服务请求时快速串联日志、定位慢调用与异常源头。资源包共124个文件以76个Java源码文件为主干配合28个XML配置、8个spring.factories自动装配声明及2个Filter过滤器定义另有properties配置、Markdown说明与示例图片整体体积仅465KB结构清晰且极易二次开发。截至目前已有402人学习下载。借助源码可完整掌握基于Filter机制向RPC调用注入日志标记并跨节点传递的实现思路学会在Dubbo调用链中自动携带追踪ID同时spring.factories与XML配置展示了Spring Boot自动装配和自定义过滤器的接入方式适合对链路追踪、日志埋点感兴趣的初中级Java开发者直接借鉴。项目还包含精简的配置与示例稍作调整就能嵌入现有工程用于日志染色、全链路排查和监控数据汇聚。1. Java 轻量级分布式日志标记追踪到底在追什么一个请求从网关进来先打到订单服务再通过 OpenFeign 调库存服务库存服务又往消息队列里丢了一条消息最后消费者在凌晨三点才把这条消息处理完。出问题的时候你面对的是四台机器、五个日志文件、几十万行带毫秒时间戳的记录唯一的线索是“大概在下午两点多用户报了一个错”。如果没有在日志里埋一个贯穿始终的标记定位这个问题的成本就是以小时计算的。标题里说的“日志标记追踪”解决的就是这个场景用一个 traceId 把一次业务请求在所有服务、所有线程里产生的日志串起来。它不统计调用耗时不做链路拓扑不依赖 agent 和字节码增强注释掉依赖就是普通日志——这是它和 SkyWalking、Zipkin 这类全链路监控系统最根本的区别。这类 zip 解压后通常就是一两个 jar 包加配置说明Java 开发者自己维护一套成本很低适合日志量大、不想引入重组件的团队。2. 追踪原理与边界traceId 的生成、传播与清理2.1 一个 zip 包里的标记追踪组件通常分三层第一层是生成与清理。入口处生成全局唯一的 traceId请求结束后从上下文移除第二层是进程内传递借助 SLF4J 的 MDC 机制把 traceId 注入日志 pattern第三层是跨进程传递通过 HTTP Header、Dubbo attachment、MQ 消息头把 traceId 带到下游服务。大多数轻量级实现不会自己做存储和展示日志打到文件或 Elasticsearch 后靠 grep 或者 Kibana 检索 traceId 来还原一条链路。这里要划清一条边界日志标记追踪和分布式事务、分布式锁是两码事。标题里这个组件只负责“让同一条业务链路的日志长得一样”不会帮你解决订单与库存的一致性问题。把视角放窄实现成本就低得多——一个拦截器加一个 Feign 拦截器核心代码量通常不到 200 行。这也是它适合作为自研组件而非采购商业 APM 的原因。2.2 三种技术选型的对比判断能力维度日志标记追踪 zip 组件SkyWalking / Zipkin全量日志集中采集接入成本引入 jar 配置安装 agent / 独立部署 collector部署 Filebeat Kafka ES生效范围日志内容调用链、拓扑、性能指标所有日志但不区分链路性能开销几乎为零低但有序列化和上报开销取决于采集端吞吐排障效果能回答“这条请求走了哪些服务、各阶段日志是什么”能回答“哪一段慢、失败在哪”能回答“某时间窗系统里发生了什么”如果团队已经在用 ES 全家桶日志标记追踪的价值会被放大traceId 作为独立字段进入 ESKibana 里点一下字段就能筛出整条链路。如果只装了 SkyWalking它的日志与调用链是分开的想从日志反查链路反而不如 traceId 直接。2.3 进程内传递为什么 MDC 是唯一可靠的入口MDC 的全称是 Mapped Diagnostic Context底层是每个线程私有的 ThreadLocal。日志框架的 pattern 里配置%X{traceId}后每次打日志都会自动带上当前线程 MDC 里的值。这是 SLF4J 生态的标准能力Logback 和 Log4j2 都原生支持不需要 hack。因此一个设计良好的组件必须在收到请求的第一时间把 traceId 塞进 MDC并在请求结束的 finally 块里调用MDC.remove或MDC.clear。忽略清理是这类组件最常见的坑。Tomcat 默认用线程池复用线程如果请求 A 设置了 traceId 而请求 B 因为某种原因没有重新设置日志就能看到两个请求的 traceId 串线。这不是小概率问题只要某条链路里有一次返回 304 或静态资源拦截器没经过就会复现。2.4 跨进程传递获取、透传与再生成跨服务传递的策略是“不上行就生成上行则透传”。入口网关或最外层服务先从请求头里取 traceId取到说明上游已经标记过直接放入 MDC取不到则自己生成一个。下游服务做同样的动作。这是保证全链路 traceId 一致的大前提。组件里头的 header 命名建议遵循业界常用的X-Trace-Id或者内部约定的traceId。要注意和网关层做好配合如果前置 Nginx 或 Spring Cloud Gateway 会把未知 header 过滤掉要显式放行该 header否则下游收不到。同步场景靠 Feign 或 RestTemplate 的拦截器透传异步场景则要手动把 traceId 拷贝到子线程的 MDC 里。具体实现放在下一章直接看代码。3. 从零实现traceId 生成、MDC 注入与跨服务透传的最小工程3.1 工程骨架与常量定义public final class TraceConstant { public static final String TRACE_ID traceId; public static final String HEADER_NAME X-Trace-Id; private TraceConstant() { } }traceId 的生成单独抽一个方法便于替换生成算法。不建议直接用UUID.randomUUID().toString()字符串太长日志里刷屏排障时肉眼比对也费劲。一般用去掉连字符的字符串截取前 16 位或者用 IP 后两段 时间戳 原子自增拼接保证分布式环境下足够唯一即可。3.2 入口拦截器生成、注入、清理三步走Component public class TraceIdInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { String traceId request.getHeader(TraceConstant.HEADER_NAME); if (traceId null || traceId.isBlank()) { traceId TraceIdGenerator.generate(); } MDC.put(TraceConstant.TRACE_ID, traceId); response.setHeader(TraceConstant.HEADER_NAME, traceId); return true; } Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { MDC.remove(TraceConstant.TRACE_ID); } }这段代码是组件的核心逻辑之一。preHandle阶段从 Header 取上游 traceId取不到则新生成放入 MDC 后所有后续日志都能通过%X{traceId}拿到它afterCompletion里的MDC.remove保证线程归还到 Tomcat 线程池时不会残留上下文。为什么用remove而不是clearclear会清掉整个线程的 MDC如果其他框架往里放了别的诊断信息会被一并删掉remove只删自己关心的 key。注册时注意设置拦截器的order让它尽量排在过滤器链的前列。按WebMvcConfigurer注册即可Configuration public class WebConfig implements WebMvcConfigurer { Resource private TraceIdInterceptor traceIdInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(traceIdInterceptor) .addPathPatterns(/**) .order(Ordered.HIGHEST_PRECEDENCE); } }3.3 Feign 透传从 MDC 里取出来再放进请求头Bean public RequestInterceptor traceIdFeignInterceptor() { return requestTemplate - { String traceId MDC.get(TraceConstant.TRACE_ID); if (traceId ! null) { requestTemplate.header(TraceConstant.HEADER_NAME, traceId); } }; }Feign 的RequestInterceptor会在每次请求发出前执行和业务代码完全解耦。逻辑说明从当前线程的 MDC 中取出 traceId放进 outgoing 请求的 Header下游服务的拦截器再从这个 Header 里取到它并放入自己的 MDC链路就串起来了。参数只有一个 header 名称务必和入口拦截器里读到的名称保持一致。RestTemplate和WebClient的写法略有差异RestTemplate用ClientHttpRequestInterceptorWebClient则依赖ExchangeFilterFunction思路是一样的。3.4 异步子线程的场景包装 Runnablepublic static Runnable wrapTraceId(Runnable runnable) { MapString, String contextMap MDC.getCopyOfContextMap(); return () - { MDC.setContextMap(contextMap); try { runnable.run(); } finally { MDC.clear(); } }; }使用方式executor.submit(wrapTraceId(() - orderService.sendMessage(msg)))。这里必须用getCopyOfContextMap而不是get单个值因为拿到的是当前线程 MDC 的完整快照子线程执行时直接还原整份上下文避免主线程后续又 put 了新值导致半个链路 traceId 分裂。子线程跑完要MDC.clear()和拦截器里remove的原因一致——线程池里的线程是复用的。到这一步一个组件的核心能力已经齐了解压后装上就能跑。4. 集成与验证本地模拟分布式环境把链路日志跑通4.1 落盘配置日志里必须能看见 traceId无论拦截器写得多好日志 pattern 里没配%X{traceId}都等于白做。Logback 的最小配置pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] [%X{traceId}] %logger{36} - %msg%n/pattern%X{traceId}就是取值MDC.get(traceId)的结果这是可插拔的。没走拦截器的日志打出来[ ]空着走了就是 32 位字符串。落在文件里每个 log 后面都跟着唯一的请求标识这是后续 grep 或者 ES 检索的前提。4.2 用 IDEA 多开进程服务模拟分布式单机模拟分布式的最快方法是让同一个服务在本地两个端口各跑一个实例。IDEA 的Run/Debug Configurations里复制一份 Spring Boot 启动配置在VM options里写-Dserver.port8081另一份写-Dserver.port8082然后同时启动两个进程。模拟的拓扑是8082 通过 OpenFeign 请求 8081。8081 充当“下游服务”8082 充当“入口服务”。如果你的机器只有一份配置加了拦截器会出现 traceId 断链两份都配上日志才会对得上。注意 idea 里相同的工程默认不会同时在两个 Configuration 里启动需要勾选Allow parallel run。4.3 两次请求验证同名不同 id启动后构造两个带有不同业务参数的 GET 请求直接请求 8082 同一个接口两次保证是两次独立调用。curl http://localhost:8082/api/order/detail?orderId10001 curl http://localhost:8082/api/order/detail?orderId10002然后去两个进程各自的日志目录拉出日志分别小写 grep 这同一个 trace 关键字grep f3a1c2e4b5d6498f8a7b6c5d4e3f2a1b app-8081.log app-8082.log如果 8082 和 8081 的日志都出现了同一串 traceId链路就已经通了8082 生成的 traceId 通过 Feign header 透传到了 8081。重点是验证两次请求是“不同 traceId、相同格式”避免出现充值缓存导致第二次也命中同一条链路。4.4 落库索引把日志检索变成 SQL 查询经常排查分布式日志的团队会在 MySQL 里放一张日志索引表把 traceId 作为分区键或普通索引列。设计最小表结构CREATE TABLE log_trace_index ( id BIGINT AUTO_INCREMENT PRIMARY KEY, trace_id VARCHAR(32) NOT NULL, app_name VARCHAR(64) NOT NULL, log_level VARCHAR(10) NOT NULL, log_time DATETIME(3) NOT NULL, message VARCHAR(2000), KEY idx_trace_time (trace_id, log_time) ) ENGINE InnoDB;插入数据时把日志关键字段落库排障时一句话定位所有涉及的节点不需要登录每台机器找半天SELECT app_name, log_level, log_time, message FROM log_trace_index WHERE trace_id f3a1c2e4b5d6498f8a7b6c5d4e3f2a1b ORDER BY log_time;注意确保log_time精确到毫秒因为trace_id相同的情况下时间顺序就是业务逻辑顺序。如果日志写入了 ES 则更省事直接按 keyword 字段查traceId排序即可但要注意 mapping 里别被 text 分词器切成两个词必须显式定义成keyword。5. 生产排查实战traceId 丢失、ES 检索与三个高频命令5.1 三个最常见的 traceId 丢失现场第一个是ExecutorService没包装。业务里用了线程池线程池里的日志 traceId 全是空的。排查方法是看日志里的[%X{traceId}]如果有一段是空的而旁边的日志有值基本就是这段代码里 new 了线程没走包装方法。第二个是AOP注解的方法内部又调了new Thread极端情况还会出现两个线程 traceId 一致那就不是丢失而是复用了。第三个是跨服务调用时网关把 header 名改了或滤掉了看下游服务的 access log 里有没有X-Trace-Id。5.2 让 traceId 在 ES 里可聚合日志进 ES 的时候如果走 Logstash要在 filter 里加上filter { mutate { add_field { [metadata][traceId] %{[traceId]} } } }简化写法是在 filebeat 配置里直接把 log 里的 traceId 捕获成独立字段- type: log json.keys_under_root: true fields: traceId: %{traceId}注意这种方式只适用于日志本身已经 JSON 化的场景Logback 配LogstashEncoder后输出如{traceId:..., message:...}ES 里才能做到精确聚合。文本日志里抓 traceId 只能靠 Kibana 的 grok parser性能和准确度都差一截。5.3 前端链路快速定位三板斧顺着错误时间查用户请求入口从入口进程的日志里拉出当时正在处理的 traceId 列表通常取最近 N 条即可grep 下午 14: 23 app-8081.log | awk {print $6} | sort | uniq -c | sort -rn | head。拿到疑似 traceId 后在所有服务的日志目录执行grep -r $traceId logs/。找到具体某一次报错后grep $traceId 具体错误日志 -A 30拉出完整堆栈上下文。定位流程不复杂难的是养成保留 traceId 的习惯所有告警通知里带上 traceId所有异常日志的 message 第一行输出 scan traceId排查的时候就能跳过日志文件大海捞针的环节直接锁定问题现场。提示不要依赖ThreadLocal变量来替换 MDCMDC 的特性和日志框架天然绑定换成ThreadLocal意味着日志 pattern 层面完全失去自动输出能力维护成本反而变高。本文还有配套的精品资源点击获取