OpenTelemetry interoperability for Java on z/OS
OneAgent version 1.225+ OpenTelemetry 1.0+
OpenTelemetry is a collection of tools, APIs, and SDKs that enable you to use telemetry data (metrics, logs, and traces) to get insights into your application's performance and behavior.
OpenTelemetry with OneAgent enables you to:
- Enrich traces with project-specific additions (for example, you can add business-relevant data to your traces or capture developer-specific diagnostics).
- Extend end-to-end traces (for example, you can capture a Java Transport that is not supported out-of-the-box by OneAgent or fill observability gaps between applications to achieve transactional insights).
Enable OpenTelemetry interoperability
Enabling OpenTelemetry interoperability connects the OneAgent Java code module to the OpenTelemetry API. When enabled, OneAgent redirects certain OpenTelemetry API usage (for example, GlobalOpenTelemetry
) to the internal Dynatrace OpenTelemetry SDK.
Therefore, we don't recommend that you use the OpenTelemetry SDK in your applications together with OneAgent interoperability because it could result in conflicts.
OpenTelemetry interoperability is disabled by default. To enable it, add the OpenTelemetry: EnableIntegration
parameter to the dtconfig.json
file:
{
"Tenant": "mytenant",
"ClusterID": 11223344,
"ZdcName": "DEFAULT",
"OpenTelemetry": {
"EnableIntegration": true
}
}
Alternatively, you can add the open-telemetry-enable-integration
option to the OneAgent JVM argument:
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=open-telemetry-enable-integration=true
OpenTelemetry instrumentation samples
To support various use cases, OpenTelemetry enables you to add vendor-neutral custom instrumentation to your applications. Instrumenting applications with OpenTelemetry requires programming knowledge and access to the application’s code. To learn how to instrument your application, refer to OpenTelemetry documentation and OpenTelemetry Java documentation.
See the examples below for using OpenTelemetry Java.
Suppress spans from specific instrumentations
You can suppress spans coming from a particular instrumentation library. To do so, add the library name to the OpenTelemetry: DisabledSensors
parameter in name via the dtconfig.json
file. You can use an asterisk (*
) to exclude all instrumentation library names starting with the preceding string. You can't use asterisk at the beginning or in the middle of a library name.
{
"Tenant": "mytenant",
"ClusterID": 11223344,
"ZdcName": "DEFAULT",
"OpenTelemetry": {
"EnableIntegration": true,
"DisabledSensors": [
"com.example.MyLib",
"opentelemetry.urllib3*"
]
}
}
Alternatively, you can add the open-telemetry-disabled-sensors
option to the OneAgent JVM argument:
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=open-telemetry-disabled-sensors=com.example.MyLib:opentelemetry.urllib3*
- If you specify exclusions in the command line, the exclusions in the
dtconfig.json
file ignored. - Use colon
:
as the separator for instrumentation library names in the command line.
The examples above suppress spans from the com.example.MyLib
instrumentation library and spans from all libraries starting with the name opentelemetry.urllib3
.
Rules for spans that Dynatrace will report
Depending on the SpanKind
, Dynatrace will suppress some OpenTelemetry spans:
- A span needs to either be of kind
SpanKind.SERVER
orSpanKind.CONSUMER
or it needs to have another span (SpanContext
) as a non-remote parent. Usually, this is handled by the Dynatrace OneAgent servlet sensor, which creates aSERVER
span and sets it as the current, active span. - Child spans of spans of kind
SpanKind.CLIENT
orSpanKind.PRODUCER
will be suppressed. For example, after the Dynatrace OneAgent creates a span of kindSpanKind.CLIENT
for a synchronous outgoing HTTP call, all spans created in the thread will be suppressed until the HTTP call, and thus the HTTP Span, is finished. You can of course create new spans in the called service which will be linked correctly.
Suppressed spans will not be visible in distributed traces.