This bundle is responsible for loading the creating an OpenTelemetry Sdk instance and registering it as a global instance ready to use everywhere in dependent applications. The module also creating server traces to insure proper context propagation.
An extensive documentation can be found in OpenTelemetry Java documentation.
Here you can find a migration guide, if you use OpenTracing on your project.
The bundle must be initialized before other bundles in the dependent applications, as it is responsible for initializing the openTelemetry Sdk and registering the created instance as global, so that dependent bundles can use it.
api project(':sda-commons-server-opentelemetry')
Then the bundle is ready to be added to the application.
public class MyApp extends Application<Configuration> {
@Override
public void run(Configuration configuration, Environment environment) {}
@Override
public void initialize(Bootstrap<Configuration> bootstrap) {
// use the autoConfigured module
bootstrap.addBundle(
OpenTelemetryBundle.builder().withAutoConfiguredTelemetryInstance().build());
// ... other bundles
}
}
If the application is already using the starter bundle, no changes are needed. The module is already added and configured with environment variables.
NOTE: Except for starter bundle, no other bundle must depend on this one. The bundle registers a global Telemetry instance that is used all across the application has a safety mechanism to prevent registering a new instance twice.
The OpenTelemetry sdk is highly configurable! Many aspects of its behavior can be configured for your needs, such as exporter choice, exporter config (like where data is sent), trace context propagation headers... The configuration can be done either with environment variables or system properties. Please note that system properties will have a higher priority over environment variables.
A full list of the configurable properties can be found in the autoconfigure module.
It is recommended to use same configuration across all services in the same domain, to ensure the right context propagation, and export traces to the same monitoring backend.
The service name is used to identify the source (the sender) of the received telemetry data in the monitoring backend. Therefore, it's important that every service has a unique name.
To provide the application with a custom name for each deployment, the OTEL_SERVICE_NAME
environment variable must be used.
By default, the module exports traces in the otlp format, to a Jaeger collector. This can be very handy for less local setup overhead, where the All-in-one Jaeger image can be enough.
OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger-collector-host:4317
Or in case if the collector is deployed as a sidecar:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
To export traces in a different format to an openTelemetry collector, configure the exporter and exporter endpoint accordingly e.g.:
OTEL_TRACES_EXPORTER=zipkin
OTEL_EXPORTER_ZIPKIN_ENDPOINT=http://zipkin-host:9411
In order to disable tracing in the applications that are using this bundle, or the starter bundle, the environment variable TRACING_DISABLED=true
can be used.
Setting TRACING_DISABLED
to false will force the instrumented modules provided by sda-commons to use a no-op instance.
Sda commons already offers the necessary instrumentation for the server and some clients, to insure a better overview about service to service interaction. It is advised to avoid unnecessary tracing for interaction with external systems and expect/rely on and generic instrumentation provided by sda-commons.
If additional internal behaviour should to be traced, an OpenTelemetry instance can be acquired using GlobalOpenTelemetry.get()
.
A very basic skeleton for a creating more traces:
public class Component {
// ...
public void doSomething() {
// ...
var tracer = GlobalTelemetry.get().getTracer("sda-commons.component");
Span span = tracer.spanBuilder("doSomething").startSpan();
try (Scope ignored = span.makeCurrent()) {
// The actual work
} finally {
span.end();
}
}
}
Some examples for manual tracing can be found in OpenTelemetry manual tracing example.