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:
- 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 - Tracing filters and a feature to automatically configure them
- mysql - Tracing MySQL statement interceptor
- 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-web - Tracing interceptor for Spring RestTemplate
- spring-webmvc - Tracing interceptor for Spring WebMVC
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
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.
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.
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.
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();
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();
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.