Automatically instrument Java applications with OpenTelemetry
This guide shows how to use the OpenTelemetry automatic instrumentation for Java applications and export the traces to Dynatrace.
- To learn more about how Dynatrace works with OpenTelemetry, see Send data to Dynatrace with OpenTelemetry.
- To learn about manual instrumentation, see Manually instrument Java applications with OpenTelemetry.
- To learn how to export the metrics to Dynatrace with OpenTelemetry Instrument Java applications with OpenTelemetry Metrics.
Prerequisites
- Dynatrace version 1.222+
- OneAgent version 1.237+
- OpenTelemetry Java Instrumentation agent support is enabled
- From the Dynatrace menu, go to Settings > Preferences > OneAgent features.
- Find and turn on OpenTelemetry Java Instrumentation agent support.
- W3C Trace Context is enabled
- From the Dynatrace menu, go to Settings > Server-side service monitoring > Deep monitoring > Distributed tracing.
- Turn on Send W3C Trace Context HTTP headers.
Overview
To monitor your Java application with OpenTelemetry, you need to
Instrument your application
Send the data to Dynatrace
Restart your application and verify the data in Dynatrace
Configure data capture to meet privacy requirements
Instrument your application
-
Download the latest version of the
opentelemetry-javaagent.jar
file into your preferred directory from github. -
Set the
OTEL_RESOURCE_ATTRIBUTES
environment variable to define your service name and service version as follows:
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.
- Launch the
opentelemetry-javaagent.jar
together with your app, as shown below:
java -javaagent:path/to/opentelemetry-javaagent.jar \
-jar myapp.jar
Send data to Dynatrace
You have two options for sending data to Dynatrace.
To send data to Dynatrace, you need to configure your environment variables as follows:
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 need to configure your environment variables as follows:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<URL>
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization="Api-Token <TOKEN>"
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_METRICS_EXPORTER=none
Lastly, you need to define the correct endpoint and token, to make sure your data arrives where it should be.
- To set the endpoint:
- 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
- Dynatrace ActiveGate
https://{your-activegate-endpoint}/e/{your-environment-id}/api/v2/otlp/v1/traces
- You may need to include the port to your ActiveGate endpoint. For example:
https://{your-activegate-endpoint}:9999/e/{your-environment-id}/api/v2/otlp/v1/traces
- If you are running a containerized ActiveGate, you need to use the FQDN of it. For example:
https://{your-activegate-service-name}.dynatrace.svc.cluster.local/e/{your-environment-id}/api/v2/otlp/v1/traces
- You may need to include the port to your ActiveGate endpoint. For example:
- Dynatrace SaaS
- Replace
<URL>
in the code snippet above with your endpoint.
- Use your Environment ID to set the endpoint to which your app will send traces as follows:
- To create an authentication token
- In the Dynatrace menu, go to Access tokens and select Generate new token.
- Provide a Token name.
- In the Search scopes box, search for
Ingest OpenTelemetry traces
and select the checkbox. - Select Generate token.
- Select Copy to copy the token to your clipboard.
- Save the token in a safe place; you can't display it again.
- Replace
<TOKEN>
in the code snippet above with your token.
Verify that the traces are ingested into Dynatrace
A few minutes after restarting your app, look for your spans:
- In the Dynatrace menu, go to Distributed traces and select the Ingested traces tab.
- Your spans will be part of an existing PurePath distributed trace if the root of your call is already monitored by OneAgent.
If your application does not receive any traffic, there will be no traces.
Configure data capture to meet privacy requirements optional
While Dynatrace automatically captures all OpenTelemetry resource and span attributes, only attribute values specified in the allowlist are stored and displayed in the Dynatrace web UI. This prevents accidental storage of personal data, so you can meet your privacy requirements and control the amount of monitoring data that's stored.
To view your custom span attributes, you need to allow them in the Dynatrace web UI first:
- Span attributes In the Dynatrace menu, go to Settings and select Server-side service monitoring > Span attributes.
- Resource attributes In the Dynatrace menu, go to Settings and select Server-side service monitoring > Resource attributes.