This module provides core tracing functionality for custom instrumentation.
<dependency> <groupId>io.jaegertracing</groupId> <artifactId>jaeger-core</artifactId> <version>$jaegerVersion</version> </dependency>
Note that you'll most likely want to include a higher-level dependency that includes components
sending data to a backend, like
A tracer instance can be obtained via the
io.jaegertracing.Configuration object. In the general
case, the most appropriate way is to get a tracer that is configured based on environment variables, like:
Tracer tracer = Configuration.fromEnv().getTracer();
If a more complex customization is required, the builder pattern can be used, like:
CodecConfiguration codecConfiguration = new CodecConfiguration() .withCodec(Builtin.HTTP_HEADERS, codec1) .withCodec(Builtin.HTTP_HEADERS, codec2); Configuration configuration = new Configuration("foo") .withCodec(codecConfiguration); Tracer tracer = configuration.getTracer();
Multiple calls to
Configuration#getTracer() result in the same tracer instance.
For more advanced cases, direct access to
be required. Note that this class is not part of the public API and its usage should be avoided.
A tracer instance can be obtained from
Tracer tracer = new JaegerTracer.Builder("myServiceName").build()
Jaeger Tracer can also work in the environment where B3 propagation is used. This is mostly related
to systems instrumented with Zipkin. Once you register
B3TextMapCodec, Jaeger can join traces
started by other Zipkin instrumented applications. This includes reading headers
X-B3-TraceId. Jaeger B3 implementation automatically propagates baggage and by default it
b3Codec = new B3TextMapCodec(); tracer = new JaegerTracer.Builder(serviceName) .registerInjector(Format.Builtin.HTTP_HEADERS, b3Codec) .registerExtractor(Format.Builtin.HTTP_HEADERS, b3Codec) ...
Configuration via Environment
When obtaining a tracer instance using the
io.jaegertracing.Configuration#fromEnv() method, values specified
via system properties (
-DJAEGER_SERVICE_NAME=foo) will override values specified via environment variables.
The following property names are available:
|JAEGER_SERVICE_NAME||yes||The service name|
|JAEGER_AGENT_HOST||no||The hostname for communicating with agent via UDP|
|JAEGER_AGENT_PORT||no||The port for communicating with agent via UDP|
|JAEGER_ENDPOINT||no||The traces endpoint, in case the client should connect directly to the Collector, like http://jaeger-collector:14268/api/traces|
|JAEGER_AUTH_TOKEN||no||Authentication Token to send as "Bearer" to the endpoint|
|JAEGER_USER||no||Username to send as part of "Basic" authentication to the endpoint|
|JAEGER_PASSWORD||no||Password to send as part of "Basic" authentication to the endpoint|
|JAEGER_PROPAGATION||no||Comma separated list of formats to use for propagating the trace context. Defaults to the standard Jaeger format. Valid values are jaeger and b3|
|JAEGER_REPORTER_LOG_SPANS||no||Whether the reporter should also log the spans|
|JAEGER_REPORTER_MAX_QUEUE_SIZE||no||The reporter's maximum queue size|
|JAEGER_REPORTER_FLUSH_INTERVAL||no||The reporter's flush interval (ms)|
|JAEGER_SAMPLER_TYPE||no||The sampler type|
|JAEGER_SAMPLER_PARAM||no||The sampler parameter (number)|
|JAEGER_SAMPLER_MANAGER_HOST_PORT||no||The host name and port when using the remote controlled sampler|
|JAEGER_TAGS||no||A comma separated list of
JAEGER_AGENT_PORT will make the client send traces to the agent via
JAEGER_ENDPOINT environment variable is also set, the traces are sent to the endpoint, effectively making
JAEGER_AGENT_* vars ineffective.
JAEGER_ENDPOINT is set, the
HttpSender is used when submitting traces to a remote
endpoint, usually served by a Jaeger Collector. If the endpoint is secured, a HTTP Basic Authentication
can be performed by setting the related environment vars. Similarly, if the endpoint expects an authentication
token, like a JWT, set the
JAEGER_AUTH_TOKEN environment variable. If the Basic Authentication environment
variables and the Auth Token environment variable are set, Basic Authentication is used.
Obtaining Tracer via TracerResolver
Jaeger's Java Client also provides an implementation of the
TracerResolver, allowing a
Tracer to be
obtained in a vendor neutral manner. This
TracerResolver implementation uses the configuration via
environment approach described above.
More information about using the
TracerResolver can be found here.
Reporting internal metrics via Micrometer
The Jaeger Java Client collects internal metrics and is able to report them via Micrometer.
To accomplish that, include the artifact
io.jaegertracing:jaeger-micrometer as a dependency to your project. The
integration should be done automatically via the service loader.
If you prefer a manual configuration, it can be done with a code similar to this:
MicrometerMetricsFactory metricsReporter = new MicrometerMetricsFactory(); Configuration configuration = new Configuration("myServiceName"); Tracer tracer = configuration .getTracerBuilder() .withMetricsFactory(metricsReporter) .build();
Especially in unit tests, it's useful to have tracer that is not connected to tracing backend, but collects spans in memory:
Reporter reporter = new InMemoryReporter(); Sampler sampler = new ConstSampler(true); Tracer tracer = new JaegerTracer.Builder(serviceName) .withReporter(reporter) .withSampler(sampler) .build();
See also: opentracing-java