Java アプリケーションのトレース
ネットワーク パフォーマンス モニタリングの正式提供を開始しました! ネットワーク パフォーマンス モニタリング提供開始!

Java アプリケーションのトレース

インストールと利用開始

Datadog アカウントをお持ちの場合、アプリ内ガイドでホストベースの設定やコンテナベースの設定に関する詳細な手順をご確認いただけます。

何らかの言語で記述されたアプリケーションのトレースを始めるには、まず Datadog Agent をインストール、構成しDocker アプリケーションのトレースまたは Kubernetes アプリケーションのトレースに関する追加ドキュメントを確認します。

次に、エージェントクラスファイルが含まれる dd-java-agent.jar をダウンロードします:

wget -O dd-java-agent.jar 'https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.datadoghq&a=dd-java-agent&v=LATEST'

最後に、アプリケーションの起動時に IDE、Maven または Gradle アプリケーションスクリプト、または java -jar コマンドに次の JVM 引数を追加します:

-javaagent:/path/to/the/dd-java-agent.jar

:

  • -javaagent-jar ファイルより前に実行され、アプリケーション引数ではなく JVM オプションとして追加される必要があります。詳しくは、Oracle ドキュメントを参照してください。

  • dd-trace-java の成果物 (dd-java-agent.jardd-trace-api.jardd-trace-ot.jar) は、すべての JVM ベース言語、つまり Scala、Groovy、Kotlin、Clojure などをサポートします。特定のフレームワークのサポートが必要な場合は、オープンソースの貢献を行うことを検討してください。

自動でデータと収集

Java の自動インスツルメンテーションは、JVM によって提供される java-agent インスツルメンテーション機能を使用します。java-agent が登録されている場合、これにはロード時間にクラスファイルを変更する能力があります。 java-agentByte Buddy フレームワークを使ってインスツルメンテーションに対して定義されたクラスを見つけ、必要に応じてこのクラスバイトを変更します。

インスツルメンテーションの由来は自動インスツルメンテーション、OpenTracing api、または両者の混合になる場合があります。一般的に、インスツルメンテーションは次の情報を取得します:

  • OpenTracing api からタイムスタンプが提供されない限り、JVM のナノタイムクロックを使ってタイミング時間が取得されます
  • キー/値タグペア
  • アプリケーションによって処理されていないエラーとスタックトレース
  • システムを通過するトレース (リクエスト) の合計数

互換性

Datadog は、Oracle JDK と OpenJDK の両方の Java JRE 1.7 以上を公式にサポートしています。Datadog は Java のアーリーアクセスバージョンを公式にサポートしていません。

インテグレーション

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

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

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

  • システムプロパティ: -Ddd.integration.<インテグレーション名>.enabled=true
  • 環境変数: DD_INTEGRATION_<インテグレーション名>_ENABLED=true

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

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

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

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

サーバーバージョンサポートの種類インスツルメンテーション名 (コンフィギュレーションに使用)
Akka-Http サーバー10.0+完全対応akka-httpakka-http-server
Finatra Web2.9+完全対応finatra
Grizzly2.0+ベータgrizzly
Java Servlet 互換2.3+、3.0+完全対応servletservlet-2servlet-3
Jax-RS アノテーションJSR311-API完全対応jax-rsjaxrsjax-rs-annotations
Jetty (非 Servlet)8+ベータjettyjetty-8
Netty HTTP サーバー4.0+完全対応nettynetty-4.0netty-4.1
Play2.4-2.7完全対応play
Ratpack1.4+完全対応ratpack
Spark Java2.3+ベータsparkjava (要 jetty)
Spring Web (MVC)4.0+完全対応spring-web
Spring WebFlux5.0+完全対応spring-webflux

ウェブフレームワークトレースは次を提供します: HTTP リクエストから応答までの時間、HTTP リクエストのタグ (ステータスコード、メソッドなど)、エラーおよびスタックトレースの取得、ウェブリクエスト内で作成された作業のリンク、分散型トレーシング

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

