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

互換性要件

Java Tracing Library は、バージョン 7 以降のすべてのプラットフォームですべての JVM をサポートします。Continuous Profiler でトレースを利用するには、OpenJDK 11 以降、Oracle Java 11 以降、ほとんどのベンダー向けの OpenJDK 8 (バージョン8u262 以降)、および Zulu Java 8 以降 (マイナーバージョン 1.8.0_212 以降) がサポートされています。バージョン 8u272 以降、すべてのベンダーがプロファイラーでサポートされるようになります。

Scala (バージョン 2.10.x - 2.13.x)、Groovy、Kotlin、Clojure などのすべての JVM ベースの言語が、Java トレーサーとプロファイラーでサポートされています。サポート対象のライブラリの一覧については、互換性要件ページをご覧ください。

インストールと利用開始

アプリ内のドキュメントに従ってください (推奨)

Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:

• デプロイコンフィギュレーション (ホスト、Docker、Kubernetes、または Amazon ECS) を範囲とする段階的な手順。
• service、env、version タグを動的に設定します。
• セットアップ中に Continuous Profiler、トレースの 100% の取り込み、およびトレース ID 挿入を有効にします。

Java のインストール手順

もしくは、各言語で作成されたアプリケーションをトレースする場合は以下の操作を行ってください。

1. Agent クラスファイルが含まれる dd-java-agent.jar をダウンロードします:

   wget -O dd-java-agent.jar https://dtdg.co/latest-java-tracer
   

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

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

3. トレース用のコンフィギュレーションオプションを追加し、特に、サービス、環境、ログインジェクション、プロファイリング、およびオプションでランタイムメトリクス (使用予定のすべてのメトリクス) に対して、環境変数を設定しているか、システムプロパティを JVM 引数として渡していることを確認します。以下の例を参照してください。なお、アプリ内クイックスタート手順を使用すると、これらが生成されます。

APM に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は datadog.yaml ファイルの apm_enabled: true で有効になっており、localhost:8126 でトレーストラフィックをリッスンします。コンテナ化環境の場合、以下のリンクに従って、Datadog Agent 内でトレース収集を有効にします。

• Dropdown

1. メインの datadog.yaml コンフィギュレーションファイルで apm_non_local_traffic: true を設定します

2. コンテナ化された環境でトレースを受信するように Agent を構成する方法については、それぞれの説明を参照してください。

3. アプリケーションをインスツルメント化した後、トレースクライアントはデフォルトでトレースを localhost:8126 に送信します。これが正しいホストとポートでない場合は、以下の環境変数を設定して変更します。

DD_AGENT_HOST と DD_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

AWS Lambda で Datadog APM を設定するには、サーバーレス関数のトレースドキュメントを参照してください。

トレースは、Heroku、Cloud Foundry、AWS Elastic Beanstalk、Azure App Services Extension など、他の多くの環境で利用できます。

その他の環境については、その環境のインテグレーションのドキュメントを参照し、セットアップの問題が発生した場合はサポートにお問い合わせください。

Java トレーサーを JVM に追加する

アプリケーションサーバーのドキュメントを使用して、-javaagent およびその他の JVM 引数を渡す正しい方法を確認してください。一般的に使用されるフレームワークの手順は次のとおりです。

JAVA_OPTS=-javaagent:/path/to/dd-java-agent.jar

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"

set CATALINA_OPTS_OPTS=%CATALINA_OPTS_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/dd-java-agent.jar"

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/dd-java-agent.jar"

JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/dd-java-agent.jar"

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

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

注

• -javaagent 引数を java -jar コマンドに追加する場合は、-jar 引数の_前_に追加する必要があります。つまり、アプリケーション引数としてではなく、JVM オプションとして追加する必要があります。例:

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

  詳細については、Oracle のドキュメントを参照してください。

• classpath に dd-java-agent を追加しないでください。予期せぬ挙動が生じる場合があります。

自動でデータと収集

Java の自動インスツルメンテーションは、JVM によって提供される java-agent インスツルメンテーション機能を使用します。java-agent が登録されている場合は、ロード時にクラスファイルを変更することができます。

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

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

コンフィギュレーション

以下のすべてのコンフィギュレーションオプションには、同等のシステムプロパティと環境変数があります。 両方に同じキータイプが設定されている場合は、システムプロパティコンフィギュレーションが優先されます。 システムプロパティは、JVM フラグとして設定できます。

注:

• 両方に同じキータイプが設定された場合、システムプロパティコンフィギュレーションが優先されます。

• システムプロパティは JVM パラメーターとして使用できます。

• デフォルトで、アプリケーションからの JMX メトリクスは、DogStatsD によりポート 8125 で Datadog Agent に送信されます。DogStatsD が Agent に対して有効になっていることを確認してください。

  • Agent をコンテナとして実行している場合は、DD_DOGSTATSD_NON_LOCAL_TRAFFIC が true に設定されていることと、Agent コンテナでポート 8125 が開いていることを確認してください。
  • Kubernetes の場合は、DogStatsD ポートをホストポートにバインドします。ECS の場合は、タスク定義で適当なフラグを設定します。

インテグレーション

インテグレーションを無効にする方法については、インテグレーションの互換性セクションを参照してください。

例

dd.service.mapping

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

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

dd.tags

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

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

dd.trace.span.tags

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

java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.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=web-app -Ddd.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.service=web-app -Ddd.env=dev -Ddd.trace.methods="hello.GreetingController[doSomeStuff,doSomeOtherStuff];hello.Randomizer[randomize]" -jar path/to/application.jar

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

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

java -javaagent:/path/to/dd-java-agent.jar -Ddd.env=dev -Ddd.service=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=web-app -Ddd.env=dev -Ddd.http.server.tag.query-string=TRUE -jar path/to/application.jar

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.jmxfetch.config.dir and dd.jmxfetch.config

構成サンプル

• 以下のいずれかのコンビネーションを使用: DD_JMXFETCH_CONFIG_DIR=<ディレクトリパス> + DD_JMXFETCH_CONFIG=conf.yaml
• または直接指定: DD_JMXFETCH_CONFIG=<ディレクトリパス>/conf.yaml

conf.yaml で以下の内容を使用します。

init_config:
instances:
    - jvm_direct: true
      port: '<PORT>'
      conf:
          - include:
                bean:
                    - java.lang:type=MemoryPool,name=Metaspace
                attribute:
                    Usage.used:
                        metric_type: gauge
                        alias: sb.usage.used

次の結果が生成されます。

JMX フェッチを使った Java メトリクス収集についての詳細は Java インテグレーションドキュメントを参照してください。

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 の場合は、次を追加します:

implementation 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% 以内です

その他の参考資料

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

Datadog Java APM ソースコードGITHUB サービス、リソース、トレースを調査するDOCUMENTATION