TLog：十分钟快速接入的分布式日志标记追踪方案

在日常的微服务系统开发与维护中，你是否遇到过这样的困扰？一个请求经过多个服务后，如何快速定位问题？分散在各处的日志如何串联起来形成完整的调用链？为了解决这些问题，一个轻量级的解决方案应运而生。今天介绍的 TLog 就是一个专门为此设计的分布式日志标记追踪神器，它承诺十分钟就能完成接入，并且非常易用。

TLog简介

TLog 通过对日志打标签来完成企业级微服务的日志追踪。它本身并不收集日志，使用方式简单，核心能力是生成全局唯一的追踪码。除了基本的追踪码，TLog 还支持在日志中自动追加 SpanId 以及上下游服务信息等标签，极大地增强了日志的可读性和排查效率。

它的设计哲学是追求用户友好，提供了完全零侵入式的接入方式。它能自动探测项目中使用的 RPC 框架和日志框架，通过字节码注入技术，在系统层面完成日志标签的追加，开发者几乎感知不到它的存在。

在兼容性方面，TLog 做得相当不错，它适配了市面上主流的 RPC 框架，包括 Dubbo、Dubbox 以及 Spring Cloud 的 OpenFeign。为了满足不同场景的需求，TLog 提供了三种接入模式：Javaagent 方式、字节码注入方式以及日志框架适配方式。无论选择哪种方式，TLog 都保证了极低的性能损耗。更值得一提的是，即使在业务异步线程、线程池、日志异步输出等复杂场景下，TLog 也能保证日志追踪的连续性不中断。

项目特性

1. 轻量级追踪：通过对日志打标签完成轻量级微服务日志追踪，无需引入沉重的日志收集组件。
2. 多模式接入：提供三种接入方式：Javaagent 完全无侵入接入、字节码一行代码接入、基于配置文件的接入，总有一种适合你的项目。
3. 日志框架全覆盖：支持常见的 Log4j、Log4j2、Logback 三大日志框架，并提供自动检测功能，完成无缝适配。
4. 网关支持：兼容 Spring Cloud Gateway 和 Soul 网关，确保从网关开始的请求也能被正确追踪。
5. HTTP调用标签传递：适配 HttpClient 和 OkHttp 的 HTTP 调用，实现跨服务的标签传递。
6. 任务框架集成：支持三种主流任务框架：JDK 的 TimerTask、Quartz 以及 XXL-JOB。
7. 标签模板自定义：支持日志标签的自定义模板配置，提供多个系统级埋点标签供选择，灵活应对不同业务需求。
8. 异步场景无忧：支持异步线程的追踪，包括线程池、多级异步线程等复杂场景，追踪链路不会丢失。
9. 性能优异：几乎无性能损耗，经过压测，性能损耗仅在 0.01% 左右，保证了系统的快速与稳定。

安装TLog

TLog 针对 Spring Boot 和 Spring Native 环境提供了两种不同的依赖包。只需引入一个包，必要的依赖会自动传递进来。

Spring Boot 依赖

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-all-spring-boot-starter</artifactId>
    <version>1.3.4</version>
</dependency>

Spring Native 依赖

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-all</artifactId>
    <version>1.3.4</version>
</dependency>

日志框架适配方式(举例Log4j框架适配器)

不同的日志框架和同步/异步场景，配置方式略有不同。

同步日志：只需要把 layout 的实现类替换成 TLog 提供的即可。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration>
<appender name="stdout" class="org.apache.log4j.ConsoleAppender">
<!--替换成AspectLog4jPatternLayout-->
<layout class="com.yomahub.tlog.core.enhance.log4j.AspectLog4jPatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} [%p] %m  >> %c:%L%n"/>
</layout>
</appender>
<appender name="fileout" class="org.apache.log4j.DailyRollingFileAppender">
<param name="File" value="./logs/test.log"/>
<!--替换成AspectLog4jPatternLayout-->
<layout class="com.yomahub.tlog.core.enhance.log4j.AspectLog4jPatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} [%p] %m  >> %c:%L%n"/>
</layout>
</appender>
<root>
<priority value="info" />
<appender-ref ref="stdout"/>
<appender-ref ref="fileout"/>
</root>
</log4j:configuration>

异步日志：只需要把 appender 的实现类替换成 TLog 提供的异步增强类。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration>
<appender name="stdout" class="org.apache.log4j.ConsoleAppender">
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} [%p] %m  >> %c:%L%n"/>
</layout>
</appender>
<appender name="fileout" class="org.apache.log4j.DailyRollingFileAppender">
<param name="File" value="./logs/log4j-dubbo-provider.log"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} [%p] %m  >> %c:%L%n"/>
</layout>
</appender>

<!--这里替换成AspectLog4jAsyncAppender-->
<appender name="asyncFileout" class="com.yomahub.tlog.core.enhance.log4j.async.AspectLog4jAsyncAppender">
<appender-ref ref="fileout"/>
</appender>

<root>
<priority value="info" />
<appender-ref ref="stdout"/>
<appender-ref ref="asyncFileout"/>
</root>
</log4j:configuration>

任务框架支持(举例XXL-JOB框架)

从 1.3.0 版本开始，TLog 对流行的分布式任务调度框架 XXL-JOB 提供了支持。

在 Spring Boot 环境下，你无需做任何额外改动，只需引入 TLog 的依赖包即可自动生效。

而在 Spring Native 环境下，你需要在配置中额外声明一行 Bean：

<bean class="com.yomahub.tlog.springboot.lifecircle.TLogXxljobEnhanceInit"/>

TLog架构图

理解了 TLog 的功能特性，再来看一下它的核心架构，就能明白它是如何工作的。

如上图所示，TLog 的上下文管理器是整个系统的枢纽。它接收来自上游过滤器（如 Dubbo Filter、Feign Filter、Web Interceptor）以及自定义标签扫描器的输入。然后，管理器会通过 Javaagent 探针或字节码注入器，将上下文信息分发给具体的日志框架适配器（Log4j、Logback、Log4j2）。最终，当应用通过 log.info()、log.warn() 等方法打印日志时，就会自动带上完整的追踪标签。这种设计巧妙地解耦了业务代码、RPC框架和日志框架，实现了低侵入和高扩展性。

如果你想深入了解如何在企业级项目中落地 分布式系统 的监控与追踪方案，欢迎在 云栈社区 与其他开发者交流探讨。

开源地址：https://gitee.com/dromara/TLog