ベータインスツルメンテーションはデフォルトで無効になっています。有効にするには、次のいずれかのコンフィギュレーションを追加します:

  • システムプロパティ: -Ddd.integration.<インテグレーション名>.enabled=true
  • 環境変数: DD_INTEGRATION_<インテグレーション名>_ENABLED=true

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

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

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

フレームワークバージョンサポートの種類インスツルメンテーション名 (コンフィギュレーションに使用)
Apache HTTP クライアント4.0+完全対応httpclient
Apache HTTP 非同期クライアント4.0+完全対応httpasyncclientapache-httpasyncclient
AWS Java SDK1.11+、2.2+完全対応aws-sdk
Google HTTP クライアント1.19.0+完全対応google-http-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+完全対応jax-rsjaxrsjax-rs-client
JMS1 と 2完全対応jms
Netty HTTP クライアント4.0+完全対応nettynetty-4.0netty-4.1
OkHTTP3.0+完全対応okhttpokhttp-3
Play WSClient1.0+完全対応play-ws
Rabbit AMQP2.7+完全対応amqprabbitmq
Spring WebClient5.0+完全対応spring-webfluxspring-webflux-client

ネットワーキングトレースは次を提供します: リクエストから応答までの時間、リクエストのタグ (例: 応答コード)、エラーおよびスタックトレースの取得、分散型トレーシング

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

データストアの互換性

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

データベースバージョンサポートの種類インスツルメンテーション名 (コンフィギュレーションに使用)
Couchbase2.0+完全対応couchbase
Cassandra3.X完全対応cassandra
Elasticsearch Transport2.0+完全対応elasticsearchelasticsearch-transportelasticsearch-transport-{2,5,6} (1 つ選択)
Elasticsearch Rest5.0+完全対応elasticsearchelasticsearch-restelasticsearch-rest-5elasticsearch-rest-6
JDBCN/A完全対応jdbc
Jedis1.4+完全対応redis
Lettuce5.0+完全対応lettuce
MongoDB3.0+完全対応mongo
SpyMemcached2.12+完全対応spymemcached

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

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

データストアトレースは次を提供します: リクエストから応答までの時間、クエリ情報 (例: サニタイジングされたクエリ文字列)、エラーおよびスタックトレースの取得

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

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

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

フレームワークバージョンサポートの種類インスツルメンテーション名 (コンフィギュレーションに使用)
Dropwizard Views0.7+完全対応dropwizarddropwizard-view
Hibernate3.5+完全対応hibernate
Hystrix1.4+完全対応hystrix
JSP Rendering2.3+完全対応jspjsp-render
Slf4J MDC1+完全対応mdc (dd.logs.injection 構成も参照してください)
Spring Data1.8+完全対応spring-data
Twilio SDK0+完全対応twilio-sdk

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

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

  • カスタムインスツルメンテーションの追加 (OpenTracing または @Trace アノテーション)。
  • 将来のリリースに含めるためのインスツルメンテーションによるプルリクエストの送信
  • Datadog サポートへのお問い合わせと機能リクエストの提供。

コンフィギュレーション

トレーサーは、システムプロパティと環境変数を使って次のように構成されます: (上記のインテグレーションセクションのインテグレーション固有の構成を参照してください。)

