Chapter 8. Logging and tracing

The client uses the SLF4J API, enabling users to select a particular logging implementation based on their needs. For example, users can provide the slf4j-log4j binding to select the Log4J implementation. More details on SLF4J are available from its website.

The client uses Logger names residing within the org.apache.qpid.jms hierarchy, which you can use to configure a logging implementation based on your needs.

8.1. Enabling protocol logging

When debugging, it is sometimes useful to enable additional protocol trace logging from the Qpid Proton AMQP 1.0 library. There are two ways to achieve this.

  • Set the environment variable (not the Java system property) PN_TRACE_FRM to 1. This will cause Proton to emit frame logging to the console.
  • Add the option amqp.traceFrames=true to your connection URI and configure the org.apache.qpid.jms.provider.amqp.FRAMES logger to log level TRACE. This will add a protocol tracer to Proton and include the output in your logs.

You can also configure the client to emit low-level tracing of input and output bytes. To enable this, add the option transport.traceBytes=true to your connection URI and configure the org.apache.qpid.jms.transports.netty.NettyTcpTransport logger to log level DEBUG.

8.2. Enabling distributed tracing

The client offers distributed tracing based on the Jaeger implementation of the OpenTracing standard. Use the following steps to enable tracing in your application:

Procedure

  1. Add the Jaeger client dependency to your POM file. 

    <dependency>
  <groupId>io.jaegertracing</groupId>
  <artifactId>jaeger-client</artifactId>
  <version>${jaeger-version}</version>
</dependency>

    ${jaeger-version} must be 1.0.0 or later.

  2. Add the jms.tracing option to your connection URI. Set the value to opentracing.

    Example: A connection URI with tracing enabled

    amqps://example.net?jms.tracing=opentracing

  3. Register the global tracer.

    Example: Global tracer registration

    import io.jaegertracing.Configuration;
import io.opentracing.Tracer;
import io.opentracing.util.GlobalTracer;

public class Example {
    public static void main(String[] args) {
        Tracer tracer = Configuration.fromEnv("<service-name>").getTracer();
        GlobalTracer.registerIfAbsent(tracer);

        // ...
    }
}

  4. Configure your environment for tracing.

    Example: Tracing configuration

    $ export JAEGER_SAMPLER_TYPE=const
$ export JAEGER_SAMPLER_PARAM=1
$ java -jar example.jar net.example.Example

    The configuration shown here is for demonstration purposes. For more information about Jaeger configuration, see Configuration via Environment and Jaeger Sampling.

To view the traces your application captures, use the Jaeger Getting Started to run the Jaeger infrastructure and console.