TLog 分布式日志追踪新手入门指南
项目概览
| 属性 | 信息 |
|---|---|
| 项目名称 | TLog |
| 组织 | Dromara |
| Stars | 3.4K+ ⭐⭐⭐ |
| Watching | 269+ |
| Forks | 767+ |
| 语言 | Java (100%) |
| Gitee 仓库 | https://gitee.com/dromara/TLog^\[1\]^ |
| 官网 | https://tlog.yomahub.com/^\[2\]^ |
| 开源协议 | MIT |
| GVP认证 | 是 |
项目简介
TLog 是一个轻量级的分布式日志标记追踪神器，10分钟即可接入，自动对日志打标签完成微服务的链路追踪。
核心价值
•零侵入设计 ：对业务代码无侵入式设计，使用简单•快速接入 ：10分钟即可接入，无需复杂配置•轻量级 ：性能损耗仅0.01%，几乎无性能影响•全链路追踪：自动为日志打标签，实现微服务链路追踪
核心功能特性
1. 日志框架支持
•✅ Log4j•✅ Log4j2•✅ Logback
2. RPC框架支持
•✅ Dubbo•✅ Dubbox•✅ Spring Cloud
3. 网关支持
•✅ Spring Cloud Gateway•✅ Soul网关
4. 特性
•✅ JavaAgent无侵入接入•✅ 字节码一行代码接入•✅ 配置文件接入•✅ HttpClient标签传递•✅ OkHttp标签传递•✅ 异步线程追踪•✅ 线程池追踪•✅ 多级异步线程追踪•✅ 三种任务框架支持（JDK TimerTask、Quartz、XXL-JOB）•✅ 自定义日志标签模板
适用场景
🌟 典型应用场景
| 场景 | 说明 |
|---|---|
| 微服务链路追踪 | 跨服务日志关联分析 |
| 分布式系统调试 | 快速定位问题来源 |
| 性能分析 | 分析请求处理时间 |
| 日志聚合 | 统一查看完整调用链 |
🎯 目标用户
•微服务架构开发者•分布式系统运维人员•需要日志追踪的开发团队•中大型互联网公司
技术架构
核心模块
go
tlog-all # 全部模块聚合tlog-core # 核心模块tlog-common # 公共模块tlog-agent # JavaAgent模块tlog-spring-boot # Spring Boot集成tlog-dubbo # Dubbo集成tlog-feign # Feign集成tlog-forest # Forest集成tlog-okhttp # OkHttp集成tlog-httpclient # HttpClient集成tlog-rest-template # RestTemplate集成tlog-xxl-job # XXL-JOB集成tlog-gateway # 网关集成接入方式
TLog提供三种接入方式：
1.JavaAgent方式 ：完全无侵入，只需添加启动参数2.字节码方式 ：一行代码接入，基于字节码增强3.配置文件方式：基于配置文件的简单接入
快速开始
1. Maven 引入
xml
<!-- 方式一：Spring Boot Starter (推荐) --><dependency> <groupId>com.yomahub</groupId> <artifactId>tlog-spring-boot-starter</artifactId> <version>1.5.0</version></dependency>
<!-- 方式二：如果使用其他框架 --><dependency> <groupId>com.yomahub</groupId> <artifactId>tlog-all</artifactId> <version>1.5.0</version></dependency>2. 配置文件
yaml
# application.ymltlog: enabled: true appname: your-app-name # 是否追踪MDC上下文 trace-mid: TID # 日志模板 log-pattern: "[{TID}] {methodName} {className}"3. Logback配置
xml
<!-- logback.xml --><appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %highlight(%-5level) %cyan(%logger{36}) - %msg%n</pattern> </encoder></appender>4. JavaAgent方式接入
bash
java -javaagent:tlog-agent.jar -jar your-app.jar5. 验证效果
启动应用后，日志将自动添加链路追踪标识：
go
2026-05-07 10:30:15.123 [http-nio-8080-exec-1] INFO c.example.Service - [TID:xxx123] Method:doSomething Class:com.example.Service - 开始处理请求2026-05-07 10:30:15.125 [http-nio-8080-exec-1] INFO c.example.Service - [TID:xxx123] Method:doSomething Class:com.example.Service - 请求处理完成性能表现
根据官方压测数据：
| 指标 | 数值 |
|---|---|
| 性能损耗 | 约0.01% |
| 内存占用 | 极小 |
| 吞吐量影响 | 可忽略 |
TLog经过严格的性能测试，确保在高并发场景下对系统性能的影响可以忽略不计。
常见问题
Q1: TLog支持哪些RPC框架？
A: 目前支持Dubbo、Dubbox、Spring Cloud生态（包括Feign、RestTemplate等）。
Q2: 如何在异步线程中保持追踪？
A: TLog自动支持线程池和多级异步场景，会自动传递链路上下文。
Q3: 如何自定义日志标签格式？
A: 通过配置文件设置log-pattern参数，支持多个系统级埋点标签。
Q4: 是否支持热更新规则？
A: 支持配置文件方式的动态更新，无需重启应用。
Q5: 如何排除不需要追踪的接口？
A: 在配置文件中添加排除路径规则即可。
学习资源
官方资源
社区支持
•项目作者：铂赛东 (bryan31)•官方公众号：关注作者公众号获取入群邀请
项目推荐指数
| 维度 | 评分 | 说明 |
|---|---|---|
| 易用性 | ⭐⭐⭐⭐⭐ | 10分钟即可接入 |
| 轻量级 | ⭐⭐⭐⭐⭐ | 性能损耗仅0.01% |
| 实用性 | ⭐⭐⭐⭐⭐ | 微服务开发必备 |
| 学习价值 | ⭐⭐⭐⭐ | 理解链路追踪原理 |
综合推荐指数 ：⭐⭐⭐⭐⭐ 强烈推荐！
对比同类产品
| 特性 | TLog | SkyWalking | Zipkin |
|---|---|---|---|
| 侵入性 | 低 | 中 | 中 |
| 性能损耗 | 0.01% | 3-5% | 5-10% |
| 配置复杂度 | 简单 | 复杂 | 中等 |
| 学习成本 | 低 | 高 | 中 |
TLog的优势在于轻量级和零侵入，适合快速集成和小型项目。
报告生成时间：2026年5月 数据来源：Gitee 官方数据 项目官网：https://tlog.yomahub.com/^\[6\]^
References
[1]: https://gitee.com/dromara/TLog
[2]: https://tlog.yomahub.com/
[3]: https://tlog.yomahub.com/
[4]: https://tlog.yomahub.com/pages/5b7bd2/
[5]: https://gitee.com/bryan31/tlog-example
[6]: https://tlog.yomahub.com/