互換性

Java Datadog Trace ライブラリはオープンソースです。詳細については、GitHub リポジトリをご覧ください。

サポートされている Java ランタイム

Java トレーサーは、Oracle JDK、OpenJDK JVM、および GraalVM の次のランタイムの自動インスツルメンテーションをサポートします。

Java トレーサー v1 (最新)

Java バージョンオペレーティングシステムサポートレベル
27 以上Windows (x86、x86-64)
Linux (x86、x86-64、arm64)
Mac (x86、x86-64、arm64)
プレビュー
18 ~ 26Windows (x86、x86-64)
Linux (x86、x86-64、arm64)
Mac (x86、x86-64、arm64)
GA
8 ~ 17Windows (x86、x86-64)
Linux (x86、x86-64)
Mac (x86、x86-64)
GA
Linux (arm64)
Mac (arm64)
プレビュー

Datadog は、Java の早期アクセスバージョンを公式にサポートしていません。

Java トレーサー v0

Java バージョンオペレーティングシステムサポートレベル
7 のみWindows (x86、x86-64)
Linux (x86、x86-64)
Mac (x86、x86-64)
サポート終了
7 のみLinux (arm64)
Mac (arm64)
サポート終了

サポートのレベル

レベルサポート内容
非対応実装していません。特別なご要望は Datadog サポートにお問い合わせください。
プレビュー初期実装です。まだすべての機能が含まれていない可能性があります。新機能のサポート、バグやセキュリティの修正は、ベストエフォートで提供されます。
一般提供 (GA)全機能の完全実装。新機能、バグやセキュリティの修正を完全サポート。
メンテナンス既存機能の完全実装。新機能は追加されません。バグとセキュリティの修正のみの対応となります。
サポート終了 (EOL)サポートはありません。

インテグレーション

プレビューのインテグレーションはデフォルトで無効になっていますが、個別に有効にできます。

  • システムプロパティ: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • 環境変数: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

Web フレームワークの互換性

dd-java-agent には、次の Web フレームワークの自動トレースのサポートが含まれます。

Web フレームワークのトレーシングでは以下の確認が可能です。

  • HTTP リクエストの応答タイミング
  • HTTP リクエスト用のタグ (ステータスコード、メソッドなど)
  • エラーとスタックトレースの取得
  • Web リクエスト内で作成された作業と分散型トレーシングの関連付け
サーバーバージョンサポートの種類インスツルメンテーション名 (構成で使用される)
Akka-Http サーバー10.0+完全対応akka-http, akka-http-server
Apache Pekko1.0+完全対応pekko-http, pekko-http-server
Finatra Web2.9+完全対応finatra
Grizzly2.0+完全対応grizzly
Grizzly-HTTP2.3.20+完全対応grizzly-filterchain
Java Servlet 互換2.3+、3.0+完全対応servletservlet-2servlet-3
Jax-RS アノテーションJSR311-API完全対応jax-rsjaxrsjax-rs-annotationsjax-rs-filter
Jetty7.0-12.x完全対応jetty
Micronaut HTTP サーバー2.x+完全対応micronaut
Mulesoft4.5.0+完全対応mule
Netty HTTP サーバー3.8+完全対応nettynetty-3.8netty-4.0netty-4.1
Play2.3~2.8完全対応playplay-action
Ratpack1.5+完全対応ratpack
Restlet HTTP サーバー2.2~2.4完全対応restlet-http.
Spark Java2.3+プレビューsparkjava (要 jetty)
Spring Boot1.5+完全対応spring-web または spring-webflux
Spring Web (MVC)4.0+完全対応spring-web
Spring WebFlux5.0+完全対応spring-webflux
Tomcat5.5+完全対応tomcat
Undertow2.0+完全対応undertow
Vert.x3.4 ~ 5.x完全対応vertxvertx-3.4vertx-3.9vertx-4.0vertx-5.0
Websocket (JSR356)1.0+プレビューwebsocket

