Introduction to TLog: Enterprise‑Level Microservice Log Tracing and Integration Guide

Introduction to TLog

TLog provides enterprise‑grade microservice log tracing by tagging logs with a globally unique trace ID, optional SpanId, and upstream/downstream service information. It operates without collecting log content, offers a zero‑intrusion integration approach, and automatically injects bytecode to support the RPC and logging frameworks used in the project.

Project Features

1. Lightweight log tagging for microservice tracing.

2. Three integration modes: Java‑agent (completely non‑intrusive), bytecode injection with a single line of code, and configuration‑file‑based integration.

3. Automatic adaptation for the three major logging frameworks: Log4j, Log4j2, and Logback.

4. Support for Spring Cloud Gateway and Soul gateway.

5. HTTP call tag propagation for HttpClient and OkHttp.

6. Compatibility with common task frameworks: JDK TimerTask, Quartz, and XXL‑JOB.

7. Customizable tag templates and multiple system‑level embedded tags.

8. Asynchronous thread tracing, including thread‑pool and multi‑level async scenarios.

9. Near‑zero performance impact (≈0.01% overhead after stress testing).

Installation

For Spring Boot:

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

For Spring Native:

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

Log Framework Adaptation (Log4j Example)

Synchronous logging: Replace the layout implementation with com.yomahub.tlog.core.enhance.log4j.AspectLog4jPatternLayout .

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration>
  <appender name="stdout" class="org.apache.log4j.ConsoleAppender">
    <!-- replace with 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"/>
    <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>

Asynchronous logging: Replace the appender class with com.yomahub.tlog.core.enhance.log4j.async.AspectLog4jAsyncAppender .

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration>
  ... (same appender definitions as above) ...
  <!-- replace with 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>

Task Framework Support (XXL‑JOB Example)

Since version 1.3.0, TLog supports the open‑source XXL‑JOB framework. In a Spring Boot environment no additional changes are required—just add the dependency. In a Spring Native environment add the following bean definition:

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

Architecture Diagram

The following image illustrates the overall TLog architecture and its integration points with various frameworks:

Open‑Source Repository

The project is hosted on Gitee: https://gitee.com/dromara/TLog

Additional Notes

The article concludes with promotional content encouraging readers to follow the public account for more architecture‑related articles and to reply with specific keywords to receive learning materials.