instrumentation

brave-instrumentation

This module a redo of all major instrumentation libraries since Brave 3. Artifacts have the naming convention "brave-instrumentation-XXX": for example, the directory "servlet" includes the artifact "brave-instrumentation-servlet".

Here's a brief overview of what's packaged here:

• dubbo-rpc - Tracing filter for RPC providers and consumers in Dubbo
• grpc - Tracing client and server interceptors for grpc
• httpasyncclient - Tracing decorator for Apache HttpClient 4.0+
• httpclient - Tracing decorator for Apache HttpClient 4.3+
• jaxrs2 - Client tracing filter and span customizing resource filter for JAX-RS 2.x
• jersey-server - Tracing and span customizing application event listeners for Jersey Server.
• jms - Tracing decorators for JMS 1.1-2.01 producers, consumers and listeners.
• kafka-clients - Tracing decorators for Kafka 0.11+ producers and consumers.
• kafka-streams - Tracing decorator for Kafka Streams 2.0+ clients.
• mysql - Tracing MySQL statement interceptor
• mysql6 - Tracing MySQL v6 statement interceptor
• mysql8 - Tracing MySQL v8 statement interceptor
• netty-codec-http - Tracing handler for Netty 4.x http servers
• okhttp3 - Tracing decorators for OkHttp 3.x
• p6spy - Tracing event listener for P6Spy (a proxy for calls to your JDBC driver)
• servlet - Tracing filter for Servlet 2.5+ (including Async)
• sparkjava - Tracing filters and exception handlers for SparkJava
• spring-rabbit - Tracing MessagePostProcessor and ListenerAdvice for Spring Rabbit
• spring-web - Tracing interceptor for Spring RestTemplate
• spring-webmvc - Tracing filter and span customizing interceptors for Spring WebMVC
• vertx-web - Tracing routing context handler for Vert.x Web

Here are other tools we provide for configuring or testing instrumentation:

• http - HttpTracing that allows portable configuration of http instrumentation
• http-tests - Interop test suit that all http client and server instrumentation must pass
• spring-beans - This allows you to setup tracing with XML instead of custom code.
• benchmarks - JMH microbenchmarks that measure instrumentation overhead

Configuration

Log integration

You may want to put trace IDs into your log files, or change thread local behavior. Look at our context libraries, for integration with tools such as SLF4J.

XML Configuration

If you are trying to trace legacy applications, you may be interested in Spring XML Configuration. This allows you to setup tracing without any custom code.

Custom configuration

When re-using trace instrumentation, you typically do not need to write any code. However, you can customize data and sampling policy through common types. The HttpTracing type configures all libraries the same way.

Ex.

apache = TracingHttpClientBuilder.create(httpTracing.clientOf("s3"));
okhttp = TracingCallFactory.create(httpTracing.clientOf("sqs"), new OkHttpClient());

Below introduces common configuration. See the http instrumentation docs for more.

Span Data

Naming and tags are configurable in a library-agnostic way. For example, to change the span and tag naming policy for clients, you can do this:

httpTracing = httpTracing.toBuilder()
    .clientParser(new HttpClientParser() {
      @Override
      public <Req> void request(HttpAdapter<Req, ?> adapter, Req req, SpanCustomizer customizer) {
        customizer.name(adapter.method(req).toLowerCase() + " " + adapter.path(req));
        customizer.tag(TraceKeys.HTTP_URL, adapter.url(req)); // the whole url, not just the path
      }
    })
    .build();

Request-based Sampling

Which requests to start traces for is configurable in a library-agnostic way. You can change the sampling policy by specifying it in the HttpTracing component. Here's an example which doesn't start new traces for requests to favicon (which many browsers automatically fetch).

httpTracing = httpTracing.toBuilder()
    .serverSampler(new HttpSampler() {
       @Override public <Req> Boolean trySample(HttpAdapter<Req, ?> adapter, Req request) {
         if (adapter.path(request).startsWith("/favicon")) return false;
         return null; // defer decision to probabilistic on trace ID
       }
     })
    .build();

Writing new instrumentation

We worked very hard to make writing new instrumentation easy and efficient. Most of our built-in instrumentation are 50-100 lines of code, yet allow flexible configuration of tags and sampling policy.

If you need to write new http instrumentation, check our docs, as this shows how to write it in a way that is least effort for you and easy for others to configure. For example, we have a standard test suite you can use to make sure things interop, and standard configuration works.

If you need to do something not http, you'll want to use our tracer library. If you are in this position, you may find our feature tests helpful.

Regardless, you may need support along the way. Please reach out on gitter, as there's usually others around to help.