チュートリアル - Datadog Agent と同じホスト上の Java アプリケーションのトレースを有効にする このチュートリアルでは、ホスト上にインストールされたサンプル Java アプリケーションでトレースを有効にするための手順を説明します。このシナリオでは、アプリケーションと同じホスト上に Datadog Agent をインストールします。
コンテナ内またはクラウドインフラストラクチャーのアプリケーション、コンテナ内の Agent、異なる言語で書かれたアプリケーションなど、その他のシナリオについては、その他のトレース有効化のチュートリアル を参照してください。
Java の一般的なトレース設定ドキュメントについては、Java アプリケーションのトレース を参照してください。
Datadog のアカウントと組織の API キー Git Curl sudo を使用する場合、root 権限を持つ物理または仮想 Linux ホスト ホスト上の Java 11 互換の JDK (単なる JRE ではありません)。このチュートリアルでは、同じマシン上でビルドし、同じマシンにデプロイしています。 Datadog Agent をマシンにインストールしていない場合は、Integrations > Agent <YOUR_API_KEY> を Datadog API キー に置き換えて、以下のスクリプトを実行することで Agent をインストールすることができます。
Copy
DD_AGENT_MAJOR_VERSION = 7 DD_API_KEY = <YOUR_API_KEY> DD_SITE = "datadoghq.com" bash -c " $( curl -L https://install.datadoghq.com/scripts/install_script.sh) "
Copy
datadoghq.com 以外の Datadog サイトにデータを送信するには、DD_SITE 環境変数を Datadog サイト に置き換えてください。
Events > Explorer Datadog ソースファセットでフィルタリングし、ホストへの Agent インストールを確認するイベントを探して、Agent が実行されており、Datadog にデータを送信していることを確認します。
次に、トレースするためのサンプルアプリケーションをインストールします。このチュートリアルのコードサンプルは github.com/DataDog/apm-tutorial-java-host で見ることができます。以下を実行することで git リポジトリの複製を行います。
Copy
git clone https://github.com/DataDog/apm-tutorial-java-host.git
Copy
Maven または Gradle のどちらか使いやすい方を使用して、サンプルアプリをビルドします。apm-tutorial-java-host 内の notes ディレクトリに移動して、以下のいずれかを実行してください。
これは、Spring Boot Jar プラグインを使用して、Java アプリケーションを実行するために必要なすべてのファイルを含む単一の Jar ファイルを作成するものです。
以下を実行することでアプリケーションを起動します。
java -jar target/notes-0.0.1-SNAPSHOT.jar
java -jar build/libs/notes-0.0.1-SNAPSHOT.jar
また、OS がサポートしていれば、scripts ディレクトリに用意されている以下のスクリプトを使って、アプリケーションをビルドして実行することもできます。
sh ./scripts/gradle_run.sh
サンプルの notes_app アプリケーションは、インメモリデータベースにデータを保存する基本的な REST API です。別のターミナルを開き、curl を使っていくつかの API リクエストを送信します。
curl localhost:8080/notesまだデータベースに何もないので [] を返します curl -X POST 'localhost:8080/notes?desc=hello'ノートに hello という説明と 1 という ID 値を追加します。{"id":1,"description":"hello"} を返します。 curl localhost:8080/notes/1id の値が 1 であるノートを返します: {"id":1,"description":"hello"}curl -X POST 'localhost:8080/notes?desc=otherNote'ノートに otherNote という説明と 2 という ID 値を追加します。{"id":2,"description":"otherNote"} を返します。 curl localhost:8080/notesデータベースの内容を返します: [{"id":1,"description":"hello"},{"id";2,"description":"otherNote"}] さらに API コールを実行し、アプリケーションのアクションを確認します。終了したら、Ctrl+C でアプリケーションを停止します。
次に、Java トレーシングライブラリ (Java Agent と呼ばれることもあります) をダウンロードします。apm-tutorial-java-host ディレクトリから、以下を実行します。
Copy
curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer' If your operating system does not support curl, you can go directly to 'https://dtdg.co/latest-java-tracer' to download the dd-java-agent.jar file.
トレースの生成と収集を開始するには、Datadog にトレースデータを送信させるフラグを追加してサンプルアプリケーションを再起動します。
注 : これらのサンプルコマンドのフラグ、特にサンプルレートは、このチュートリアル以外の環境では、必ずしも適切ではありません。実際の環境で何を使うべきかについては、
トレース構成 を読んでください。
notes ディレクトリから、以下を実行します。
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= notes -Ddd.env= dev -jar -Ddd.version= 0.0.1 target/notes-0.0.1-SNAPSHOT.jar
または、提供されたスクリプトを使用します。
sh ./scripts/mvn_instrumented_run.sh
notes ディレクトリから、以下を実行します。
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= notes -Ddd.env= dev -jar -Ddd.version= 0.0.1 build/libs/notes-0.0.1-SNAPSHOT.jar
または、提供されたスクリプトを使用します。
sh ./scripts/gradle_instrumented_run.sh
再びアプリケーションにリクエストを送るには、curl を使用します。
curl localhost:8080/notes[]curl -X POST 'localhost:8080/notes?desc=hello'{"id":1,"description":"hello"}curl localhost:8080/notes/1{"id":1,"description":"hello"}curl localhost:8080/notes[{"id":1,"description":"hello"}]しばらく待って、Datadog の UI を見てみてください。APM > Traces
h2 はこのチュートリアルのために埋め込まれたメモリ内データベースで、notes は Spring Boot アプリケーションです。トレースリストには、すべてのスパン、いつ開始したか、どのリソースがスパンで追跡されたか、どれくらいの時間がかかったか、が表示されます。
もし、トレースが表示されない場合は、Traces Search フィールドのフィルターをクリアしてください (使用していない ENV などの環境変数にフィルターをかけている場合があります)。
Traces ページで、POST /notes トレースをクリックすると、各スパンにかかった時間や、あるスパンが完了する前に他のスパンが発生したことを示すフレームグラフが表示されます。グラフの上部にあるバーは、前の画面で選択したスパンです (この場合、ノートアプリケーションへの最初のエントリポイントです)。
バーの幅は、それが完了するまでにかかった時間を示します。低い深さのバーは、高い深さのバーの寿命の間に完了するスパンを表します。
POST トレースのフレームグラフは次のようになります。
GET /notes トレースは次のようになります。
Java トレーシングライブラリは、Java のビルトイン Agent とモニタリングのサポートを利用します。フラグ -javaagent:../dd-java-agent.jar は、JVM が Java Agent として実行できるように、Java トレーシングライブラリをどこで見つけるかを指示します。Java Agent については、https://www.baeldung.com/java-instrumentation で詳しく説明されています。
Java Agent を有効にする javaagent フラグに加え、起動コマンドでは、Datadog 内でアプリケーションを一意に識別するための 3 つの統合サービスタグ付け の設定を指定します。監視するアプリケーションには、必ず env、service、version タグを指定してください。
そして最後に、dd.trace.sample.rate フラグは、このアプリケーションのサンプルレートを設定します。上記の起動コマンドでは、この値を 1 に設定しています。これは、notes サービスに対する全てのリクエストの 100% が、分析と表示のために Datadog のバックエンドに送信されることを意味します。低容量のテストアプリケーションの場合、これは問題ありません。実稼働時や大量のデータを扱う環境では、このようなことはしないでください。代わりに、リクエストの一部をサンプリングします。例えば、-Ddd.trace.sample.rate=0.1 とすると、リクエストの 10% 分のトレースが Datadog に送信されます。トレース構成設定 とサンプリング機構 について詳しくお読みください。
このコマンドのフラグは -jar フラグの前に表示されていることに注意してください。これは、このフラグがアプリケーションではなく、Java Virtual Machine のパラメーターだからです。アプリケーションに Java Agent を追加するときは、このフラグを正しい場所に指定するようにしてください。
自動インスツルメンテーションは便利ですが、より細かいスパンが欲しい場合もあります。Datadog の Java DD Trace API では、アノテーションやコードを使用してコード内のスパンを指定することができます。
次のステップでは、コードにアノテーションを追加して、いくつかのサンプルメソッドをトレースする方法を説明します。
/notes/src/main/java/com/datadog/example/notes/NotesHelper.java を開きます。このサンプルには、コードにカスタムトレースを設定するさまざまな方法を示す、コメントアウトされたコードがすでに含まれています。
手動トレーシングをサポートするためのライブラリをインポートしている行のコメントを解除します。
import datadog.trace.api.Trace ;
import datadog.trace.api.DDTags ;
import io.opentracing.Scope ;
import io.opentracing.Span ;
import io.opentracing.Tracer ;
import io.opentracing.tag.Tags ;
import io.opentracing.util.GlobalTracer ;
import java.io.PrintWriter ;
import java.io.StringWriter
2 つのパブリックプロセスを手動でトレースしている行のコメントを解除します。これらは、@Trace アノテーションを使用して、operationName や resourceName などのアスペクトをトレースで指定することを示しています。
@Trace ( operationName = "traceMethod1" , resourceName = "NotesHelper.doLongRunningProcess" )
// ...
@Trace ( operationName = "traceMethod2" , resourceName = "NotesHelper.anotherProcess" )
また、アプリケーション内の特定のコードブロックに対して、別のスパンを作成することもできます。スパン内には、サービスやリソース名のタグ、エラー処理タグを追加します。これらのタグは、Datadog の視覚化でスパンとメトリクスを表示するフレームグラフになります。プライベートメソッドを手動でトレースする行のコメントを解除します。
Tracer tracer = GlobalTracer . get ();
// Tags can be set when creating the span
Span span = tracer . buildSpan ( "manualSpan1" )
. withTag ( DDTags . SERVICE_NAME , "NotesHelper" )
. withTag ( DDTags . RESOURCE_NAME , "privateMethod1" )
. start ();
try ( Scope scope = tracer . activateSpan ( span )) {
// Tags can also be set after creation
span . setTag ( "postCreationTag" , 1 );
Thread . sleep ( 30 );
Log . info ( "Hello from the custom privateMethod1" );
また、エラー時にタグを設定する行も:
} catch ( Exception e ) {
// Set error on span
span . setTag ( Tags . ERROR , true );
span . setTag ( DDTags . ERROR_MSG , e . getMessage ());
span . setTag ( DDTags . ERROR_TYPE , e . getClass (). getName ());
final StringWriter errorString = new StringWriter ();
e . printStackTrace ( new PrintWriter ( errorString ));
span . setTag ( DDTags . ERROR_STACK , errorString . toString ());
Log . info ( errorString . toString ());
} finally {
span . finish ();
}
ビルドスクリプトの構成を更新し、アプリケーションをビルドします。
a. notes/pom.xml を開き、手動トレースの依存関係を構成する行のコメントを解除します。dd-trace-api ライブラリは @Trace アノテーションに使用され、opentracing-util と opentracing-api は手動でスパンを作成するために使用されます。
b. 以下を実行します。
./mvnw clean package
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= notes -Ddd.env= dev -jar -Ddd.version= 0.0.1 target/notes-0.0.1-SNAPSHOT.jar
またはスクリプトを使用します。
sh ./scripts/mvn_instrumented_run.sh
a. notes/build.gradle を開き、手動トレースの依存関係を構成する行のコメントを解除します。dd-trace-api ライブラリは @Trace アノテーションに使用され、opentracing-util と opentracing-api は手動でスパンを作成するために使用されます。
b. 以下を実行します。
./gradlew clean bootJar
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= notes -Ddd.env= dev -jar -Ddd.version= 0.0.1 build/libs/notes-0.0.1-SNAPSHOT.jar
またはスクリプトを使用します。
sh ./scripts/gradle_instrumented_run.sh
いくつかの HTTP リクエスト、特にいくつかの GET リクエストを再送します。
トレースエクスプローラーで、新しい GET リクエストの 1 つをクリックすると、次のようなフレームグラフが表示されます。
getAll 関数にカスタムトレースが追加され、スタックトレースがより詳細になったことに注意してください。
手動でスパンを作成した privateMethod は、他のコールとは別のブロックとして表示され、別の色でハイライトされています。@Trace アノテーションを使用した他のメソッドは、GET リクエスト (notes アプリケーション) と同じサービス、同じ色で表示されます。カスタムインスツルメンテーションは、ハイライトして監視する必要があるコードの重要な部分がある場合に有効です。
詳しくは、カスタムインストルメンテーション をご覧ください。
単一のアプリケーションをトレースすることは素晴らしいスタートですが、トレースの本当の価値は、リクエストがサービスを通じてどのように流れるかを見ることです。これは、_分散型トレーシング_と呼ばれています。
サンプルプロジェクトには calendar という 2 番目のアプリケーションが含まれており、呼び出されるたびにランダムな日付を返します。Notes アプリケーションの POST エンドポイントには、add_date という名前の 2 つ目のクエリパラメーターがあります。このパラメータが y に設定されると、Notes はカレンダーアプリケーションを呼び出して、ノートに追加する日付を取得します。
サンプルリポジトリの /calendar ディレクトリに移動し、カレンダーアプリをビルドして実行します。
次を実行します。
./mvnw clean package
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= calendar -Ddd.env= dev -jar -Ddd.version= 0.0.1 target/calendar-0.0.1-SNAPSHOT.jar
またはスクリプトを使用します。
sh ./scripts/mvn_instrumented_run.sh
次を実行します。
./gradlew bootJar
java -javaagent:../dd-java-agent.jar -Ddd.trace.sample.rate= 1 -Ddd.service= calendar -Ddd.env= dev -jar -Ddd.version= 0.0.1 build/libs/calendar-0.0.1-SNAPSHOT.jar
またはスクリプトを使用します。
sh ./scripts/gradle_instrumented_run.sh
add_date パラメーターを指定して、POST リクエストを送信します。
curl -X POST 'localhost:8080/notes?desc=hello_again&add_date=y'{"id":1,"description":"hello_again with date 2022-11-06"}トレースエクスプローラーで、この最新の notes トレースをクリックすると、2 つのサービス間の分散型トレーシングが表示されます。
notes アプリケーションでは何も変更していないことに注意してください。Datadog は notes から calendar への HTTP コールに使用される okHttp ライブラリと、notes と calendar の HTTP リクエストをリッスンするために使用する Jetty ライブラリの両方を自動的にインスツルメントします。これにより、トレース情報を 1 つのアプリケーションから他のアプリケーションに渡すことができ、分散型トレースをキャプチャすることができます。
もし、期待通りのトレースが受信できない場合は、Java トレーサーのでデバッグモードを設定してください。詳しくはデバッグモードの有効化 を読んでください。
