isabella232 / java-spring-zipkin

Dependencies

The opentracing-spring-zipkin-starter simply contains the code needed to provide a Zipkin implementation of the OpenTracing's io.opentracing.Tracer interface.

For a project to be able to actually instrument a Spring stack, one or more of the purpose built starters (like io.opentracing.contrib:opentracing-spring-web-starter or io.opentracing.contrib:opentracing-spring-cloud-starter)
would also have to be included in the POM.

The opentracing-spring-zipkin-web-starter starter is convenience starter that includes both opentracing-spring-zipkin-starter and opentracing-spring-web-starter This means that by including it, simple web Spring Boot microservices include all the necessary dependencies to instrument Web requests / responses and send traces to Zipkin.

The opentracing-spring-zipkin-cloud-starter starter is convenience starter that includes both opentracing-spring-zipkin-starter and opentracing-spring-cloud-starter This means that by including it, all parts of the Spring Cloud stack supported by Opentracing will be instrumented

Configuration

<dependency>
  <groupId>io.opentracing.contrib</groupId>
  <artifactId>opentracing-spring-zipkin-web-starter</artifactId>
</dependency>

or

<dependency>
  <groupId>io.opentracing.contrib</groupId>
  <artifactId>opentracing-spring-zipkin-cloud-starter</artifactId>
</dependency>

Either dependency will ensure that Spring Boot will auto configure a Zipkin implementation of OpenTracing's Tracer when the application starts.

By default, the Zipkin server is expected to collect traces at http://localhost:9411/api/v2/spans encoded with JSON_V2. To change the default simply set the following the property:

opentracing.zipkin.http-sender.baseUrl=http://<host>:<port>

Configuration options

All the available configuration options can be seen in ZipkinConfigurationProperties. The prefix to be used for these properties is opentracing.zipkin. Furthermore, the service name is configured via the standard Spring Cloud spring.application.name property.

Beware to use the correct syntax for properties that are camel-case in ZipkinConfigurationProperties.

• For properties / yaml files use -. For example opentracing.zipkin.http-sender.url=http://somehost:someport
• For environment variables use _. For example OPENTRACING_ZIPKIN_HTTP_SENDER_URL=http://somehost:someport

Defaults

If no configuration options are changed and the user does not manually provide any of the beans that the auto-configuration process provides, the following defaults are used:

• unknown-spring-boot Will be used as the service-name if no value has been specified to the property spring.application.name.
• Sampler.ALWAYS_SAMPLE
• AsyncReporter (using an OkHttpSender)

Common cases

Set service name

Set spring.application.name to the desired name

Sampling

• Boundary sampler

  opentracing.zipkin.boundary-sampler.rate = value

  Where value is between 0.0 (no sampling) and 1.0 (sampling of every request)

• Counting sampler

  opentracing.zipkin.counting-sampler.rate = value

  Where value is between 0.0 (no sampling) and 1.0 (sampling of every request)

The samplers above are mutually exclusive.

A custom sampler could of course be provided by declaring a bean of type brave.sampler.Sampler

Reporter

By default starter configures AsyncRepoter using OkHttpSender with JSON_V2 encoding. Following properties can be changed to configure the reporter.

• opentracing.zipkin.http-sender.encoder - encoding of spans e.g. JSON_V1, JSON_V2, PROTO3
• opentracing.zipkin.http-sender.baseUrl - set base url e.g. http://zipkin:9411/

Advanced cases

Manual bean provisioning

Any of the following beans can be provided by the application (by adding configuring them as bean with @Bean for example) and will be used to by the Tracer instead of the auto-configured beans.

• brave.sampler.Sampler
• zipkin2.reporter.Reporter

brave.Tracing.Builder customization

Right before the Tracer is created, it is possible to provide arbitrary customizations to Tracing.Builder by providing a bean of type ZipkinTracerCustomizer

Caution

Beware of the default sampler in production

In a high traffic environment, the default sampler that is configured is very unsafe since it samples every request. It is therefore highly recommended to explicitly configure on of the other options in a production environment

Development

Maven checkstyle plugin is used to maintain consistent code style based on Google Style Guides

./mvnw clean install

Release

Follow instructions in RELEASE

License

Apache 2.0 License.