# SOFATracer: distributed call tracing written to local logs > SOFATracer is a Java component that records the network calls in a request chain under a unified traceId and writes them to local disk as logs, based on the OpenTracing specification, so a fault can be found by reading logs rather than by querying a tracing backend. It suits a large service estate where the log pipeline already exists, and it asks for instrumentation at the component level. **sofastack/sofa-tracer** — SOFATracer is a component for the distributed system call trace. And through a unified traceId logging the logs of various network calls in the invoking link. These logs can be used for quick discovery of faults, service governance, etc. - Repository: https://github.com/sofastack/sofa-tracer - Stars: 1,127 · Forks: 380 - Language: Java - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/sofastack-sofa-tracer ## What the component does SOFATracer is a component for distributed system call tracing that records the state of the various network calls in an invocation chain as logs through a unified traceId, with the stated purpose of making network calls visible. The logs can then be used for quick discovery of faults and for service governance. The mechanism is worth stating precisely, because it is what distinguishes this from a tracing system in the usual sense. There is no collector and no trace database. The trace is written out as log lines on the machine where the call happened, and the correlation happens because every line carries the same trace identifier, so a search across the central log system for that identifier reconstructs the chain. That design has a real appeal in a large estate, because the infrastructure it depends on already exists. Every service already ships logs somewhere, and that somewhere is where the trace ends up. Nothing new has to be operated, and the log retention policy is the retention policy you already have. The project came out of Ant Financial, which built the solution on the OpenTracing specification to analyse the online call behaviour and the call performance of its applications, and it is part of the SOFA stack, with a Spring Boot starter module among the repository directories and the topics list including the starter name. The licence is Apache-2.0, the last push to the repository was on 2026-06-07, and the most recent tagged releases are v3.1.1 from April 2021 and v3.1.0 from January 2021. ## The background: the problem it was built for The background section explains the motivation in more detail than most projects offer, and it is worth reading because the constraints it describes are the reason the design looks the way it does. The argument runs like this. In a modern architecture everything is built on services, and those services are deployed as large distributed clusters. The applications are then built on different software modules, which may have been developed by different teams, may be implemented in different programming languages, and may be deployed across thousands of servers. What is needed is a component that helps understand the online call behaviour of each application and analyse the performance of remote calls. Every element of that description is a constraint on the design. Different teams means the instrumentation has to be something each team can add without changing their code's structure. Different languages means the trace identifier has to travel over the wire in a language neutral way, which is what the OpenTracing specification provides. Thousands of servers means the volume has to be manageable, which is what the sampling and the statistics logging are for. That last point is the one that shapes the whole component. A trace record for every call on every server in a large cluster is a lot of data, and the answer in this design is not to drop the records but to change what is written, a summary record for every call and a statistics record on an interval, plus a configurable sampling strategy that the samples directory demonstrates. ## OpenTracing as the base, extended The first feature is the tracing model itself, and the description is careful about the relationship to the specification. The solution is based on the OpenTracing specification and extends its capabilities. Different frameworks or components can implement on top of it, providing tracing by instrumenting each component with points in the code. So the API is the standard one, which matters more than it might sound. The trace identifier and the span identifier are concepts from the specification, and a service written against any OpenTracing implementation can participate in a trace that SOFATracer recorded. The extension is in the delivery half, the logging and the reporting, not in the vocabulary. The second feature is the asynchronous disk logging, and it is the part with the most implementation detail in the README. It is built on the Disruptor, a high performance lock free circular queue, to provide the ability to print logs to the local disk asynchronously. A framework or component that integrates it can customise the output format of the log file while the writing is asynchronous. There are two similar kinds of log printing. The summary log writes a record to disk for every call. The statistics log collects and writes out statistics at intervals. The division matters. A call that fails is in the summary log immediately, and a call that is slow is in the statistics log without having written a record for every other call. A team reading a trace after an incident gets the per call detail, and a team watching a service gets the aggregate, and neither pays for the other. ## Retention, and the pipeline you already run The third feature is retention, and it is a small feature that pays for itself. The asynchronously written SOFATracer logs support self-clearing and rolling. They can be cleared by day, and they can be rolled by hour or by day. That is the operational counterpart of writing the trace to disk instead of to a collector. A log file that is never cleaned is a disk that fills, and a distributed trace written from thousands of servers needs a retention rule that is local, per machine, and cheap. A daily clear with hourly rolling gives you a window of recent history on the machine and bounds the disk use, and the existing log shipper then takes what it needs. The two log types interact with this nicely. The statistics log is the one you leave running because it is small and it carries the aggregate, and the summary log is the one you keep for a shorter window because it is per call. The fifth feature is the interface, and it is the piece that decides whether anyone looks at the data. SOFATracer can report the tracing data remotely to Zipkin for display of the distributed trace, so the same trace that is on disk for the log search can also be visualised as a span diagram in a tool built for that purpose. ## The SLF4J MDC integration, and the configuration The fourth feature is the one that makes the trace visible in the logs you already read. SLF4J provides the MDC, the mapped diagnostic context, which supports user defined and modified log output formats and content. SOFATracer integrates the SLF4J MDC function so that a user can, with a small change to the log configuration file alone, output the current tracer context's tracerId and spanId. The wording is precise and worth repeating, because it describes the intended workflow. You do not change the logging code in your service. You add a pattern to the log configuration that prints the context values, and every line your service writes then carries the trace identifier. That is a much lower barrier than a tracing agent or a per service code change, and it means the trace appears in the log stream next to everything else, so a developer debugging with logs sees the chain without switching tools. The sixth feature is unified configuration, described as rich configuration in the configuration file so that an application can be tuned to its own needs. Combined with the sampling strategy that the samples demonstrate, this is where you decide how much trace a service produces and where it goes. ## The project layout, the samples and the build requirements The repository is a multi-module Maven build, and the module names describe the layers. There is a tracer-core module, a tracer-extensions module for the optional pieces, a tracer-all module that aggregates the pieces for a single dependency, a tracer-sofa-boot-starter for the Spring Boot integration, a tracer-test module, and a tracer-plugins directory. The root also has a parent pom, a licence file, a header file used for the licence headers, a formatter configuration, a check format script and a codecov configuration. The samples are the most useful part of the repository for a reader, and the README lists them as separate example projects in a directory. They cover a Spring MVC service writing logs to disk, the same with remote reporting to Zipkin, a SOFA RPC service, a sample printing the trace identifier through the SLF4J logging interface, a DataSource sample, an HttpClient sample, a sample showing the sampling strategy, a Spring Cloud integration, a Dubbo integration, and a RestTemplate sample. Between them they show the instrumentation points that matter, the HTTP clients and the data source, the RPC frameworks, the two logging paths and the sampling behaviour, and the Spring Cloud and Dubbo integrations are the two that matter for a Java microservice estate. The build requirements are where the age of the project shows. The compilation environment requires JDK 7 or JDK 8, and Maven 3.2.5 or later. There is also a contributing guide to read before sending code, and the build badge and the coverage badge are the two signals the README offers about the health of the tree, with the last push to the repository on 2026-06-07 and the most recent release from 2021, which is a combination worth holding in mind before you plan an adoption. ## Conclusion Adopt SOFATracer if your estate already runs a central log system and you want per call visibility across services without standing up a tracing collector and storage tier, because the component writes the trace to disk in the same format as everything else your services log. Do not adopt it for a new greenfield service if you can pick a modern tracing stack, since the released versions here date from 2021 and the project is built around an OpenTracing based API. Before you plan a rollout, check the build requirements, because the documented compile environment is JDK 7 or JDK 8, which is the clearest signal of how the codebase has aged. ## FAQ ### What is SOFATracer? It is a component for distributed system call tracing that records the various network calls in an invocation chain as logs through a unified traceId, so that the behaviour of a call chain can be understood. The logs can be used for quick discovery of faults and for service governance. ### How does SOFATracer write its trace data? Asynchronously to local disk, using the Disruptor, a high performance lock free circular queue. It provides two kinds of log, a summary log that writes a record for every call, and a statistics log that writes aggregated output at intervals, and the output format can be customised by the integrating framework or component. ### What can I do with the SOFATracer logs? They are ordinary logs on the local disk, so they can be searched in whatever log system the service already ships to, and they support self-clearing and rolling, by day for clearing and by hour or day for rolling. The tracing data can also be reported remotely to Zipkin for display of the distributed trace. ### How do I add the trace identifier to my existing logs? Through the SLF4J MDC integration. SOFATracer integrates with the mapped diagnostic context so that, with a small change to the log configuration file alone, you can output the current tracer context's tracerId and spanId on every line the service writes. ## Sources - [Issues](https://github.com/sofastack/sofa-tracer/issues) - [License: Apache-2.0](https://github.com/sofastack/sofa-tracer/blob/master/LICENSE) - [README](https://github.com/sofastack/sofa-tracer/blob/master/README.md) - [Releases](https://github.com/sofastack/sofa-tracer/releases) - [sofastack/sofa-tracer on GitHub](https://github.com/sofastack/sofa-tracer) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sofastack-sofa-tracer