システムプロパティ環境変数デフォルト説明
dd.trace.enabledDD_TRACE_ENABLEDtruefalse トレースエージェントが無効の時
dd.trace.configDD_TRACE_CONFIGnull構成プロパティが行ごとに 1 つ提供されている、ファイルへのオプションパス。たとえば、ファイルパスは -Ddd.trace.config=<ファイルパス>.properties 経由として、ファイルのサービス名に dd.service.name=<サービス名> を設定して提供することができます。
dd.service.nameDD_SERVICE_NAMEunnamed-java-app同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。
dd.service.mappingDD_SERVICE_MAPPINGnull(例: mysql:my-service-name-db) コンフィギュレーション経由でサービス名を動的に変更します。サービス間でデータベースの名前を区別する場合に便利です。
dd.writer.typeDD_WRITER_TYPEDDAgentWriterデフォルト値はトレースを Agent に送信します。代わりに LoggingWriter で構成すると、トレースがコンソールに書き出されます。
dd.agent.hostDD_AGENT_HOSTlocalhostトレースの送信先のホスト名。コンテナ化された環境を使う場合は、これを構成してホスト IP にします。詳しくは、Docker アプリケーションのトレースを参照してください。
dd.trace.agent.portDD_TRACE_AGENT_PORT8126構成されたホストに対して Agent がリッスンしているポート番号。
dd.trace.agent.unix.domain.socketDD_TRACE_AGENT_UNIX_DOMAIN_SOCKETnullこれは、トレーストラフィックをプロキシに送り、その後リモート Datadog Agent に送信するために使うことができます。
dd.trace.global.tagsDD_TRACE_GLOBAL_TAGSnull(例: key1:value1,key2:value2) すべてのスパンとすべての JMX メトリクスに追加されるデフォルトタグのリスト。この値は trace.span.tagstrace.jmx.tags にマージされ、1 つの場所で両方を構成することができます。
dd.trace.span.tagsDD_TRACE_SPAN_TAGSnull(例: key1:value1,key2:value2) すべてのスパンに追加されるデフォルトタグのリスト。同じ名前のタグがスパンに直接追加された場合、ここのデフォルトは上書きされます。
dd.trace.jmx.tagsDD_TRACE_JMX_TAGSnull(例: key1:value1,key2:value2) すべての JMX メトリクスに追加されるデフォルトタグのリスト。同じ名前のタグが JMX メトリクスに追加された場合、ここのデフォルトは上書きされます。
dd.trace.header.tagsDD_TRACE_HEADER_TAGSnull(例: CASE-insensitive-Header:my-tag-name,User-ID:userId) 名前をタグ付けするヘッダーキーのマップ。ヘッダー値がトレースのタグとして自動的に提供されます。
dd.trace.annotationsDD_TRACE_ANNOTATIONS(こちらを参照)(例: com.some.Trace;io.other.Trace) @Trace として処理するメソッドアノテーションのリスト。
dd.trace.methodsDD_TRACE_METHODSnull(例: package.ClassName[method1,method2,...];AnonymousClass$1[call]) トレースするクラス/インターフェイスとメソッドのリスト。@Trace の追加と似ていますが、コードの変更はありません。
dd.trace.partial.flush.min.spansDD_TRACE_PARTIAL_FLUSH_MIN_SPANS1000フラッシュする部分スパンの数を設定します。大量のトラフィック処理や長時間のトレース実行時にメモリのオーバーヘッドを軽減する際に役立ちます。
dd.trace.report-hostnameDD_TRACE_REPORT_HOSTNAMEfalse有効にすると、検出されたホスト名がトレースメタデータに追加されます
dd.trace.split-by-tagsDD_TRACE_SPLIT_BY_TAGSnull(例: aws.service) 対応するサービスタグで特定されるよう、スパンの名前を変えるために使われます
dd.trace.db.client.split-by-instanceDD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCEfalsetrue に設定すると、db スパンにインスタンス名がサービス名として割り当てられます
dd.trace.health.metrics.enabledDD_TRACE_HEALTH_METRICS_ENABLEDfalsetrue に設定すると、トレーサーヘルスメトリクスが送信されます
dd.trace.health.metrics.statsd.hostDD_TRACE_HEALTH_METRICS_STATSD_HOSTdd.jmxfetch.statsd.host と同じヘルスメトリクスの送信先の Statsd ホスト
dd.trace.health.metrics.statsd.portDD_TRACE_HEALTH_METRICS_STATSD_PORTdd.jmxfetch.statsd.port と同じヘルスメトリクスの送信先の Statsd ポート
dd.http.client.tag.query-stringDD_HTTP_CLIENT_TAG_QUERY_STRINGfalsetrue に設定すると、クエリ文字列パラメーターとフラグメントがウェブクライアントスパンに追加されます
dd.http.client.error.statusesDD_HTTP_CLIENT_ERROR_STATUSESfalse許容可能なエラーの範囲。デフォルトで 4xx エラーはエラーとしてレポートされません。このコンフィギュレーションはこれをオーバーライドします。例: dd.http.client.error.statuses=400-499
dd.http.server.tag.query-stringDD_HTTP_SERVER_TAG_QUERY_STRINGfalsetrue に設定すると、クエリ文字列パラメーターとフラグメントがウェブサーバースパンに追加されます
dd.jmxfetch.enabledDD_JMXFETCH_ENABLEDtrueJava トレースエージェントによる JMX メトリクスの収集を有効にします。
dd.jmxfetch.config.dirDD_JMXFETCH_CONFIG_DIRnull(例: /opt/datadog-agent/etc/conf.d) JMX メトリクスコレクションの追加構成ディレクトリ。Java エージェントは yaml ファイルの instance セクションの jvm_direct:true を探してコンフィギュレーションを変更します。
dd.jmxfetch.configDD_JMXFETCH_CONFIGnull(例: activemq.d/conf.yaml,jmx.d/conf.yaml) JMX メトリクスコレクションの追加メトリクス構成ファイル。Java エージェントは yaml ファイルの instance セクションの jvm_direct:true を探してコンフィギュレーションを変更します。
dd.jmxfetch.check-periodDD_JMXFETCH_CHECK_PERIOD1500JMX メトリクスの送信頻度 (ms)。
dd.jmxfetch.refresh-beans-periodDD_JMXFETCH_REFRESH_BEANS_PERIOD600利用可能な JMX Bean のリストのリフレッシュ頻度 (秒)。
dd.jmxfetch.statsd.hostDD_JMXFETCH_STATSD_HOSTagent.host と同じJMX メトリクスの送信先の Statsd ホスト
dd.jmxfetch.statsd.portDD_JMXFETCH_STATSD_PORT8125JMX メトリクスの送信先の Statsd ポート
dd.logs.injectionDD_LOGS_INJECTIONfalseDatadog トレース ID とスパン ID に対する自動 MDC キー挿入の有効化。詳しくは、高度な使用方法を参照してください

