Run the Java Agent Alongside Dynatrace OneAgent

This page explains how to run the Contrast Java agent on a JVM that also has Dynatrace OneAgent installed. It covers both common OneAgent deployment styles, including an explicit -javaagent flag, and full stack host injection.

Before you begin

Contrast Java agent version 6.15.0 or later is required.
This agent release stopped Dynatrace from instrumenting and introspecting the Contrast agent's own third party dependency classes, a conflict that could otherwise prevent the Contrast agent from starting.

Determine how OneAgent is deployed

Dynatrace OneAgent reaches a JVM one of two ways:

An explicit -javaagent flag, which is the same mechanism Contrast itself uses. If the java command or JAVA_TOOL_OPTIONS shows -javaagent pointing at a Dynatrace jar, commonly oneagentloader.jar, OneAgent was added this way.
Full stack host injection, which is Dynatrace's own recommended approach for containers and hosts. In this mode, Dynatrace sets the LD_PRELOAD environment variable to point at its native library, commonly liboneagentproc.so, and no -javaagent flag appears anywhere. Because the injection happens before the JVM starts, you cannot reorder it the way the two -javaagent flags can be reordered.

To tell which mode is active, check the running process for a Dynatrace -javaagent flag first. If none is present, check the process environment for LD_PRELOAD. The Contrast Java agent detects LD_PRELOAD-based agents since Java Agent 5.2.3.

Steps for `-javaagent` deployments

Add the Contrast agent first on the java command line, ahead of the Dynatrace agent:

java -javaagent:contrast.jar -javaagent:oneagentloader.jar -jar app.jar

Loading Contrast first reduces the performance impact of running both agents together.

Steps for full stack host injection

Two mitigations are supported, and neither approach depends on load order:

Run Contrast Java agent 6.15.0 or later. That release stops Dynatrace from introspecting Contrast's own dependency classes no matter which agent technically loads first.
Add a Dynatrace side exclusion so OneAgent skips Contrast's classes entirely. See Dynatrace side configuration, below, for details.

Dynatrace side configuration

Dynatrace supports an environment variable that excludes matching classes from instrumentation:

DT_EXCLUDE_JAVA_CLASSES={match_type}:{pattern}(;{match_type}:{pattern}...)

Where match_type is one of starts, contains, or ends.

The recommended value for Contrast is as follows:

DT_EXCLUDE_JAVA_CLASSES=starts:com.contrastsecurity

If you continue to see instrumentation conflicts with the exclusion variable set, confirm whether Dynatrace's CloudNative feature is enabled and whether it can be disabled.

Kubernetes using the Contrast Agent Operator

If the Dynatrace Operator runs in classicFullStack mode, set CONTRAST_ENABLE_EARLY_CHAINING=true on the Contrast Agent Operator configuration and restart the affected pods.

Verify both agents are running

In Contrast, confirm the application appears in the Contrast interface and that contrast.log shows a normal startup with no agent conflict errors.

In Dynatrace, confirm the process appears as monitored in Dynatrace and that OneAgent's own logs show it attached successfully.

A clean startup on both sides, with none of the errors listed under Known issues and troubleshooting below, is a reasonable smoke test that the two agents are coexisting correctly.

Measure agent CPU overhead using Dynatrace

Dynatrace can isolate how much CPU time the Contrast agent itself is using:

In Dynatrace, create an API Detection Rule using com.contrastsecurity as the pattern.
Open Diagnostic tools > CPU analysis > Method hotspots for the timeframe you want to measure. That view isolates method calls from Contrast from the rest of the application.

Known issues and troubleshooting

Issue	Resolution
Agent fails to start, third party class conflict	Dynatrace instruments shaded third party dependencies, such as the Apache HttpClient classes bundled in Contrast. This may prevent the Contrast agent from starting. Upgrading the Contrast Java Agent 6.15.0 addresses this by renaming the affected classes so Dynatrace no longer recognizes them as instrumentation targets.
`UnsatisfiedLinkError` on startup	Seen with Dynatrace's CloudNative instrumentation feature enabled, on both JDK 17 and JDK 21, in Kubernetes and Helm deployments. Disable CloudNative in Dynatrace, or set `DT_EXCLUDE_JAVA_CLASSES`.
JVM crash on startup	Upgrade to Java Agent 6.15.0. Two separate crashes were fixed on the way to that release: a general JVM crash in Java Agent 6.5.0 a crash specific to OpenJDK 21 in Java Agent 6.5.2 Both are included once you are on 6.15.0 or later. Knowing the specific versions helps confirm whether a crash on an older agent matches one of these known issues or is a new issue.

Issue

Resolution

Agent fails to start, third party class conflict

Dynatrace instruments shaded third party dependencies, such as the Apache HttpClient classes bundled in Contrast. This may prevent the Contrast agent from starting.

Upgrading the Contrast Java Agent 6.15.0 addresses this by renaming the affected classes so Dynatrace no longer recognizes them as instrumentation targets.

UnsatisfiedLinkError on startup

Seen with Dynatrace's CloudNative instrumentation feature enabled, on both JDK 17 and JDK 21, in Kubernetes and Helm deployments.

Disable CloudNative in Dynatrace, or set DT_EXCLUDE_JAVA_CLASSES.

JVM crash on startup

Upgrade to Java Agent 6.15.0.

Two separate crashes were fixed on the way to that release:

a general JVM crash in Java Agent 6.5.0
a crash specific to OpenJDK 21 in Java Agent 6.5.2

Both are included once you are on 6.15.0 or later. Knowing the specific versions helps confirm whether a crash on an older agent matches one of these known issues or is a new issue.

In this section: