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

このドキュメントは最新ではありません。最新版はこちらをクリックして英語版をご覧ください。

互換性要件

最新の 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 リポジトリを参照してください。

    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アプリケーション環境（production、staging など）
    DD_LOGS_INJECTIONdd.logs.injectionDatadog のトレース ID とスパン ID に対する MDC キーの自動挿入を有効にします。詳細については、高度な使用方法を参照してください。

    ベータ版: バージョン 1.18.3 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログ UI で DD_LOGS_INJECTION を設定できます。
    DD_PROFILING_ENABLEDdd.profiling.enabled継続的プロファイラーを有効化
    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.5、202003181415、1.3-alpha)

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

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

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

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

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

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

      Tomcat 起動スクリプトファイル (たとえば、Linux では setenv.sh) を開き、次を追加します。

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

      Windows では、setenv.bat:

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

      setenv ファイルが存在しない場合は、Tomcat プロジェクトフォルダーの ./bin ディレクトリで作成します。

      • スタンドアロンモードの場合:

        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 クロックを使ってタイミング時間が取得されます
      • キー/値タグペア
      • アプリケーションによって処理されていないエラーとスタックトレース
      • システムを通過するトレース (リクエスト) の合計数

      セッションリプレイ

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

      その他の参考資料

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

      Datadog Java APM ソースコードGITHUB more more サービス、リソース、トレースの詳細ドキュメント more more