:

構成例:

dd.trace.enabled

システムプロパティとデバッグアプリのモードの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.trace.enabled=false -Ddatadog.slf4j.simpleLogger.defaultLogLevel=debug -jar path/to/application.jar

デバッグアプリのログに、Tracing is disabled, not installing instrumentations. と表示されます。

dd.service.name

システムプロパティの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -jar path/to/application.jar

dd.service.mapping

システムプロパティの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -Ddd.service.mapping=postgresql:web-app-pg -jar path/to/application.jar

dd.trace.global.tags

スパンと JMX メトリクスにグローバルな env を設定:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -Ddd.trace.global.tags=env:dev -jar path/to/application.jar

dd.trace.span.tags

すべてのスパンに project:test を追加する例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -Ddd.trace.global.tags=env:dev -Ddd.trace.span.tags=project:test -jar path/to/application.jar

dd.trace.jmx.tags

JMX メトリクスに custom.type:2 を設定:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -Ddd.trace.global.tags=env:dev -Ddd.trace.span.tags=project:test -Ddd.trace.jmx.tags=custom.type:2 -jar path/to/application.jar

dd.trace.methods

システムプロパティの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.trace.global.tags=env:dev -Ddd.service.name=web-app -Ddd.trace.methods=notes.app.NotesHelper[customMethod3] -jar path/to/application.jar

dd.trace.db.client.split-by-instance

システムプロパティの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.trace.global.tags=env:dev -Ddd.service.name=web-app -Ddd.trace.db.client.split-by-instance=TRUE -jar path/to/application.jar

これで、DB インスタンス 1 である webappdb に、db.instance スパンのメタデータと同じサービス名が付けられます:

これで、DB インスタンス 2 である secondwebappdb に、db.instance スパンのメタデータと同じサービス名が付けられます:

同様に、サービスマップで、1 つの Web アプリが 2 つの異なる Postgres データベースに呼び出しを行っていることがわかります。

dd.http.server.tag.query-string

システムプロパティの例:

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service.name=web-app -Ddd.trace.global.tags=env:dev -Ddd.http.server.tag.query-string=TRUE -jar path/to/application.jar

B3 ヘッダーの抽出と挿入

