Skip to content
Branch: master
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
benchmarks [maven-release-plugin] prepare for next development iteration Jul 16, 2019
dubbo-rpc [maven-release-plugin] prepare for next development iteration Jul 16, 2019
grpc [maven-release-plugin] prepare for next development iteration Jul 16, 2019
http-tests [maven-release-plugin] prepare for next development iteration Jul 16, 2019
http [maven-release-plugin] prepare for next development iteration Jul 16, 2019
httpasyncclient [maven-release-plugin] prepare for next development iteration Jul 16, 2019
httpclient [maven-release-plugin] prepare for next development iteration Jul 16, 2019
jaxrs2 [maven-release-plugin] prepare for next development iteration Jul 16, 2019
jersey-server [maven-release-plugin] prepare for next development iteration Jul 16, 2019
jms [maven-release-plugin] prepare for next development iteration Jul 16, 2019
kafka-clients [maven-release-plugin] prepare for next development iteration Jul 16, 2019
kafka-streams [maven-release-plugin] prepare for next development iteration Jul 16, 2019
mysql [maven-release-plugin] prepare for next development iteration Jul 16, 2019
mysql6 [maven-release-plugin] prepare for next development iteration Jul 16, 2019
mysql8 [maven-release-plugin] prepare for next development iteration Jul 16, 2019
netty-codec-http [maven-release-plugin] prepare for next development iteration Jul 16, 2019
okhttp3 [maven-release-plugin] prepare for next development iteration Jul 16, 2019
p6spy [maven-release-plugin] prepare for next development iteration Jul 16, 2019
servlet [maven-release-plugin] prepare for next development iteration Jul 16, 2019
sparkjava [maven-release-plugin] prepare for next development iteration Jul 16, 2019
spring-rabbit [maven-release-plugin] prepare for next development iteration Jul 16, 2019
spring-web [maven-release-plugin] prepare for next development iteration Jul 16, 2019
spring-webmvc [maven-release-plugin] prepare for next development iteration Jul 16, 2019
vertx-web [maven-release-plugin] prepare for next development iteration Jul 16, 2019
README.md Adds JMS 1.1/2.0 instrumentation (#764) Aug 30, 2018
pom.xml [maven-release-plugin] prepare for next development iteration Jul 16, 2019

README.md

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:

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.

You can’t perform that action at this time.