Java Compatibility Requirements

이 페이지는 아직 한국어로 제공되지 않으며 번역 작업 중입니다. 번역에 관한 질문이나 의견이 있으시면 언제든지 저희에게 연락해 주십시오.

Compatibility

The Java Datadog Trace library is open source - view the GitHub repository for more information.

Supported Java runtimes

The Java Tracer supports automatic instrumentation for the following Oracle JDK, OpenJDK JVM, and GraalVM runtimes.

Java Tracer v1 (latest)

Java versionsOperating SystemsSupport level
from 22 and upwardWindows (x86, x86-64)
Linux (x86, x86-64, arm64)
Mac (x86, x86-64, arm64)		Beta
from 18 to 21Windows (x86, x86-64)
Linux (x86, x86-64, arm64)
Mac (x86, x86-64, arm64)		GA
from 8 to 17Windows (x86, x86-64)
Linux (x86, x86-64)
Mac (x86, x86-64)		GA
Linux (arm64)
Mac (arm64)		Beta

Datadog does not officially support any early-access versions of Java.

Java Tracer v0 (maintenance)

Java versionsOperating SystemsSupport level
7 onlyWindows (x86, x86-64)
Linux (x86, x86-64)
Mac (x86, x86-64)		Maintenance
7 onlyLinux (arm64)
Mac (arm64)		End-of-life

Levels of support

LevelSupport provided
UnsupportedNo implementation. Contact Datadog support for special requests.
BetaInitial implementation. May not yet contain all features. Support for new features and bug and security fixes are provided on a best-effort basis.
General Availability (GA)Full implementation of all features. Full support for new features and bug and security fixes.
MaintenanceFull implementation of existing features. Does not receive new features. Support for bug and security fixes only.
End-of-life (EOL)No support.

Integrations

Beta integrations are disabled by default but can be enabled individually:

  • System Property: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • Environment Variable: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

Web framework compatibility

dd-java-agent includes support for automatically tracing the following web frameworks.

Web Framework tracing provides:

  • timing HTTP request to response
  • tags for the HTTP request (status code, method, etc.)
  • error and stacktrace capturing
  • linking work created within a web request and Distributed Tracing
ServerVersionsSupport TypeInstrumentation Names (used for configuration)
Akka-Http Server10.0+Fully Supportedakka-http, akka-http-server
Finatra Web2.9+Fully Supportedfinatra
Grizzly2.0+Fully Supportedgrizzly
Grizzly-HTTP2.3.20+Fully Supportedgrizzly-filterchain
Java Servlet Compatible2.3+, 3.0+Fully Supportedservlet, servlet-2, servlet-3
Jax-RS AnnotationsJSR311-APIFully Supportedjax-rs, jaxrs, jax-rs-annotations, jax-rs-filter
Jetty7.0-12.xFully Supportedjetty
Micronaut HTTP Server2.xFully Supportedmicronaut
Mulesoft4Fully Supportedmule
Netty HTTP Server3.8+Fully Supportednetty, netty-3.8, netty-4.0, netty-4.1
Play2.3-2.8Fully Supportedplay, play-action
Ratpack1.5+Fully Supportedratpack
Restlet HTTP Server2.2 - 2.4Fully Supportedrestlet-http.
Spark Java2.3+Betasparkjava (requires jetty)
Spring Boot1.5+Fully Supportedspring-web or spring-webflux
Spring Web (MVC)4.0+Fully Supportedspring-web
Spring WebFlux5.0+Fully Supportedspring-webflux
Tomcat5.5+Fully Supportedtomcat
Undertow2.0+Fully Supportedundertow
Vert.x3.4+Fully Supportedvertx, vertx-3.4, vertx-3.9, vertx-4.0

Note: Many application servers are Servlet compatible and are automatically covered by that instrumentation, such as Websphere, Weblogic, and JBoss. Also, frameworks like Spring Boot (version 3) inherently work because they usually use a supported embedded application server, such as Tomcat, Jetty, or Netty.

Framework Integrations Disabled By Default

The following instrumentations are disabled by default and can be enabled with the following settings:

InstrumentationTo Enable
JAX-WS-Ddd.integration.jax-ws.enabled=true
Mulesoft-Ddd.integration.mule.enabled=true, -Ddd.integration.grizzly-client.enabled=true, -Ddd.integration.grizzly-filterchain.enabled=true
Grizzly-Ddd.integration.grizzly-client.enabled=true
Grizzly-HTTP-Ddd.integration.grizzly-filterchain.enabled=true
Ning-Ddd.integration.ning.enabled=true
Spark Java-Ddd.integration.sparkjava.enabled=true
Hazelcast (client side only)-Ddd.integration.hazelcast.enabled=true
-Ddd.integration.hazelcast_legacy.enabled=true
TIBCO BusinessWorks-Ddd.integration.tibco.enabled=true

Note: JAX-WS integration instruments endpoints annotated with @WebService (JAX-WS 1.x) and @WebServiceProvider (JAX-WS 2.x).

Don’t see your desired web frameworks? Datadog is continually adding additional support. Contact Datadog support if you need help.

Networking framework compatibility

dd-java-agent includes support for automatically tracing the following networking frameworks.

Networking tracing provides:

  • timing request to response
  • tags for the request (for example, response code)
  • error and stacktrace capturing
  • distributed tracing
FrameworkVersionsSupport TypeInstrumentation Names (used for configuration)
Apache HTTP Client4.0+Fully Supportedhttpclient, apache-httpclient, apache-http-client
Apache HTTP Async Client4.0+Fully Supportedhttpasyncclient, apache-httpasyncclient
AWS Java SDK1.11+, 2.2+Fully Supportedaws-sdk
Camel-OpenTelemetry3.12.0+Betaopentelemetry-1
Commons HTTP Client2.0+Fully Supportedcommons-http-client
Google HTTP Client1.19.0+Fully Supportedgoogle-http-client
Google Pub/Sub1.116.0+Fully Supportedgoogle-pubsub
Grizzly HTTP Client1.9+Betagrizzly-client
gRPC1.5+Fully Supportedgrpc, grpc-client, grpc-server
HttpURLConnectionallFully Supportedhttpurlconnection, urlconnection
Kafka-Clients0.11+Fully Supportedkafka
Kafka-Streams0.11+Fully Supportedkafka, kafka-streams
Java RMIallDistributed Tracing Not Supportedrmi, rmi-client, rmi-server
Jax RS Clients2.0+Fully Supportedjax-rs, jaxrs, jax-rs-client
Jersey Client1.9-2.29Fully Supportedjax-rs, jaxrs, jax-rs-client
JMS / Jakarta JMS1-3.0+Fully Supportedjms, jms-1, jms-2, jakarta-jms
Netty HTTP Client4.0+Fully Supportednetty, netty-4.0, netty-4.1
Ning HTTP Client1.9.0+Betaning
OkHTTP2.2+Fully Supportedokhttp, okhttp-2,okhttp-3
Play WSClient1.0+Fully Supportedplay-ws
Rabbit AMQP2.7+Fully Supportedamqp, rabbitmq
Spring SessionAwareMessageListener3.1+Fully Supportedspring-jms-3.1
Spring WebClient5.0+Fully Supportedspring-webflux, spring-webflux-client

Kafka Note: Datadog’s Kafka integration works with Kafka version 0.11+, which supports the Header API. This API is used to inject and extract trace context. If you are running a mixed version environment, the Kafka broker can incorrectly report the newer version of Kafka. This causes an issue when the tracer tries to inject headers that are not supported by the local producer. Additionally, older consumers are unable to consume the message because of the presence of headers. To prevent these issues, if you are running a mixed version Kafka environment with versions older than 0.11, disable context propagation with the environment variable: DD_KAFKA_CLIENT_PROPAGATION_ENABLED=false.

JMS Note: Datadog’s JMS integration automatically adds and reads message object properties x__dash__datadog__dash__trace__dash__id and x__dash__datadog__dash__parent__dash__id to maintain context propagation between consumer and producer services.

Camel Note: Distributed trace propagation over Camel routes is not supported.

Don’t see your desired networking framework? Datadog is continually adding additional support. Contact Datadog support if you need help.

Data store compatibility

dd-java-agent includes support for automatically tracing the following database frameworks/drivers.

Datastore tracing provides:

  • timing request to response
  • query info (for example, a sanitized query string)
  • error and stacktrace capturing
DatabaseVersionsSupport TypeInstrumentation Names (used for configuration)
Aerospike4.0+Fully Supportedaerospike
Couchbase2.0+Fully Supportedcouchbase
Cassandra3.0+Fully Supportedcassandra
Elasticsearch Transport2.0+Fully Supportedelasticsearch, elasticsearch-transport, elasticsearch-transport-{2,5,6,7} (pick one)
Elasticsearch Rest5.0+Fully Supportedelasticsearch, elasticsearch-rest, elasticsearch-rest-{5,6,7} (pick one)
JDBCN/AFully Supportedjdbc, jdbc-datasource
Jedis1.4+Fully Supportedjedis, redis
Lettuce4.0+Fully Supportedlettuce, lettuce-4-async, lettuce-5-rx
MongoDB3.0-4.0+Fully Supportedmongo
OpenSearch Rest1.x-2.xFully Supportedopensearch, opensearch-rest
OpenSearch Transport1.x-2.xFully Supportedopensearch, opensearch-transport
RediScala1.5+Fully Supportedrediscala, redis
Redisson2.x-3.xFully Supportedredisson, redis
SpyMemcached2.12+Fully Supportedspymemcached
Vert.x Cassandra Client3.9+Fully Supportedcassandra
Vert.x Redis Client3.9Fully Supportedvertx-redis-client
Vert.x MySQL Client3.9+Fully Supportedvertx-sql-client

dd-java-agent is also compatible with common JDBC drivers including:

  • Apache Derby
  • Firebird SQL
  • H2 Database Engine
  • HSQLDB
  • IBM DB2
  • MariaDB
  • MSSQL (Microsoft SQL Server)
  • MySQL
  • Oracle
  • Postgres SQL
  • ScalikeJDBC

Database Integrations Disabled By Default

The following instrumentations are disabled by default and can be enabled with the following settings:

InstrumentationTo Enable
JDBC-Datasource- System Property: -Ddd.integration.jdbc-datasource.enabled=true
- Environment Variable: DD_INTEGRATION_JDBC_DATASOURCE_ENABLED=true

Don’t see your desired datastores? Datadog is continually adding additional support. Contact Datadog support if you need help.

Additional framework compatibility

dd-java-agent includes support for automatically tracing the following frameworks.

FrameworkVersionsSupport TypeInstrumentation Names (used for configuration)
Apache CXF (Jax-WS)3.0+OpenTelemetry Extensioncxf
Datanucleus JDO4.0+Fully Supporteddatanucleus
Dropwizard Views0.7+Fully Supporteddropwizard, dropwizard-view
GraphQL14.0+Fully Supportedgraphql-java
Hazelcast (client)3.6+Betahazelcast, hazelcast_legacy
Hibernate3.5+Fully Supportedhibernate, hibernate-core
Hystrix1.4+Fully Supportedhystrix
JSP Rendering2.3+Fully Supportedjsp, jsp-render, jsp-compile
JUnit4.1+, 5.3+Fully Supportedjunit, junit-4, junit-5
Project Reactor3.1+Fully Supportedreactor-core
Quartz2.xFully Supportedquartz
RxJava2.xFully Supportedrxjava
Spring Data1.8+Fully Supportedspring-data
Spring Scheduling3.1+Fully Supportedspring-scheduling
TIBCO BusinessWorks5.14.0+Betatibco, tibco_bw
Twilio SDK< 8.0Fully Supportedtwilio-sdk

Don’t see your desired frameworks? Datadog is continually adding additional support. To request a framework, contact our awesome support team.

To improve visibility into applications using unsupported frameworks, consider:

Disabling integrations

Most integrations are enabled by default. The following setting can change the default to disabled.

  • System Property: -Ddd.integrations.enabled=false
  • Environment Variable: DD_INTEGRATIONS_ENABLED=false

Integrations can be enabled or disabled individually (overriding the default above).

  • System Property: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • Environment Variable: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

(See above for each integration’s name.)

Known issues

  • Running the Java tracer in Bitbucket is not supported.
  • Loading multiple Java Agents that perform APM/tracing functions is not a recommended or supported configuration.

GraalVM Native Image support

GraalVM Native Image is a technology that allows you to compile Java applications into native executables. The Datadog Java tracer supports GraalVM Native Image. This allows you to compile your applications into native executables while still benefiting from the tracing capabilities offered by the library.

Requirements

Use the latest versions of:

Setup

    To set up the Datadog Java tracer with GraalVM Native Image, follow these steps:

    1. Instrument your application, following the steps described on Tracing Java Applications.
    2. When you build a native executable with the native-image command, add the -J-javaagent:/path/to/dd-java-agent.jar argument. For example:
      native-image -J-javaagent:/path/to/dd-java-agent.jar -jar App.jar
    3. (Optional) Enable the profiler integration by adding the following argument: -J-Ddd.profiling.enabled=true -–enable-monitoring=jfr.
      • For tracer versions before 1.39.1, when executing the generated native executable, ensure that DD_PROFILING_START_FORCE_FIRST=true is set as an environment variable.

    To set up the Datadog Java tracer with Quarkus Native, follow these steps:

    1. Instrument your application, following the steps described in Tracing Java Applications.
    2. When you build a native executable, use the quarkus.native.additional-build-args property. For example:
      ./mvnw package -Dnative -Dquarkus.native.additional-build-args='-J-javaagent:/path/to/dd-java-agent.jar'
    3. (Optional) Enable the profiler integration by adding the following argument: -J-Ddd.profiling.enabled=true -–enable-monitoring=jfr.
      • For tracer versions before 1.39.1, when executing the generated native executable, ensure that DD_PROFILING_START_FORCE_FIRST=true is set as an environment variable.

    To set up the Datadog Java tracer with Spring Native, follow these steps:

    1. Instrument your application, following the steps described on Tracing Java Applications.
    2. For Spring Native builds based on Buildpacks, enable the Paketo Buildpack for Datadog using BP_DATADOG_ENABLED=true.
      • You can do this at the build tool level, like Maven:
      <build>
<plugins>
  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
      <image>
        ...
        <env>
          ...
          <BP_DATADOG_ENABLED>true</BP_DATADOG_ENABLED>
          ...
        </env>
      </image>
    </configuration>
  </plugin>
</plugins>
</build>
      • Alternatively, you can use the pack build command with --env BP_DATADOG_ENABLED=true option to enable the Datadog buildpack.
    3. (Optional) Enable the profiler integration by setting the environment variable BP_NATIVE_IMAGE_BUILD_ARGUMENTS=’-J-Ddd.profiling.enabled=true -–enable-monitoring=jfr’.
      • For tracer versions before 1.39.1, when executing the generated native executable, ensure that DD_PROFILING_START_FORCE_FIRST=true is set as an environment variable.

    Usage

    After completing the setup, the service should send traces to Datadog.

    You can view traces using the Trace Explorer.

    Features are not enabled or configured correctly for native images

    There are known issues with accessing system properties at runtime from a binary built with Graal Native Image.

    • For runtime configuration, use environment variables (DD_PROPERTY_NAME=value), instead of system properties (-Ddd.property.name=value).
    • The exception to this rule is when enabling the profiler. In this case, pass -J-Ddd.profiling.enabled=true to the native-image tool at build time.
    Native-image buildpack versions older than 5.12.2

    Older native-image buildpack versions expose the following option: USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM.

    When this option is false, exceptions like the following can occur:

    Caused by: org.graalvm.compiler.java.BytecodeParser$BytecodeParserError:
com.oracle.graal.pointsto.constraints.UnsupportedFeatureException:
No instances of datadog.trace.bootstrap.DatadogClassLoader are allowed in the image heap
as this class should be initialized at image runtime. To see how this object got
instantiated use --trace-object-instantiation=datadog.trace.bootstrap.DatadogClassLoader.

    Solutions to this issue are:

    • Set USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM explicitly to true in the image env configuration,
    • Or upgrade the native-image buildpack to version 5.12.2 or later. The best way to do this is by upgrading the java-native-image buildpack to 8.13.0 or later.
    Paketo buildpack for Datadog versions older than 4.6.0

    Paketo buildpack for Datadog had a bug in older versions that materialized with the following error message:

    disabling Datadog at launch time is unsupported for Node
ERROR: failed to launch: exec.d: failed to execute exec.d file at path '/layers
paketo-buildpacks_datadog/helper/exec.d/toggle': exit status 1

    The solution to this issue is to upgrade to version 4.6.0 or later.

    Further Reading

    추가 유용한 문서, 링크 및 기사:

    Instrument Your ApplicationDOCUMENTATION more more
    PREVIEWING: esther/docs-9478-fix-split-after-example