注: 多くのアプリケーションサーバーは Servlet 互換で、そのインスツルメンテーションによって自動的にカバーされます (Websphere、Weblogic、JBoss)。 また、Spring Boot (バージョン 3) のようなフレームワークは、通常、Tomcat、Jetty、Netty など、サポートされた組み込みアプリケーションサーバーを使用するため、本質的に機能します。

フレームワークインテグレーションがデフォルトで無効

以下のインスツルメンテーションはデフォルトでは無効になっており、以下の設定により有効にすることができます。

インスツルメンテーション有効にするには
Grizzly-Ddd.integration.grizzly-client.enabled=true
Grizzly-HTTP-Ddd.integration.grizzly-filterchain.enabled=true
Hazelcast (クライアント側のみ)-Ddd.integration.hazelcast.enabled=true
-Ddd.integration.hazelcast_legacy.enabled=true
Ignite-Ddd.integration.ignite.enabled=true
JAX-WS-Ddd.integration.jax-ws.enabled=true
JDBC Datasource-Ddd.integration.jdbc-datasource.enabled=true
Mulesoft-Ddd.integration.mule.enabled=true
Netty Promise-Ddd.integration.netty-promise.enabled=true
Ning-Ddd.integration.ning.enabled=true
Spark Java-Ddd.integration.sparkjava.enabled=true
TIBCO BusinessWorks-Ddd.integration.tibco.enabled=true
URL Connection-Ddd.integration.urlconnection.enabled=true
-Ddd.integration.httpurlconnection.enabled=true
Websocket-Ddd.trace.websocket.messages.enabled=true
ZIO-Ddd.integration.zio.experimental.enabled=true

: JAX-WS インテグレーションは、@WebService (JAX-WS 1.x) および @WebServiceProvider (JAX-WS 2.x) でアノテーションされたエンドポイントをインスツルメントします。

希望する Web フレームワークが見つかりませんか?Datadog では継続的にサポートを追加しています。サポートが必要な場合は、Datadog サポートにお問い合わせください。

ネットワーキングフレームワークの互換性

dd-java-agent には、次のネットワーキングフレームワークの自動トレースのサポートが含まれます。

ネットワーキングのトレーシングでは以下の確認が可能です。

  • リクエストの応答タイミング
  • リクエスト用のタグ (応答コードなど)
  • エラーとスタックトレースの取得
  • 分散型トレーシング
フレームワークバージョンサポートの種類インスツルメンテーション名 (構成で使用される)
Apache HTTP クライアント4.0+完全対応httpclientapache-httpclientapache-http-client
Apache HTTP 非同期クライアント4.0+完全対応httpasyncclientapache-httpasyncclient
AWS Java SDK1.11+、2.2+完全対応aws-sdk
Camel-OpenTelemetry3.12.0+プレビューopentelemetry-1
Commons HTTP クライアント2.0+完全対応commons-http-client
Google HTTP クライアント1.19.0+完全対応google-http-client
Google Pub/Sub1.116.0+完全対応google-pubsub
Grizzly HTTP クライアント1.9+プレビューgrizzly-client
gRPC1.5+完全対応grpcgrpc-clientgrpc-server
HttpURLConnectionすべて完全対応httpurlconnectionurlconnection
Kafka-Clients0.11+完全対応kafka
Kafka-Streams0.11+完全対応kafkakafka-streams
Java RMIすべて分散型トレーシング非対応rmirmi-clientrmi-server
Jax RS クライアント2.0+完全対応jax-rsjaxrsjax-rs-client
Jersey クライアント1.9 ~ 2.29完全対応jax-rsjaxrsjax-rs-client
JMS / Jakarta JMS1 ~ 3.0+完全対応jmsjms-1jms-2jakarta-jms
Netty HTTP クライアント4.0+完全対応nettynetty-4.0netty-4.1
Ning HTTP クライアント1.9.0+プレビューning
OkHTTP2.2+完全対応okhttpokhttp-2okhttp-3
Play WSClient1.0+完全対応play-ws
Rabbit AMQP2.7+完全対応amqprabbitmq
SOFA RPC5.0+完全対応sofarpc
Spring SessionAwareMessageListener3.1+完全対応spring-jms-3.1
Spring WebClient5.0+完全対応spring-webfluxspring-webflux-client

