X-Trace - Client Library

This project contains the client library for generating X-Trace reports from a system. Since X-Trace uses Baggage, all metadata propagation concerns are taken care of by Baggage instrumentation. Internally, X-Trace uses pubsub for publishing reports to the X-Trace server.

Logging

The class XTrace provides a static API for interacting with X-Trace. The method XTrace.getLogger() is similar to log4j or commons logging calls such as LogFactory.getLogger(). It will return an XTraceLogger that can be used to generate reports. Typical use of this call is to create a static instance of XTraceLogger per class.

public static final XTraceLogger xtrace = XTrace.getLogger(MyClass.class);
public static final XTraceLogger xtrace = XTrace.getLogger("nameForLogger");

Once you have acquired an XTraceLogger, the log method can be used to generate and send a report. You can provide a format string to this method, using {} to escape variables. Once the replacement variables have been exhausted, the remaining varargs are appended to the report as key-value pairs.

xtrace.log("This is an X-Trace logging statement");
xtrace.log("My name is {}", "Jon");
xtrace.log("Another log statement", "Name", "Jon");

Tasks

By default, calls to log do not do anything, and X-Trace reports are not generated. In order to generate reports, a request must be marked as a task with the call to the static XTrace.startTask() method.

XTrace.startTask(true);

This generates a random task ID and stores it in Baggage. When a call to XTrace.log is encountered, the Baggage is checked for a task ID. If a task ID is present, a report is generated and the task ID attached. Thus, X-Trace does not log events most of the time, unless a request is explicitly given a task ID.

Configuration

X-Trace logging can be configured to exclude reports generated by loggers by name. Set xtrace.client.reporting.default to true or false to turn logging classes on or off by default, then override individual logging classes with the xtrace.client.reporting.enabled and xtrace.client.reporting.disabled properties. If xtrace.client.reporting.on is set to false, X-Trace will be disabled entirely.

Discovery Mode

For convenience, X-Trace has a "discovery mode". In this mode, X-Trace log statements will be generated regardless of whether a task ID is present. If a task ID is not present, a deterministic ID will be generated based on process name, host name, and thread ID. This produces verbose logs that can be viewed on the X-Trace server, that are helpful when instrumenting a new system with Baggage to see where there might be context "leaks".

To use this mode, set xtrace.client.reporting.discoverymode to true.

X-Trace Client uses the following default configuration values:

xtrace {
    client {
        reporting {
            on                  = true      # is XTrace reporting globally enabled
            default             = true      # for a logging class, it is on or off by default
            enabled             = [ "com.example.EnabledClass",     # list of agent names for whom logging is enabled,
                                        "randomEnabledAgentName" ]      #  overriding setting in xtrace.client.reporting.default
            disabled            = [ "com.example.DisabledClass",    # list of agent names for whom logging is disabled
                                        "randomDisabledAgentName" ]     #  overriding setting in xtrace.client.reporting.default
        }
    }
}