TLog: A Lightweight Log Tracing Framework for Java Microservices

With the rise of microservices, locating logs across many service nodes becomes difficult; TLog offers a simple, almost zero‑intrusion solution that automatically adds traceId tags to logs, allowing developers to quickly pinpoint request flows.

TLog Overview

TLog enhances existing logs by attaching a traceId that spans the entire microservice chain. It does not collect logs itself; it merely enriches the logs you already output.

Integration Steps

1. Add Dependency

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

2. Replace Logback Configuration

After updating the Logback config, the integration is complete.

3. Test

Using SLF4J's LoggerFactory , the generated log contains a traceId such as 11794076298070144 , which can be used to search the whole request chain.

Three Integration Methods

JavaAgent (minimal intrusion, Spring Boot only)

Bytecode injection (minimal intrusion, Spring Boot only)

Log framework adapter (supports Logback, Log4j, Log4j2; most flexible)

Core Concepts

Log Tags

Default tags include preApp , preHost , preIp , currIp , traceId , and spanId . The default pattern outputs only spanId and traceId , but it can be customized, e.g.:

tlog.pattern=[$preApp][$preIp][$spanId][$traceId]

TLogContext

TLogContext stores trace information in a TransmittableThreadLocal , making it accessible throughout the call chain.

TLogRPCHandler

This component extracts trace data from incoming requests, sets it into TLogContext and MDC, and generates the log tag according to the configured pattern.

Third‑Party Framework Adaptations

Asynchronous Threads

Direct new Thread creation is automatically supported. For thread pools, wrap tasks with TLogInheritableTask or use TLogThreadPoolExecutor to avoid manual wrapping.

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

RPC Frameworks

TLog integrates with Dubbo/Dubbox via SPI filters and with OpenFeign via a RequestInterceptor , propagating traceId in request headers.

HTTP Clients

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

Gateways

Both Spring Cloud Gateway and Soul Gateway are supported through a global filter that extracts trace information.

Message Queues

Wrap messages in TLogMqWrapBean before sending; the consumer processes them via TLogMqConsumerProcessor , preserving traceId across MQ boundaries.

Task Schedulers

Supported task frameworks: JDK Timer (via TLogTimerTask ), Quartz (via TLogQuartzJobBean ), spring‑scheduled, and XXL‑JOB (no extra config needed).

Summary

All adaptations follow the same principle: before a request or task is dispatched, TLog extracts the current traceId from TLogContext , injects it into the outgoing payload, and the receiver restores it into its own context, enabling seamless end‑to‑end tracing.

For frameworks not yet supported, developers can follow the demonstrated adaptation pattern.

Conclusion

TLog provides lightweight, near‑zero‑overhead log tracing suitable for small‑to‑medium enterprises, supporting multiple logging frameworks, RPCs, gateways, HTTP clients, MQs, and task schedulers, with customizable tag templates and minimal performance impact.