Kafka に関する注記: Datadog の Kafka インテグレーションは、ヘッダー API をサポートする Kafka のバージョン 0.11+ で機能します。この API は、トレースコンテキストの挿入と抽出に使用されます。バージョンが混在する環境でシステムを稼働させている場合は、Kafka ブローカーが Kafka のより新しいバージョンを間違って報告する場合があります。この場合、SDK がローカルのプロデューサーでサポートされていないヘッダーを挿入しようとすると問題が発生します。また、古いバージョンのコンシューマーは、ヘッダーが存在するためにメッセージを収集することができません。これらの問題を回避するために、0.11 より前のバージョンの Kafka が混在している環境では、環境変数 DD_KAFKA_CLIENT_PROPAGATION_ENABLED=false を使用してコンテキストの伝搬を無効化するようにしてください。

JMS に関する注記: Datadog の JMS インテグレーションでは、コンシューマーサービスとプロデューサーサービス間のコンテキスト伝搬を維持するために、メッセージオブジェクトプロパティ x__dash__datadog__dash__trace__dash__idx__dash__datadog__dash__parent__dash__id の追加と読み取りが自動的に行われます。

Camel に関する注記: Camel のルートを使った分散型トレースの伝搬はサポートされていません。

SOFA RPC に関する注記: Datadog の SOFA RPC インテグレーションは、トランスポートプロトコルの Bolt、Triple、REST をサポートしています。Triple は gRPC トランスポートを使用するため、Triple 呼び出しの分散型トレーシングでは、grpc インテグレーションを有効にしたままにする必要があります。

希望するネットワーキングフレームワークが見つかりませんか?Datadog では継続的にサポートを追加しています。サポートが必要な場合は、Datadog サポートにお問い合わせください。

データストアの互換性

dd-java-agent には、次のデータベースフレームワーク/ドライバーの自動トレースのサポートが含まれます。

データストアのトレーシングでは以下の確認が可能です。

  • リクエストの応答タイミング
  • クエリ情報 (サニタイジングされたクエリ文字列など)
  • エラーとスタックトレースの取得
データベースバージョンサポートの種類インスツルメンテーション名 (構成で使用される)
Aerospike4.0+完全対応aerospike
Couchbase2.0+完全対応couchbase
Cassandra3.0+完全対応cassandra
Elasticsearch Transport2.0+完全対応elasticsearchelasticsearch-transportelasticsearch-transport-{2,5,6,7} (1 つ選択)
Elasticsearch Rest5.0+完全対応elasticsearchelasticsearch-restelasticsearch-rest-{5,6,7} (1 つ選択)
Ignite2.0 ~ 3.0プレビューignite
JDBCN/A完全対応jdbcjdbc-datasource
Jedis1.4+完全対応jedisredis
Lettuce4.0+完全対応lettucelettuce-4-asynclettuce-5-rx
MongoDB3.0 ~ 4.0+完全対応mongo
OpenSearch Rest1.x ~ 2.x完全対応opensearchopensearch-rest
OpenSearch Transport1.x ~ 2.x完全対応opensearchopensearch-transport
RediScala1.5+完全対応rediscalaredis
Redisson2.x ~ 3.x完全対応redissonredis
SpyMemcached2.12+完全対応spymemcached
Vert.x Cassandra クライアント3.9 ~ 4.x完全対応cassandra
Vert.x Redis クライアント3.9 ~ 4.x完全対応vertx-redis-client
Vert.x MySQL クライアント3.9 ~ 4.x完全対応vertx-sql-client

: Redis 6.0+ は、HELLOMIGRATEACL SETUSER などのコマンドでインライン認証をサポートしています。

  • Datadog Trace Agent: 必要最小限の推奨バージョンは 7.76.1 です。これは、トレースメタデータ内の認証パラメーターが自動的に難読化されるようにするためです。
  • Datadog Lambda Extension (Serverless 環境): 必要最小限のバージョンは v28.0.0 です。

dd-java-agent は、次を含む一般的な JDBC ドライバーとも互換性があります。

  • Apache Derby
  • Firebird SQL
  • H2 データベースエンジン
  • HSQLDB
  • IBM DB2
  • MariaDB
  • MSSQL (Microsoft SQL Server)
  • MySQL
  • Oracle
  • Postgres SQL
  • ScalikeJDBC

データベースインテグレーションがデフォルトで無効

以下のインスツルメンテーションはデフォルトでは無効になっており、以下の設定により有効にすることができます。

インスツルメンテーション有効にするには
JDBC-Datasource- システムプロパティ: -Ddd.integration.jdbc-datasource.enabled=true
- 環境変数: DD_INTEGRATION_JDBC_DATASOURCE_ENABLED=true

希望するデータストアが見つかりませんか?Datadog では継続的にサポートを追加しています。サポートが必要な場合は、Datadog サポートにお問い合わせください。

その他のフレームワークの互換性

dd-java-agent には、次のフレームワークの自動トレースのサポートが含まれます。

フレームワークバージョンサポートの種類インスツルメンテーション名 (構成で使用される)
Apache CXF (Jax-WS)3.0+OpenTelemetry 拡張機能cxf
Datanucleus JDO4.0+完全対応datanucleus
Dropwizard Views0.7+完全対応dropwizarddropwizard-view
GraphQL14.0+完全対応graphql-java
Hazelcast (クライアント)3.6+プレビューhazelcasthazelcast_legacy
Hibernate3.5+完全対応hibernatehibernate-core
Hystrix1.4+完全対応hystrix
JSP Rendering2.3+完全対応jspjsp-renderjsp-compile
JUnit4.1+、5.3+完全対応junitjunit-4junit-5
Kotlin Coroutines1.3+完全対応kotlin_coroutine
Project Reactor3.1+完全対応reactor-core
Quartz2.x完全対応quartz
RxJava2.x完全対応rxjava
Spring Data1.8+完全対応spring-data
Spring Scheduling3.1+完全対応spring-scheduling
TIBCO BusinessWorks5.14.0 ~ 6.11.0プレビューtibcotibco_bw
Twilio SDK< 8.0完全対応twilio-sdk

希望するフレームワークが見つかりませんか?Datadog では継続的にサポートを追加しています。フレームワークのリクエストは、サポートチームまでお気軽にお問い合わせください。

サポートされていないフレームワークを使用したアプリケーションの可視性を向上させるには、次のことを検討してください。

インテグレーションの無効化

大半のインテグレーションはデフォルトで有効になっています。次の設定により、デフォルトを無効に変更できます。

  • システムプロパティ: -Ddd.integrations.enabled=false
  • 環境変数: DD_INTEGRATIONS_ENABLED=false

インテグレーションは個別に有効または無効にできます (上記のデフォルトを上書き)。

  • システムプロパティ: -Ddd.integration.<INTEGRATION_NAME>.enabled=true
  • 環境変数: DD_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

(各インテグレーションの名前については上記を参照してください。)

既知の問題

  • Bitbucket での Java トレーサーの実行はサポートされていません。
  • APM/トレース機能を実行する複数の Java Agent を読み込む構成は、推奨およびサポートされていません。
  • Java 24 以降で SDK を実行すると、JNI のネイティブアクセスに関連する警告が表示されることがあります。これらの警告を抑制するには --enable-native-access=ALL-UNNAMED フラグを追加します。詳細については、JEP 472 を参照してください。

事前コンパイル (AOT) クラスの読み込みとリンクのサポート

起動時間を改善するために、事前コンパイル (AOT) クラスの読み込みとリンクにより、JVM の起動時にアプリケーションクラスが、読み込まれてリンクされた状態ですぐに利用できるようになります。詳細については、JEP 483 および JEP 514 を参照してください。

