SDA Commons Server OpenTelemetry

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.

Docs

An extensive documentation can be found in OpenTelemetry Java documentation.

Migrating from OpenTracing

Here you can find a migration guide, if you use OpenTracing on your project.

Usage

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.

Configuration

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.

Service Name

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.

Basic configuration

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

Using other exporters

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

Disable Tracing

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.

Manual instrumentation

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.