Manually instrument Java applications with OpenTelemetry

xmlcopydownload
<dependencies>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
    </dependency>
</dependencies>

groovycopydownload
dependencies {
    implementation("io.opentelemetry:opentelemetry-api")
}

To send data to Dynatrace, you need to configure your environment variables as follows:

shellcopydownload
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_METRICS_EXPORTER=none

If you do not set the metrics exporter environment variable (even in a scenario where you only want to send traces), you will receive error messages.
The functionality of sending traces is not affected.

To send data to Dynatrace, you have to add the following extra dependencies, the code snippet below in your application startup code, as well as configure the required environment variables.

xmlcopydownload
<dependencies>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
        <version>1.12.0-alpha</version>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp-http-trace</artifactId>
        <version>1.12.0</version>
    </dependency>
</dependencies>

groovycopydownload
dependencies {
    implementation 'io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.12.0-alpha'
    implementation 'io.opentelemetry:opentelemetry-exporter-otlp-http-trace:1.12.0'
}

Add the following imports to your code and create a method to enrich the OpenTelemetry Resource with Dynatrace-specific metadata:

javacopydownload
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;

private static void initOpenTelemetry() {
    AutoConfiguredOpenTelemetrySdk.builder().addResourceCustomizer((resource, properties) -> {
        Resource dtMetadata = Resource.empty();
        for (String name : new String[]{"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties", "/var/lib/dynatrace/enrichment/dt_metadata.properties"}) {
            try {
                Properties props = new Properties();
                props.load(name.startsWith("/var") ? new FileInputStream(name) : new FileInputStream(Files.readAllLines(Paths.get(name)).get(0)));
                dtMetadata = dtMetadata.merge(Resource.create(props.entrySet().stream()
                        .collect(Attributes::builder, (b, e) -> b.put(e.getKey().toString(), e.getValue().toString()), (b1, b2) -> b1.putAll(b2.build()))
                        .build())
                );
            } catch (IOException e) {
            }
        }
        return resource.merge(dtMetadata);
    }).build().getOpenTelemetrySdk();
}

Configure your environment variables as follows:

shellcopydownload
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<URL>
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization="Api-Token <TOKEN>"
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_RESOURCE_ATTRIBUTES="service.name=java-quickstart,service.version=1.0.1"

Replace the service name and version attributes with the name and version of your application.

Lastly, you need to define the correct endpoint and token to make sure your data arrives where it should be.

• To set the endpoint
  1. Use your Environment ID to set the endpoint to which your app will send traces as follows:
     • Dynatrace SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces
     • Dynatrace Managed https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/traces
  2. Replace <URL> in the environment variables above with your endpoint.
• To create an authentication token
  1. In the Dynatrace menu, go to Access tokens and select Generate new token.
  2. Provide a Token name.
  3. In the Search scopes box, search for Ingest OpenTelemetry traces and select the checkbox.
  4. Select Generate token.
  5. Select Copy to copy the token to your clipboard.
  6. Save the token in a safe place; you can't display it again.
  7. Replace <TOKEN> in the environment variables above with your token.

To send data to Dynatrace, you have to add the dependencies as well as add and configure the code snippet below in your Java application code.

xmlcopydownload
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.12.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp-http-trace</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-semconv</artifactId>
        <version>1.12.0-alpha</version>
    </dependency>
</dependencies>

groovycopydownload
dependencies {
    implementation(platform("io.opentelemetry:opentelemetry-bom:1.12.0"))
    implementation("io.opentelemetry:opentelemetry-api")
    implementation("io.opentelemetry:opentelemetry-sdk")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp-http-trace")
    implementation("io.opentelemetry:opentelemetry-semconv:1.12.0-alpha")
}

Add the following imports to your code and create a method to configure the OpenTelemetry Global Tracer Provider, as well as enrich the OpenTelemetry Resource with Dynatrace-specific metadata:

javacopydownload
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;

private static void initOpenTelemetry() {
    Resource serviceName = Optional.ofNullable(System.getenv("OTEL_SERVICE_NAME"))
            .map(n -> Attributes.of(AttributeKey.stringKey("service.name"), n))
            .map(Resource::create)
            .orElseGet(Resource::empty);

    Resource envResourceAttributes = Resource.create(Stream.of(Optional.ofNullable(System.getenv("OTEL_RESOURCE_ATTRIBUTES")).orElse("").split(","))
            .filter(pair -> pair != null && pair.length() > 0 && pair.contains("="))
            .map(pair -> pair.split("="))
            .filter(pair -> pair.length == 2)
            .collect(Attributes::builder, (b, p) -> b.put(p[0], p[1]), (b1, b2) -> b1.putAll(b2.build()))
            .build()
    );

    Resource dtMetadata = Resource.empty();
    for (String name : new String[] {"dt_metadata_e617c525669e072eebe3d0f08212e8f2.properties", "/var/lib/dynatrace/enrichment/dt_metadata.properties"}) {
        try {
            Properties props = new Properties();
            props.load(name.startsWith("/var") ? new FileInputStream(name) : new FileInputStream(Files.readAllLines(Paths.get(name)).get(0)));
            dtMetadata = dtMetadata.merge(Resource.create(props.entrySet().stream()
                    .collect(Attributes::builder, (b, e) -> b.put(e.getKey().toString(), e.getValue().toString()), (b1, b2) -> b1.putAll(b2.build()))
                    .build())
            );
        } catch (IOException e) {}
    }

    SpanExporter exporter = OtlpHttpSpanExporter.builder()
            .setEndpoint("<URL>") //TODO Replace <URL> to your SaaS/Managed-URL as mentioned in the next step
            .addHeader("Authorization", "Api-Token <TOKEN>") //TODO Replace <TOKEN> with your API Token as mentioned in the next step
            .build();

    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
            .setResource(Resource.getDefault().merge(envResourceAttributes).merge(serviceName).merge(dtMetadata))
            .setSampler(Sampler.alwaysOn())
            .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
            .build();

    OpenTelemetrySdk.builder()
            .setTracerProvider(sdkTracerProvider)
            .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
            .buildAndRegisterGlobal();
    Runtime.getRuntime().addShutdownHook(new Thread(sdkTracerProvider::close));
}

Configure your environment variables as follows:

shellcopydownload
OTEL_RESOURCE_ATTRIBUTES="service.name=java-quickstart,service.version=1.0.1"

Alternatively:

shellcopydownload
OTEL_SERVICE_NAME="java-quickstart"

Replace the service name and version attributes with the name and version of your application.

Lastly, you need to define the correct endpoint and token to make sure your data arrives where it should be.

• To set the endpoint
  1. Use your Environment ID to set the endpoint to which your app will send traces as follows:
     • Dynatrace SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces
     • Dynatrace Managed https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/traces
  2. Replace <URL> in the environment variables above with your endpoint.
• To create an authentication token
  1. In the Dynatrace menu, go to Access tokens and select Generate new token.
  2. Provide a Token name.
  3. In the Search scopes box, search for Ingest OpenTelemetry traces and select the checkbox.
  4. Select Generate token.
  5. Select Copy to copy the token to your clipboard.
  6. Save the token in a safe place; you can't display it again.
  7. Replace <TOKEN> in the environment variables above with your token.