要件

以下のものを使用します。

セットアップ

AOT クラスの読み込みとリンクを APM 用に設定するには、トレーニング実行時に Datadog Java SDK を追加します。

java -javaagent:/path/to/dd-java-agent.jar -XX:AOTCacheOutput=app.aot -jar App.jar

使用方法

本番環境で同じ Datadog Java SDK を、以前にキャッシュされたトレーニングデータと共に追加します。

java -javaagent:/path/to/dd-java-agent.jar -XX:AOTCache=app.aot -jar App.jar

Trace Explorer を使用してトレースを表示できます。

トレーニング実行時に Datadog Java SDK がアタッチされていない

本番環境で以下の警告が表示される場合、トレーニング時に Datadog Java SDK がアタッチされていなかったことを表します。

Mismatched values for property jdk.module.addmods: java.instrument specified during runtime but not during dump time

そのため、JVM は AOT キャッシュを使用して起動時間を改善することができません。解決策は、トレーニング時に SDK をアタッチすることです。

GraalVM Native Image のサポート

GraalVM Native Image は、Java アプリケーションをネイティブ実行可能ファイルにコンパイルする技術です。Datadog Java SDK は GraalVM Native Image をサポートしています。これにより、ライブラリが提供するトレース機能の恩恵を受けながら、アプリケーションをネイティブ実行可能ファイルにコンパイルできます。

要件

以下のものを使用します。

セットアップ

GraalVM Native Image を使用して Datadog Java SDK をセットアップするには、次の手順に従ってください。

  1. Java アプリケーションのトレースに記載されている手順に従ってアプリケーションをインスツルメントします。
  2. native-image コマンドでネイティブ実行可能ファイルをビルドする際に -J-javaagent:/path/to/dd-java-agent.jar 引数を追加します。たとえば、次のようになります。
    native-image -J-javaagent:/path/to/dd-java-agent.jar -jar App.jar
    
  3. (オプション) 次の引数を追加してプロファイラーインテグレーションを有効にします: -J-Ddd.profiling.enabled=true --enable-monitoring=jfr
    • トレーサーのバージョンが 1.39.1 より前の場合は、生成されたネイティブ実行可能ファイルを実行する際に、DD_PROFILING_START_FORCE_FIRST=true を環境変数として設定してください。

Quarkus Native を使用して Datadog Java SDK をセットアップするには、次の手順に従ってください。

  1. Java アプリケーションのトレースに記載されている手順に従ってアプリケーションをインスツルメントします。
  2. ネイティブ実行可能ファイルをビルドする際に quarkus.native.additional-build-args プロパティを使用します。たとえば、次のようになります。
    ./mvnw package -Dnative -Dquarkus.native.additional-build-args='-J-javaagent:/path/to/dd-java-agent.jar'
    
  3. (オプション) 次の引数を追加してプロファイラーインテグレーションを有効にします: -J-Ddd.profiling.enabled=true --enable-monitoring=jfr
    • トレーサーのバージョンが 1.39.1 より前の場合は、生成されたネイティブ実行可能ファイルを実行する際に、DD_PROFILING_START_FORCE_FIRST=true を環境変数として設定してください。

Spring Native を使用して Datadog Java SDK をセットアップするには、次の手順に従ってください。

  1. Java アプリケーションのトレースに記載されている手順に従ってアプリケーションをインスツルメントします。
  2. Buildpacks に基づく Spring Native ビルドの場合、BP_DATADOG_ENABLED=true を使用して Datadog 用 Paketo Buildpack を有効にします。
    • 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>
    
    • または、pack build コマンドを --env BP_DATADOG_ENABLED=true オプションと共に使用して Datadog ビルドパックを有効にできます。
  3. (オプション) プロファイラーインテグレーションを有効にするには環境変数 BP_NATIVE_IMAGE_BUILD_ARGUMENTS=’-J-Ddd.profiling.enabled=true --enable-monitoring=jfr’ を設定します。
    • トレーサーのバージョンが 1.39.1 より前の場合は、生成されたネイティブ実行可能ファイルを実行する際に、DD_PROFILING_START_FORCE_FIRST=true を環境変数として設定してください。
