互換性要件

最新の Java トレーサーは、バージョン 8 以上のすべての JVM をサポートしています。8 以下の JVM バージョンに関する追加情報は、サポートする JVM ランタイムをお読みください。

Datadog の Java バージョンとフレームワークのサポート一覧 (レガシーバージョンとメンテナンスバージョンを含む) については、互換性要件ページをご覧ください。

はじめに

作業を始める前に、Agent のインストールと構成が済んでいることを確認してください。

アプリケーションをインスツルメントする

Datadog Agent をインストールして構成したら、次はアプリケーションに直接トレーシングライブラリを追加してインスツルメントします。互換性情報の詳細をお読みください。

アプリケーションのトレースを開始するには

  1. 最新のトレーサークラスファイルを含む dd-java-agent.jar を、Datadog ユーザーがアクセス可能なフォルダにダウンロードします。
wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar

注: 特定のメジャーバージョンの最新ビルドをダウンロードするには、代わりに https://dtdg.co/java-tracer-vX リンクを使用してください。ここで X は希望するメジャーバージョンです。 例えば、バージョン 1 の最新ビルドには https://dtdg.co/java-tracer-v1 を使用します。マイナーバージョン番号は含めてはいけません。または、特定のバージョンについては Datadog の Maven リポジトリを参照してください。

Note: Release Candidate versions are made available in GitHub DataDog/dd-trace-java releases. These have “RC” in the version and are recommended for testing outside of your production environment. You can subscribe to GitHub release notifications to be informed when new Release Candidates are available for testing. If you experience any issues with Release Candidates, reach out to Datadog support.

  1. IDE、Maven または Gradle アプリケーションスクリプト、java -jar コマンドから、Continuous Profiler、デプロイ追跡、ログ挿入(Datadog へログを送信する場合)を使用してアプリケーションを実行するには、-javaagent JVM 引数と、該当する以下のコンフィギュレーションオプションを追加します。

    java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -XX:FlightRecorderOptions=stackdepth=256 -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar
    

    イメージのサイズを削減し、モジュールを省略する必要性が強い場合は、jdeps コマンドを使って依存関係を特定することができます。しかし、必要なモジュールは時間の経過とともに変更される可能性がありますので、自己責任で行ってください。

    プロファイリングを有効にすると、APM バンドルによっては料金に影響が出る場合があります。詳しくは料金ページをご覧ください。
環境変数システムプロパティ説明
DD_ENVdd.envアプリケーション環境(productionstaging など)
DD_LOGS_INJECTIONdd.logs.injectionDatadog のトレース ID とスパン ID に対する MDC キーの自動挿入を有効にします。詳細については、高度な使用方法を参照してください。

ベータ版: バージョン 1.18.3 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログ UI で DD_LOGS_INJECTION を設定できます。
DD_PROFILING_ENABLEDdd.profiling.enabledEnable the Continuous Profiler
DD_SERVICEdd.service同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。
DD_TRACE_SAMPLE_RATEdd.trace.sample.rateすべてのサービスのトレースのルートでサンプリングレートを設定します。

ベータ版: バージョン 1.18.3 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログ UI で DD_TRACE_SAMPLE_RATE を設定できます。
DD_TRACE_SAMPLING_RULESdd.trace.sampling.rules指定したルールに合致するサービスのトレースのルートでのサンプリングレートを設定します。
DD_VERSIONdd.versionアプリケーションのバージョン (例: 2.52020031814151.3-alpha)

追加のコンフィギュレーションオプション は以下で説明されています。

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

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

アプリの名前が my_app.jar の場合は、以下を含む my_app.conf を作成します。

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

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

Linux

To enable tracing when running Tomcat on Linux:

  1. Open your Tomcat startup script file, for example setenv.sh.
  2. Add the following to setenv.sh:
    CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"
    

Windows (Tomcat as a Windows service)

To enable tracing when running Tomcat as a Windows service:

  1. Open a Command Prompt.
  2. Run the following command to update your Tomcat service configuration:
    tomcat8 //US//<SERVICE_NAME> --Environment="CATALINA_OPTS=%CATALINA_OPTS% -javaagent:\"c:\path\to\dd-java-agent.jar\""
    
    Replace <SERVICE_NAME> with the name of your Tomcat service and replace the path to dd-java-agent.jar.
  3. Restart your Tomcat service for changes to take effect.

Windows (Tomcat with environment setup script)

To enable tracing when running Tomcat with an environment setup script:

  1. Create setenv.bat in the ./bin directory of the Tomcat project folder, if it doesn’t already exist.
  2. Add the following to setenv.bat:
    set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"
    

If the previous step doesn’t work, try adding the following instead:

set JAVA_OPTS=%JAVA_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"
  • スタンドアロンモードの場合:

    standalone.conf の末尾に次の行を追加します。

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/dd-java-agent.jar"
  • スタンドアロンモードと Windows の場合、standalone.conf.bat の最後に以下の行を追加します。
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/dd-java-agent.jar"
  • ドメインモードの場合:

    ファイル domain.xml の server-groups.server-group.jvm.jvm-options というタグの下に、以下の行を追加します。

<option value="-javaagent:/path/to/dd-java-agent.jar"/>

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

jetty.sh を使用して Jetty をサービスとして開始する場合は、編集して次を追加します。

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

start.ini を使用して Jetty を起動する場合は、次の行を追加します(--exec の下に。まだ存在しない場合は --exec 行を追加します)。

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

管理コンソールで:

  1. Servers を選択します。Server Type で、WebSphere application servers を選択し、サーバーを選択します。
  2. Java and Process Management > Process Definition を選択します。
  3. Additional Properties セクションで、Java Virtual Machine をクリックします。
  4. Generic JVM arguments テキストフィールドに次のように入力します。
-javaagent:/path/to/dd-java-agent.jar

詳細とオプションについては、WebSphere のドキュメントを参照してください。

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

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

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

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

自動インスツルメンテーション

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

注: リモート ClassLoader でロードされたクラスは、自動的にインスツルメンテーションされません。

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

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

構成

必要に応じて、統合サービスタグ付けの設定など、アプリケーションパフォーマンスのテレメトリーデータを送信するためのトレースライブラリーを構成します。詳しくは、ライブラリの構成を参照してください。

その他の参考資料