How TLog Enables Zero‑Intrusion Log Tracing for Microservices

Background

With the rise of microservices, many companies split systems into numerous services, making log correlation across business chains difficult. While distributed tracing tools like SkyWalking or Pinpoint are non‑intrusive, they require setup costs, so this article presents TLog, a simple, almost zero‑intrusion log tracing framework suitable for small‑to‑medium companies.

TLog Overview

TLog automatically tags logs and generates a traceId that spans the entire microservice chain, allowing rapid request tracing via the traceId. It enhances existing logs without collecting them, binding trace information to printed logs. It is recommended to use TLog together with a log‑collection solution; if a full distributed tracing system is already in place, TLog is unnecessary.

Example: ELK combined with TLog quickly locates request processing chains.

TLog Integration

1. Integration Steps

1.1 Add Dependency

<code>&lt;dependency&gt;
    &lt;groupId&gt;com.yomahub&lt;/groupId&gt;
    &lt;artifactId&gt;tlog-all-spring-boot-starter&lt;/artifactId&gt;
    &lt;version&gt;1.5.0&lt;/version&gt;
&lt;/dependency&gt;</code>

1.2 Replace Logback Configuration

Configuration is now complete.

1.3 Test

The logger obtained via SLF4J prints logs through Logback, showing a traceId such as 11794076298070144 that can be used to search the entire request chain.

2. TLog Integration Methods

TLog offers three integration approaches:

JavaAgent

Bytecode Injection

Log Framework Adapter

The article’s example uses the Log Framework Adapter for Logback, but TLog also supports Log4j and Log4j2. JavaAgent and bytecode injection have less code intrusion but only support Spring Boot and lack MDC and async log features, so the adapter method is recommended for full functionality.

Project environment compatibility comparison:

Core Principles of TLog

1. Log Tags

TLog tags logs with fields such as preApp, preHost, preIp, currIp, traceId, spanId. By default, only spanId and traceId are output according to the labelPattern.

You can customize the tag format via the Spring Boot property, e.g.:

<code>tlog.pattern=[$preApp][$preIp][$spanId][$traceId]</code>

2. TLogContext

TLogContext uses TransmittableThreadLocal to store traceId, preApp, etc., making them accessible throughout the call chain.

3. TLogRPCHandler

This component extracts trace information from incoming requests, sets it into TLogContext and MDC, and generates log tags.

Third‑Party Framework Adaptations

TraceId propagation is supported for asynchronous threads, cross‑service calls, and MQ scenarios.

1. Asynchronous Threads

1.1 General Threads

New Thread creation automatically carries traceId.

Result shows successful traceId transmission.

1.2 Thread Pools

Thread pools also support traceId propagation, but tasks should be wrapped with TLogInheritableTask to avoid data leakage.

<code>ThreadPoolExecutor pool =
        new ThreadPoolExecutor(1, 2, 1, TimeUnit.SECONDS, new LinkedBlockingQueue<>(10));
pool.execute(new TLogInheritableTask() {
    @Override
    public void runTask() {
        logger.info("异步执行");
    }
});</code>

A simplified approach is to use TLogThreadPoolExecutor which automatically wraps tasks.

<code>ThreadPoolExecutor pool =
        new TLogThreadPoolExecutor(1, 2, 1, TimeUnit.SECONDS, new LinkedBlockingQueue<>(10));
pool.execute(() -> logger.info("异步执行"));</code>

2. RPC Framework Support

TLog integrates with Dubbo, Dubbox, and OpenFeign without additional configuration.

2.1 Dubbo/Dubbox

Via SPI‑based Filter, traceId is added to request headers and extracted on the provider side.

2.2 OpenFeign

Implemented through Feign's RequestInterceptor, adding traceId to request headers.

3. HTTP Client Support

Supported clients include HttpClient, OkHttp, hutool‑http, RestTemplate, and Forest; they all propagate traceId via request headers.

4. Spring Cloud Gateway Support

Adapted via a GlobalFilter that extracts traceId from incoming headers.

5. MQ Support

Messages are wrapped in TLogMqWrapBean to carry traceId.

<code>TLogMqWrapBean&lt;BizBean&gt; tLogMqWrap = new TLogMqWrapBean(bizBean);
mqClient.send(tLogMqWrap);
</code>

On consumption, TLogMqConsumerProcessor extracts the context.

<code>TLogMqConsumerProcessor.process(tLogMqWrapBean, new TLogMqRunner&lt;BizBean&gt;() {
    @Override
    public void mqConsume(BizBean o) {
        // business logic
    }
});
</code>

6. Task Framework Support

Supported task frameworks: JDK Timer, Quartz, spring‑scheduled, and XXL‑JOB. Timer tasks need wrapping with TLogTimerTask , Quartz jobs with TLogQuartzJobBean , while spring‑scheduled and XXL‑JOB work out‑of‑the‑box.

Conclusion

TLog provides lightweight, near‑zero‑overhead log tracing for microservices, offering three integration methods, support for major logging frameworks, RPC and HTTP clients, gateways, MQ, and various task schedulers, with customizable tag templates and minimal performance impact.