GraalVM 25 では、 Use of Unsafe に関連するエラーが発生することがあります。これに対処するには、ネイティブ実行可能ファイルをビルドする際に -Dnet.bytebuddy.safe=false を追加します。

使用方法

セットアップが完了すると、Datadog にトレースが送信されるはずです。

Trace Explorer を使用してトレースを表示できます。

ネイティブイメージで機能が有効化されない、または正しく構成されない

Graal Native Image を使用してビルドされたバイナリから実行時にシステムプロパティにアクセスする際に既知の問題があります。

  • ランタイム構成で、システムプロパティ (-Ddd.property.name=value) の代わりに環境変数 (DD_PROPERTY_NAME=value) を使用します。
  • このルールの例外は、プロファイラーを有効にする場合です。この場合は、_ビルド時_に native-image ツールに -J-Ddd.profiling.enabled=true を渡します。
ネイティブイメージビルドパックのバージョンが 5.12.2 未満の場合

ネイティブイメージビルドパックの古いバージョンでは、次のオプションを利用できます: USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM

このオプションが false の場合、次のような例外が発生することがあります。

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.

この問題に対する解決策は次の通りです。

  • イメージの env の構成で、USE_NATIVE_IMAGE_JAVA_PLATFORM_MODULE_SYSTEM を明示的に true に設定します。
  • または、native-image ビルドパックをバージョン 5.12.2 以降にアップグレードします。これを行う最良の方法は、java-native-image ビルドパックを 8.13.0 以降にアップグレードすることです。
Datadog 用 Paketo Buildpack のバージョンが 4.6.0 未満の場合

Datadog 用 Paketo Buildpack の古いバージョンには、次のエラーメッセージが表示されるバグがありました。

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

この問題の解決策は、バージョン 4.6.0 以降にアップグレードすることです。

Spring Native のビルドが exec.d/toggle エラーでクラッシュする

Spring Boot ネイティブイメージをビルドする際には、ビルドパックのバージョンが 4.6.0 以降でも、上記と同様のエラーが発生することがあります。

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

その原因は、通常、Datadog ビルドパックがネイティブイメージビルドパックの前に実行されたために、ネイティブイメージビルドが意図されていることが認識されないことです。その結果、最終的なネイティブ実行可能ファイルと互換性のない、JVM ビルド用のトグルスクリプトが誤って追加されます。

解決策は、spring-boot-maven-plugin の構成で BP_NATIVE_IMAGE 環境変数を明示的に true に設定することです。これにより、すべてのビルドパックで、ネイティブイメージビルドであることが最初から認識されるようになります。

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <configuration>
        <image>
          ...
          <env>
            ...
            <BP_NATIVE_IMAGE>true</BP_NATIVE_IMAGE>
            ...
          </env>
        </image>
      </configuration>
    </plugin>
  </plugins>
</build>
Datadog SDK のアクティブ化に関する問題

トレーサーの構成が Unix ドメインソケット (UDS) に依存している場合、初期化エラーが発生する可能性があります。UDS は、ネイティブイメージではサポートされていません。

dd.trace 2024-12-30 08:34:43:306 +0000] [main] WARN datadog.trace.agent.tooling.nativeimage.TracerActivation - Problem activating datadog tracer
java.lang.NoClassDefFoundError: Could not initialize class jnr.unixsocket.UnixSocketChannel

解決策は、ソケットベースの通信 (socket モード) ではなくホストベースの通信 (hostip モードまたは service モード) を使用するように Java トレーサーを構成することです。

詳細については、APM と DogstatsD の通信モードの構成を参照してください。Admission Controller に依存しないセットアップについては、DD_TRACE_AGENT_URL のドキュメントを参照してください。

参考資料

お役に立つドキュメント、リンクや記事: