Spring Boot OpenTracing auto-configuration

Spring Boot auto-configuration for OpenTracing tracer implementations

License	License Apache License, Version 2.0
GroupId	GroupId me.snowdrop
ArtifactId	ArtifactId opentracing-tracer-parent
Last Version	Last Version 0.1
Release Date	Release Date Mar 1, 2018
Type	Type pom
Description	Description Spring Boot OpenTracing auto-configuration Spring Boot auto-configuration for OpenTracing tracer implementations
Project URL	Project URL https://github.com/snowdrop/opentracing-tracer
Source Code Management	Source Code Management https://github.com/snowdrop/opentracing-tracer

Download opentracing-tracer-parent

Filename	Size
opentracing-tracer-parent-0.1.pom	11 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/me.snowdrop/opentracing-tracer-parent/ -->
<dependency>
    <groupId>me.snowdrop</groupId>
    <artifactId>opentracing-tracer-parent</artifactId>
    <version>0.1</version>
    <type>pom</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/me.snowdrop/opentracing-tracer-parent/
implementation 'me.snowdrop:opentracing-tracer-parent:0.1'

Gradle Kotlin

// https://jarcasting.com/artifacts/me.snowdrop/opentracing-tracer-parent/
implementation ("me.snowdrop:opentracing-tracer-parent:0.1")

Apache Buildr

'me.snowdrop:opentracing-tracer-parent:pom:0.1'

Apache Ivy

<dependency org="me.snowdrop" name="opentracing-tracer-parent" rev="0.1">
  <artifact name="opentracing-tracer-parent" type="pom" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='me.snowdrop', module='opentracing-tracer-parent', version='0.1')
)

Scala SBT

libraryDependencies += "me.snowdrop" % "opentracing-tracer-parent" % "0.1"

Leiningen

[me.snowdrop/opentracing-tracer-parent "0.1"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

opentracing-tracer-autoconfigure
opentracing-tracer-jaeger-starter
opentracing-tracer-jaeger-spring-web-starter
opentracing-tracer-jaeger-spring-cloud-starter
opentracing-tracer-testsuite

opentracing-tracer

Spring Boot autoconfiguration for OpenTracing tracer implementations

WARNING

This repo has been deprecated. Please use this module instead

Usage

Depending on what kind of Spring project is to be instrumented, add of one the following dependencies

Spring MVC project

<dependency>
    <groupId>me.snowdrop</groupId>
    <artifactId>opentracing-tracer-jaeger-spring-web-starter</artifactId>
    <version>0.1</version>
</dependency>

Spring Cloud project

<dependency>
    <groupId>me.snowdrop</groupId>
    <artifactId>opentracing-tracer-jaeger-spring-cloud-starter</artifactId>
    <version>0.1</version>
</dependency>

If for some reason the user plans to include the instrumentation dependencies manually, then the following starter can be used to simply include the auto-configuration code and Jaeger dependency

<dependency>
    <groupId>me.snowdrop</groupId>
    <version>0.1</version>
    <artifactId>opentracing-tracer-jaeger-starter</artifactId>
</dependency>

Configuration options

All the available configuration options can be seen in me.snowdrop.opentracing.tracer.JaegerConfigurationProperties. The prefix to be used for these properties is opentracing.jaeger.

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

For properties / yaml files use -. For example opentracing.jaeger.log-spans=true
For environment variables use _. For example OPENTRACING_JAEGER_LOG_SPANS

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:

spring-boot Will be used as the service-name
A CompositeReporter is provided which does not contain any delegates - effectively functioning as a Noop Reporter
A ConstSampler with the value of true. This means that every trace will be sampled
A NullStatsReporter is used - effectively meaning that no stats will be collected about the reporting of traces

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.

com.uber.jaeger.samplers.Sampler
com.uber.jaeger.metrics.StatsReporter
com.uber.jaeger.metrics.Metrics
com.uber.jaeger.reporters.Reporter

Common cases

Set service name

Set opentracing.jaeger.service-name to the desired name

Define an HTTP collector

Set opentracing.jaeger.http-sender.url to the URL of the Jaeger collector

Define a UDP collector

Set opentracing.jaeger.udp-sender.host to the host of the Jaeger collector and opentracing.jaeger.udp-sender.port to the end of the Jaeger collector

Enable logging of spans

Set opentracing.jaeger.log-spans to true

Use a probabilistic sampler

Set opentracing.jaeger.probabilistic-sampler.sampling-rate to a value between 0.0 (no sampling) and 1.0 (sampling of every request)

Propagate headers in B3 format (for compatibility with Zipkin collectors)

Set opentracing.jaeger.enable-b3-propagation to true

Advanced cases

com.uber.jaeger.Tracer.Builder customization

Before creating the Tracer it is possible to provide arbitrary customizations to Tracer.Builder by providing a bean of type JaegerTracerCustomizer

Add custom reporter while maintaining the ability to autoconfigure standard ones with properties

By supplying a bean of ReporterAppender the user can add custom as many custom Reporter as needed without having the forgo the ability to configure the standard reportes via auto-configuration

Use OpenTracing's TracerResolver

If the user want's to construct the Tracer using TracerResolver.resolveTracer the property opentracing.jaeger.useTracerResolver needs to be set to true (in addition of course to opentracing.jaeger.enable being set to true) In such a case none of this project's defaults are used and neither are the other configuration properties consulted. Check out the documentation of TracerResolver for details on what properties need to be set. Those properties mentioned in the documentation can be set using any method Spring Boot supports and are not limited to System Properties and Environment Variables that TraceResolver supports out of the box

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

Executing tests

In order for all tests to run correctly, the docker daemon need to be running on the system

Run the tests be executing

mvn clean test

Snowdrop

Home of Snowdrop

Versions

Version
0.1 Mar 1, 2018