Currently, there are two (overloaded) methods of the class TracerFactory which evaluate a given XML trace-config: readConfiguration(File configFile) and readConfiguration(InputStream inputStream). The latter one is well suited for configurations which are given as resources on the classpath. Both methods are validating their input against a XML schema which is referenced in the first section. The overall structure of the XML configuration is divided into four parts: the pool of named tracers, the default tracer (which must always be a NullTracer), a map which maps threads on named tracers and a queue of uniform tracers. These parts will be discussed in the sections 2-5.

The applied XML schema is attached to the classpath as resource, see TraceConfigSchema.

This section is mandatory for historical reasons, but its content might be empty. The uniquely named tracers together with their individual configurations belong into this part. A complete FileTracer configuration is shown below:

The specification of the Limit and the Context is optional. If no Limit is given the file size of the accompanying log file is unbounded. If no Context is specified you must initialise a Context with explicit values for DebugLevel and Online by applying initCurrentTracingContext(int debugLevel, boolean online) otherwise calling initCurrentTracingContext() is sufficient. A Context is always associated with a certain thread. A NetTracer needs no log directory but a listener address, see below:

The specification of a DefaultTracer is optional. If no DefaultTracer is given the JDKLoggingRouter is used. The default tracer is returned by the methods getCurrentPoolTracer() or getCurrentQueueTracer() of the class TracerFactory if no specified tracer can be found for the current thread or - in case of a QueueTracer - if the queue tracers are disabled. Only NullTracers are allowed, e.g.:

Within this section you can map threads on pooled tracers so that you can easily request a tracer for the current thread by calling getCurrentPoolTracer() or getTracer(Thread thread). See, for example, the configuration below:

Given three pooled tracers, the main- and the TestThread-0-threads are mapped on the TestTracer-0, the TestThread-1-thread is mapped on the TestTracer-0 and the TestThread-2-thread is mapped on the TestTracer-2. E.g. calling getCurrentPoolTracer() from the main-thread or from TestThread-0 gives you the TestTracer-0.

A blocking queue containing uniform tracers can be configured within this segment. By invoking takeTracer() you receive the next available tracer from the queue or the invocation blocks if the queue is empty because all tracers are currently allocated. This approach might be useful for debugging code running within an application server serving web requests. QueueTracers should not be used for long running tasks.