Datadog APM トレーサーは、分散型トレーシングの B3 ヘッダーの抽出と挿入をサポートしています。

分散したヘッダーの挿入と抽出は、挿入/抽出スタイルを構成することで制御されます。現在、次の 2 つのスタイルがサポートされています:

  • Datadog: Datadog
  • B3: B3

挿入スタイルは次を使って構成できます:

  • システムプロパティ: -Ddd.propagation.style.inject=Datadog,B3
  • 環境変数: DD_PROPAGATION_STYLE_INJECT=Datadog,B3

プロパティまたは環境変数の値は、挿入が有効になっているヘッダースタイルのカンマ (またはスペース) 区切りリストです。デフォルトでは、Datadog 挿入スタイルのみが有効になっています。

抽出スタイルは次を使って構成できます:

  • システムプロパティ: -Ddd.propagation.style.extract=Datadog,B3
  • 環境変数: DD_PROPAGATION_STYLE_EXTRACT=Datadog,B3

プロパティまたは環境変数の値は、抽出が有効になっているヘッダースタイルのカンマ (またはスペース) 区切りリストです。デフォルトでは、Datadog 抽出スタイルのみが有効になっています。

複数の抽出スタイルが有効になっている場合、抽出試行はスタイルの構成順で実行され、最初に成功した抽出値が使われます。

トレースのレポート

Datadog にトレースをレポートすると、次のことが発生します:

  • トレースが完了します
  • トレースはトレースの非同期キューにプッシュされます
    • キューのサイズには制限があり、設定された上限である 7000 件のトレースを超えて拡大することはありません
    • サイズの上限に達すると、トレースは破棄されます
    • 正確なスループットを実現するため、トレースの合計数が取得されます
  • 独立したレポートスレッドで、トレースキューがフラッシュされ、トレースが msgpack 経由でエンコードされ、その後 http 経由で Datadog Agent に送信されます
  • キューのフラッシュが 1 秒に 1 回のスケジュールで発生します

Datadog がサポートするライブラリやフレームワークの実際のコード、ドキュメント、使用例を確認したい場合は、インテグレーションセクションの Java アプリケーションの自動インスツルメンテーションされたコンポーネントの全一覧を参照してください。

トレースアノテーション

プロジェクトに dd-trace-api 依存関係を追加します。Maven の場合、次を pom.xml に追加します:

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>dd-trace-api</artifactId>
    <version>{バージョン}</version>
</dependency>

Gradle の場合は、次を追加します:

compile group: 'com.datadoghq', name: 'dd-trace-api', version: {}

次に @Trace をメソッドに追加して、dd-java-agent.jar での実行時にメソッドがトレースされるようにします。Agent が添付されていない場合は、このアノテーションはアプリケーションに影響しません。

@Trace アノテーションにはデフォルトのオペレーション名 trace.annotation がある一方、トレースされるメソッドにはデフォルトでリソースがあります。

パフォーマンス

Java APM がアプリケーションのオーバーヘッドに与える影響は最小限です:

  • Java APM によって維持されるコレクションがメモリで無制限に拡大することはありません
  • トレースのレポートによってアプリケーションスレッドがブロックされることはありません
  • Java APM は、トレースコレクションとライブラリのインスツルメンテーションのために追加クラスをロードします
  • 通常、Java APM による CPU 使用率の上昇は 3% 以内です
  • 通常、Java APM による JVM ヒープ使用率の上昇は 3% 以内です

Agent ホスト名の変更

アプリケーションレベルのトレーサーを設定し、以下のカスタム Agent ホスト名にトレースを送信します。

Java Tracing Module が自動的に検索し環境変数の DD_AGENT_HOSTDD_TRACE_AGENT_PORT で初期化します。

java -javaagent:<DD-JAVA-エージェントパス>.jar -jar <アプリケーションパス>.jar

システムプロパティを使うこともできます:

java -javaagent:<DD-JAVA-エージェントパス>.jar \
     -Ddd.agent.host=$DD_AGENT_HOST \
     -Ddd.agent.port=$DD_TRACE_AGENT_PORT \
     -jar <アプリケーションパス>.jar

その他の参考資料