分布式日志排查太头疼？TLog 让你一眼看穿请求链路！

原创于 2025-10-11 14:13:47 发布 · 630 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#分布式 #tlog

框架篇专栏收录该内容

41 篇文章

订阅专栏

01 引言

你是否曾经历过这样的深夜？告警短信突然响起，线上订单莫名失败。你焦头烂额地登录一台台服务器，在成百上千行的日志文件里反复 grep、awk，试图拼凑出一个完整请求的蛛丝马迹。

微服务之间环环相扣，一个请求穿越网关、订单、库存、支付……日志碎片散落在各处，就像一幅拼图被扔进了不同房间，排查过程宛如大海捞针。

这，正是分布式系统日志排查的常态——昂贵、低效且令人心力交瘁。但今天，这一切将成为过去。我们将为你介绍一款来自Dromara社区的神器——TLog。它不记录日志，却能让日志自己“说话”，为每一个请求装上全局“追踪器”，真正实现一眼看穿分布式请求链路，让问题定位变得前所未有的简单和清晰。

02 简介

TLog 是一个轻量级的分布式日志标记追踪框架，它并不重复造轮子去记录日志，而是专注于一件事：自动为你的每一次请求生成一个唯一的追踪ID（TraceId），并让这个ID在整个调用链路中无缝传递。

支持log4j，log4j2，logback三大日志框架，支持dubbo，dubbox，springcloud三大RPC框架。

简单来说，TLog 的核心思想是：

自动打标：在请求入口处（如HTTP请求、定时任务、消息队列消费者），TLog会自动生成一个全局唯一的TraceId。
无缝传递：无论你的服务之间通过何种方式调用（如Feign、Dubbo、OpenFeign等），TLog都能透明地将TraceId传递到下游服务。
日志关联：在每个服务的日志输出中，TLog会自动将这个TraceId打印到日志内容中。

最终效果是，你只需要在日志平台（如ELK、Graylog、Splunk）上搜索这个TraceId，就能立刻拉取出这个请求流经所有服务的全部日志，请求的完整生命周期一目了然。

Gitee地址：https://gitee.com/dromara/TLog

官网地址：https://tlog.yomahub.com/

03 最佳实践

3.1 接入方式选择

官方提供了三种接入方式：

Javaagent方式
字节码注入方式
日志框架适配方式

前两种的接入方式虽然简单，代码侵入性小。但是不支持MDC和异步日志。而且只支持springboot项目。官方推荐第三中接入方式：

3.2 Maven依赖引入

官方提供全量和按需引入的方式，如果你对项目不熟悉后果者项目框架使用混乱，可以选择全量引入的方式。

这里演示选择使用按需引入的方式：

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-web-spring-boot-starter</artifactId>
    <version>1.5.2</version>
</dependency>

3.3 `logback`适配

就是将encoder的实现类ch.qos.logback.classic.encoder.PatternLayoutEncoder，换成com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder就好了。

3.4 测试案例

@Slf4j
@RestController
public class TlogTestController {

    @RequestMapping("/tlog")
    public void testTlog() {
        log.info(">>>>>>测试tlog");
        log.info(">>>>>>测试tlog 有没有加 traceId");
        log.info(">>>>>>测试tlog 有没有加 spanId");
    }
}

3.5 Tlog使用前后对比

使用前

使用后

其中第一个参数是spanId，第二个是traceId

**spanId**的生成规则，如图：

04 扩展功能

上面的案例已经完成了基本的接入，该框架还提供了扩展功能。

4.1 自动打印调用参数和时间

只需要一行配置：

# 不配默认为false
tlog.enable-invoke-time-print=true

效果

4.2 自定义`TraceId`生成器

TLog默认采用snowflake算法生成traceId，也可以自定义。只需要继承TLogIdGenerator类即可。

public class MytraceIdGenerator extends TLogIdGenerator {

    @Override
    public String generateTraceId() {
        return UUID.randomUUID().toString();
    }
}

然后在springboot的配置类里声明：

tlog.id-generator=com.simonking.boot.log.config.MytraceIdGenerator

结果就变成了UUID了：

05 小结

此外，Tlog还对常用的工具类做了支持，如：httpclient、hutool-http、forest等。

在分布式系统复杂度日益增长的今天，可观测性不再是可选项，而是必需品。TLog以其简单、高效、非侵入的设计哲学，精准地解决了日志追踪这一核心痛点，为开发者提供了一把快速定位线上问题的“金钥匙”。