- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
このチュートリアルでは、コンテナにインストールされたサンプル Java アプリケーションでトレースを有効にするための手順を説明します。このシナリオでは、Datadog Agent はコンテナにもインストールされています。
ホスト上のアプリケーションと Agent、コンテナ内のアプリケーションとホスト上の Agent、クラウドインフラストラクチャー上のアプリケーションと Agent、他の言語で書かれたアプリケーションなど、他のシナリオについては、その他のトレース有効化のチュートリアルを参照してください。
Java の一般的なトレース設定ドキュメントについては、Java アプリケーションのトレースを参照してください。
このチュートリアルのコードサンプルは、GitHub の github.com/DataDog/apm-tutorial-java-host にあります。まずは、このリポジトリを複製してください。
git clone https://github.com/DataDog/apm-tutorial-java-host.git
このリポジトリには、Docker コンテナ内で実行できるようにあらかじめ構成されたマルチサービスの Java アプリケーションが含まれています。サンプルアプリは、データの追加や変更を行うための REST API を備えた基本的なノートアプリです。docker-compose
の YAML ファイルは docker
ディレクトリに配置されます。
このチュートリアルでは、アプリケーションと Datadog Agent の両方のコンテナをビルドする all-docker-compose.yaml
ファイルを使用します。
notes
と calendar
の各ディレクトリには、アプリケーションをビルドするための Dockerfile が、Maven と Gradle の 2 つのセットで用意されています。このチュートリアルでは Maven を使用しますが、Gradle に慣れている場合は、ビルドコマンドを変更することで、Maven の代わりに Gradle を使用することができます。
アプリケーションのコンテナを構築するには、/docker
ディレクトリの中から以下を実行します。
docker-compose -f all-docker-compose.yaml build notes
ビルドに失敗した場合は、Ctrl+C
で終了し、コマンドを再実行してください。
コンテナを起動します。
docker-compose -f all-docker-compose.yaml up notes
docker ps
コマンドで実行中のコンテナを表示することで、実行されていることを確認することができます。
別のターミナルを開いて、アプリを行使するために API リクエストを送信します。ノートアプリケーションは、同じコンテナで実行されているメモリ内 H2 データベースにデータを保存する REST API です。これにいくつかのコマンドを送信します。
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"}]
アプリケーションの実行を確認したら、それを停止して、トレースを有効にします。
コンテナを停止します。
docker-compose -f all-docker-compose.yaml down
コンテナを削除します。
docker-compose -f all-docker-compose.yaml rm
Java アプリケーションが動作するようになったので、トレースを有効にするための構成を行います。
Java tracing パッケージをプロジェクトに追加します。Agent はコンテナで動作するため、Dockerfile が適切に構成されていることを確認し、何もインストールする必要はありません。notes/dockerfile.notes.maven
ファイルを開き、dd-java-agent
をダウンロードする行のコメントを解除します。
RUN curl -Lo dd-java-agent.jar https://dtdg.co/latest-java-tracer
同じ notes/dockerfile.notes.maven
ファイル内で、トレースなしで実行するための ENTRYPOINT
行をコメントアウトしてください。次に、トレースを有効にしてアプリケーションを実行する ENTRYPOINT
行のコメントを解除します。
ENTRYPOINT ["java" , "-javaagent:../dd-java-agent.jar", "-Ddd.trace.sample.rate=1", "-jar" , "target/notes-0.0.1-SNAPSHOT.jar"]
これにより、アプリケーションは自動的に Datadog のサービスにインスツルメンテーションされます。
異なるバージョンやデプロイ環境間でトレースされたサービスを識別する統合サービスタグにより、Datadog 内で相関が取れるようになり、検索やフィルターに利用できるようになります。統合サービスタグ付けに使用する環境変数は、DD_SERVICE
、DD_ENV
、DD_VERSION
の 3 つです。Docker でデプロイされたアプリケーションの場合、これらの環境変数を Dockerfile または docker-compose
ファイル内に追加することができます。
このチュートリアルでは、all-docker-compose.yaml
ファイルにこれらの環境変数がすでに定義されています。
environment:
- DD_SERVICE=notes
- DD_ENV=dev
- DD_VERSION=0.0.1
また、同じユニバーサルサービスタグの service
、env
、version
の値に対する Docker ラベルが Dockerfile に設定されていることがわかります。これにより、アプリケーションを起動したら Docker メトリクスを取得することもできます。
labels:
- com.datadoghq.tags.service="notes"
- com.datadoghq.tags.env="dev"
- com.datadoghq.tags.version="0.0.1"
all-docker-compose.yaml
ファイルのサービスセクションに Datadog Agent を追加し、ビルドに Agent を追加します。
Agent の構成のコメントを解除し、自分の Datadog API キーとサイトを指定します。
datadog-agent:
container_name: datadog-agent
image: "gcr.io/datadoghq/agent:latest"
pid: host
environment:
- DD_API_KEY=<DD_API_KEY_HERE>
- DD_SITE=datadoghq.com # Default. Change to eu.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com as appropriate for your org
- DD_APM_ENABLED=true
- DD_APM_NON_LOCAL_TRAFFIC=true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /proc/:/host/proc/:ro
- /sys/fs/cgroup:/host/sys/fs/cgroup:ro
notes
コンテナ内の datadog-agent
の depends_on
フィールドのコメントを解除してください。
notes
サービスセクションで、DD_AGENT_HOST
環境変数に Agent コンテナのホスト名が設定されていることに注目してください。notes
コンテナセクションはこのようになります。
notes:
container_name: notes
restart: always
build:
context: ../
dockerfile: notes/dockerfile.notes.maven
ports:
- 8080:8080
labels:
- com.datadoghq.tags.service="notes"
- com.datadoghq.tags.env="dev"
- com.datadoghq.tags.version="0.0.1"
environment:
- DD_SERVICE=notes
- DD_ENV=dev
- DD_VERSION=0.0.1
- DD_AGENT_HOST=datadog-agent
# - CALENDAR_HOST=calendar
depends_on:
# - calendar
- datadog-agent
このチュートリアルの後半で、calendar
セクションと変数を構成することになります。
トレーシングライブラリがインストールされたので、アプリケーションを再起動し、トレースの受信を開始します。以下のコマンドを実行します。
docker-compose -f all-docker-compose.yaml build notes
docker-compose -f all-docker-compose.yaml up notes
Agent が動作しているかどうかは、ターミナルで連続出力を観察するか、Datadog のイベントエクスプローラーを開いて Agent の開始イベントを確認することで分かります。
アプリケーションを起動した状態で、いくつかの 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 の APM > Traces にアクセスすると、API 呼び出しに対応するトレースの一覧が表示されます。
h2
はこのチュートリアルのために埋め込まれたインメモリデータベースで、notes
は Spring Boot アプリケーションです。トレースリストには、すべてのスパン、いつ開始したか、どのリソースがスパンで追跡されたか、どれくらいの時間がかかったか、が表示されます。
もし、数分待ってもトレースが表示されない場合は、Traces Search フィールドのフィルターをクリアしてください (使用していない ENV
などの環境変数にフィルターをかけている場合があります)。
Traces ページで、POST /notes
トレースをクリックすると、各スパンにかかった時間や、あるスパンが完了する前に他のスパンが発生したことを示すフレームグラフが表示されます。グラフの上部にあるバーは、前の画面で選択したスパンです (この場合、ノートアプリケーションへの最初のエントリポイントです)。
バーの幅は、それが完了するまでにかかった時間を示します。低い深さのバーは、高い深さのバーの寿命の間に完了するスパンを表します。
POST
トレースのフレームグラフは次のようになります。
GET /notes
トレースは次のようになります。
Java トレーシングライブラリは、Java のビルトイン Agent とモニタリングのサポートを利用します。Dockerfile のフラグ -javaagent:../dd-java-agent.jar
は、JVM が Java Agent として実行できるように、Java トレーシングライブラリをどこで見つけるかを指示します。Java Agent については、https://www.baeldung.com/java-instrumentation で詳しく説明されています。
dd.trace.sample.rate
フラグは、このアプリケーションのサンプルレートを設定します。Dockerfile の ENTRYPOINT コマンドでは、この値を 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();
}
notes/pom.xml
を開き、手動トレースの依存関係を構成する行のコメントを解除して、Maven ビルドを更新します。dd-trace-api
ライブラリは @Trace
アノテーションに使用され、opentracing-util
と opentracing-api
は手動でスパンを作成するために使用されます。
コンテナを再構築します。
docker-compose -f all-docker-compose.yaml build notes
docker-compose -f all-docker-compose.yaml up notes
いくつかの HTTP リクエスト、特にいくつかの GET
リクエストを再送します。
トレースエクスプローラーで、新しい GET
リクエストの 1 つをクリックすると、次のようなフレームグラフが表示されます。
getAll
関数にカスタムトレースが追加され、スタックトレースがより詳細になったことに注意してください。
手動でスパンを作成した privateMethod
は、他のコールとは別のブロックとして表示され、別の色でハイライトされています。@Trace
アノテーションを使用した他のメソッドは、GET
リクエスト (notes
アプリケーション) と同じサービス、同じ色で表示されます。カスタムインスツルメンテーションは、ハイライトして監視する必要があるコードの重要な部分がある場合に有効です。
詳しくは、カスタムインストルメンテーションをご覧ください。
単一のアプリケーションをトレースすることは素晴らしいスタートですが、トレースの本当の価値は、リクエストがサービスを通じてどのように流れるかを見ることです。これは、_分散型トレーシング_と呼ばれています。
サンプルプロジェクトには calendar
という 2 番目のアプリケーションが含まれており、呼び出されるたびにランダムな日付を返します。Notes アプリケーションの POST
エンドポイントには、add_date
という名前の 2 つ目のクエリパラメーターがあります。このパラメータが y
に設定されると、Notes はカレンダーアプリケーションを呼び出して、ノートに追加する日付を取得します。
ノートアプリと同様に、Dockerfile の起動コマンドに dd-java-agent
を追加して、トレース用のカレンダーアプリの構成を確認します。calendar/Dockerfile.calendar.maven
を開き、すでに dd-java-agent
がダウンロードされていることを確認します。
RUN curl -Lo dd-java-agent.jar https://dtdg.co/latest-java-tracer
同じ calendar/dockerfile.calendar.maven
ファイル内で、トレースなしで実行するための ENTRYPOINT
行をコメントアウトしてください。次に、トレースを有効にしてアプリケーションを実行する ENTRYPOINT
行のコメントを解除します。
ENTRYPOINT ["java" , "-javaagent:../dd-java-agent.jar", "-Ddd.trace.sample.rate=1", "-jar" , "target/calendar-0.0.1-SNAPSHOT.jar"]
docker/all-docker-compose.yaml
を開き、calendar
サービス用の環境変数のコメントを解除して、アプリ用の Agent ホストと Docker 用の統合サービスタグをセットアップします。
calendar:
container_name: calendar
restart: always
build:
context: ../
dockerfile: calendar/dockerfile.calendar.maven
labels:
- com.datadoghq.tags.service="calendar"
- com.datadoghq.tags.env="dev"
- com.datadoghq.tags.version="0.0.1"
environment:
- DD_SERVICE=calendar
- DD_ENV=dev
- DD_VERSION=0.0.1
- DD_AGENT_HOST=datadog-agent
ports:
- 9090:9090
depends_on:
- datadog-agent
notes
サービスセクションで、CALENDAR_HOST
環境変数と depends_on
の calendar
エントリのコメントを解除して、2 つのアプリの間で必要な接続を行います。
notes:
...
environment:
- DD_SERVICE=notes
- DD_ENV=dev
- DD_VERSION=0.0.1
- DD_AGENT_HOST=datadog-agent
- CALENDAR_HOST=calendar
depends_on:
- calendar
- datadog-agent
コンテナを再起動し、マルチサービスアプリケーションを構築します。まず、実行中のコンテナをすべて停止します。
docker-compose -f all-docker-compose.yaml down
その後、以下のコマンドを実行して起動します。
docker-compose -f all-docker-compose.yaml build
docker-compose -f all-docker-compose.yaml up
すべてのコンテナが立ち上がった後、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"}
トレースエクスプローラーで、この最新のトレースをクリックすると、2 つのサービス間の分散型トレーシングが表示されます。
notes
アプリケーションでは何も変更していないことに注意してください。Datadog は notes
から calendar
への HTTP コールに使用される okHttp
ライブラリと、notes
と calendar
の HTTP リクエストをリッスンするために使用する Jetty ライブラリの両方を自動的にインスツルメントします。これにより、トレース情報を 1 つのアプリケーションから他のアプリケーションに渡すことができ、分散型トレースをキャプチャすることができます。
もし、期待通りのトレースが受信できない場合は、Java トレーサーのでデバッグモードを設定してください。詳しくはデバッグモードの有効化を読んでください。