- はじめに
- エージェント
- インテグレーション
- Watchdog
- イベント
- ダッシュボード
- モバイルアプリケーション
- インフラストラクチャー
- サーバーレス
- メトリクス
- ノートブック
- アラート設定
- APM & Continuous Profiler
- CI Visibility
- RUM & セッションリプレイ
- データベース モニタリング
- ログ管理
- セキュリティプラットフォーム
- Synthetic モニタリング
- ネットワークモニタリング
- 開発者
- API
- アカウントの管理
- データセキュリティ
- ヘルプ
Java トレーサーには、Oracle JDK または OpenJDK に Java JRE 1.7 以降が必要です。Datadog は Java のアーリーアクセスバージョンを公式にサポートしていません。サポートするライブラリの一覧については、互換性要件ページをご覧ください。
Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:
service
、env
、version
タグを動的に設定します。もしくは、各言語で作成されたアプリケーションをトレースする場合は以下の操作を行ってください。
Datadog Agent をインストール、構成します。Docker アプリケーションのトレースまたは Kubernetes アプリケーションのトレースに関する追加ドキュメントを確認します。
Agent クラスファイルが含まれる dd-java-agent.jar
をダウンロードします:
wget -O dd-java-agent.jar https://dtdg.co/latest-java-tracer
アプリケーションの起動時に IDE、Maven または Gradle アプリケーションスクリプト、または java -jar
コマンドに次の JVM 引数を追加します:
-javaagent:/path/to/the/dd-java-agent.jar
トレース用のコンフィギュレーションオプションを追加し、特に、サービス、環境、ログインジェクション、プロファイリング、およびオプションでランタイムメトリクス (使用予定のすべてのメトリクス) に対して、環境変数を設定しているか、システムプロパティを JVM 引数として渡していることを確認します。以下の例を参照してください。なお、アプリ内クイックスタート手順を使用すると、これらが生成されます。
IDE のドキュメントを使用して、-javaagent
およびその他の JVM 引数を渡す正しい方法を確認してください。一般的に使用されるフレームワークの手順は次のとおりです。
アプリの名前が my_app.jar
の場合は、以下を含む my_app.conf
を作成します。
JAVA_OPTS=-javaagent:/path/to/dd-java-agent.jar
詳細については、Spring Boot のドキュメントを参照してください。
Tomcat 起動スクリプトファイル (たとえば、catalina.sh
) を開き、次を追加します。
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"
または Windows では、catalina.bat
:
set CATALINA_OPTS_OPTS=%CATALINA_OPTS_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"
standalone.sh
の末尾に次の行を追加します。
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"
詳細については、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
管理コンソールで:
-javaagent:/path/to/dd-java-agent.jar
詳細とオプションについては、WebSphere のドキュメントを参照してください。
-javaagent
引数を java -jar
コマンドに追加する場合は、-jar
引数の_前_に追加する必要があります。つまり、アプリケーション引数としてではなく、JVM オプションとして追加する必要があります。例:
java -javaagent:/path/to/dd-java-agent.jar -jar my_app.jar
詳細については、Oracle のドキュメントを参照してください。
dd-trace-java
の成果物 (dd-java-agent.jar
、dd-trace-api.jar
、dd-trace-ot.jar
) は、すべての JVM ベース言語、つまり Scala、Groovy、Kotlin、Clojure などをサポートします。特定のフレームワークのサポートが必要な場合は、オープンソースの貢献を行うことを検討してください。
Java の自動インスツルメンテーションは、JVM によって提供される java-agent
インスツルメンテーション機能を使用します。java-agent
が登録されている場合は、ロード時にクラスファイルを変更することができます。
インスツルメンテーションの由来は自動インスツルメンテーション、OpenTracing api、または両者の混合になる場合があります。一般的に、インスツルメンテーションは次の情報を取得します:
以下のすべてのコンフィギュレーションオプションには、同等のシステムプロパティと環境変数があります。 両方に同じキータイプが設定されている場合は、システムプロパティコンフィギュレーションが優先されます。 システムプロパティは、JVM フラグとして設定できます。
システムプロパティ | 環境変数 | デフォルト | 説明 |
---|---|---|---|
dd.service | DD_SERVICE | unnamed-java-app | 同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。バージョン 0.50.1 以降で利用可能。 |
dd.tags | DD_TAGS | null | (例: layer:api,team:intake ) すべてのスパン、プロファイル、JMX メトリクスに追加されるデフォルトタグのリスト。DD_ENV または DD_VERSION が使用される場合、DD_TAGS で定義される env または version タグをオーバーライドします。バージョン 0.50.1 以降で利用可能。 |
dd.env | DD_ENV | none | アプリケーション環境(例、production、staging など)。0.48+ 以降のバージョンで利用可能。 |
dd.version | DD_VERSION | null | アプリケーションバージョン(例、2.5、202003181415、1.3-alpha など)。0.48+ 以降のバージョンで利用可能。 |
dd.logs.injection | DD_LOGS_INJECTION | false | Datadog トレース ID とスパン ID に対する自動 MDC キー挿入の有効化。詳しくは、高度な使用方法を参照してください。 |
dd.trace.config | DD_TRACE_CONFIG | null | 構成プロパティが行ごとに 1 つ提供されている、ファイルへのオプションパス。たとえば、ファイルパスは -Ddd.trace.config=<ファイルパス>.properties 経由として、ファイルのサービス名に dd.service=<SERVICE_NAME> を設定して提供することができます。 |
dd.service.mapping | DD_SERVICE_MAPPING | null | (例: mysql:my-mysql-service-name-db, postgres:my-postgres-service-name-db ) コンフィギュレーション経由でサービス名を動的に変更します。サービス間でデータベースの名前を区別する場合に便利です。 |
dd.writer.type | DD_WRITER_TYPE | DDAgentWriter | デフォルト値はトレースを Agent に送信します。代わりに LoggingWriter で構成すると、トレースがコンソールに書き出されます。 |
dd.agent.host | DD_AGENT_HOST | localhost | トレースの送信先のホスト名。コンテナ化された環境を使う場合は、これを構成してホスト IP にします。詳しくは、Docker アプリケーションのトレースを参照してください。 |
dd.trace.agent.port | DD_TRACE_AGENT_PORT | 8126 | 構成されたホストに対して Agent がリッスンしているポート番号。 |
dd.trace.agent.unix.domain.socket | DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET | null | これは、トレーストラフィックをプロキシに送り、その後リモート Datadog Agent に送信するために使うことができます。 |
dd.trace.agent.url | DD_TRACE_AGENT_URL | null | トレースを送信する URL。http:// (HTTP を使用) もしくは unix:// ( Unix ドメインソケットを使用)のいずれかで始まります。この設定は DD_AGENT_HOST および DD_TRACE_AGENT_PORT よりも優先されます。バージョン 0.65 以上で使用可能です。 |
dd.trace.agent.timeout | DD_TRACE_AGENT_TIMEOUT | 10 | Datadog Agent とのネットワークインタラクションのタイムアウト (秒)。 |
dd.trace.header.tags | DD_TRACE_HEADER_TAGS | null | (例: CASE-insensitive-Header:my-tag-name,User-ID:userId ) 名前をタグ付けするヘッダーキーのマップ。ヘッダー値がトレースのタグとして自動的に提供されます。 |
dd.trace.annotations | DD_TRACE_ANNOTATIONS | (こちらを参照) | (例: com.some.Trace;io.other.Trace ) @Trace として処理するメソッドアノテーションのリスト。 |
dd.trace.methods | DD_TRACE_METHODS | null | (例: "package.ClassName[method1,method2,...];AnonymousClass$1[call]" ) トレースするクラス/インターフェイスとメソッドのリスト。@Trace の追加と似ていますが、コードの変更はありません。 |
dd.trace.partial.flush.min.spans | DD_TRACE_PARTIAL_FLUSH_MIN_SPANS | 1000 | フラッシュする部分スパンの数を設定します。大量のトラフィック処理や長時間のトレース実行時にメモリのオーバーヘッドを軽減する際に役立ちます。 |
dd.trace.split-by-tags | DD_TRACE_SPLIT_BY_TAGS | null | (例: aws.service ) 対応するサービスタグで特定されるよう、スパンの名前を変えるために使われます |
dd.trace.db.client.split-by-instance | DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE | false | true に設定すると、db スパンにインスタンス名がサービス名として割り当てられます |
dd.trace.health.metrics.enabled | DD_TRACE_HEALTH_METRICS_ENABLED | false | true に設定すると、トレーサーヘルスメトリクスが送信されます |
dd.trace.health.metrics.statsd.host | DD_TRACE_HEALTH_METRICS_STATSD_HOST | dd.jmxfetch.statsd.host と同じ | ヘルスメトリクスの送信先の Statsd ホスト |
dd.trace.health.metrics.statsd.port | DD_TRACE_HEALTH_METRICS_STATSD_PORT | dd.jmxfetch.statsd.port と同じ | ヘルスメトリクスの送信先の Statsd ポート |
dd.http.client.tag.query-string | DD_HTTP_CLIENT_TAG_QUERY_STRING | false | true に設定すると、クエリ文字列パラメーターとフラグメントがウェブクライアントスパンに追加されます |
dd.http.client.error.statuses | DD_HTTP_CLIENT_ERROR_STATUSES | 400-499 | 許容可能なエラーの範囲。デフォルトで 4xx エラーは HTTP クライアントのエラーとしてレポートされます。このコンフィギュレーションはこれをオーバーライドします。例: dd.http.client.error.statuses=400-499 |
dd.http.server.error.statuses | DD_HTTP_SERVER_ERROR_STATUSES | 500-599 | 許容可能なエラーの範囲。デフォルトで 5xx ステータスコードは HTTP サーバーのエラーとしてレポートされます。このコンフィギュレーションはこれをオーバーライドします。例: dd.http.server.error.statuses=500-599 |
dd.http.server.tag.query-string | DD_HTTP_SERVER_TAG_QUERY_STRING | false | true に設定すると、クエリ文字列パラメーターとフラグメントがウェブサーバースパンに追加されます |
dd.trace.enabled | DD_TRACE_ENABLED | true | false トレースエージェントが無効の時 |
dd.jmxfetch.enabled | DD_JMXFETCH_ENABLED | true | Java トレースエージェントによる JMX メトリクスの収集を有効にします。 |
dd.jmxfetch.config.dir | DD_JMXFETCH_CONFIG_DIR | null | (例: /opt/datadog-agent/etc/conf.d ) JMX メトリクスコレクションの追加構成ディレクトリ。Java エージェントは yaml ファイルの instance セクションの jvm_direct:true を探してコンフィギュレーションを変更します。 |
dd.jmxfetch.config | DD_JMXFETCH_CONFIG | null | (例: activemq.d/conf.yaml,jmx.d/conf.yaml ) JMX メトリクスコレクションの追加メトリクス構成ファイル。Java エージェントは yaml ファイルの instance セクションの jvm_direct:true を探してコンフィギュレーションを変更します。 |
dd.jmxfetch.check-period | DD_JMXFETCH_CHECK_PERIOD | 1500 | JMX メトリクスの送信頻度 (ms)。 |
dd.jmxfetch.refresh-beans-period | DD_JMXFETCH_REFRESH_BEANS_PERIOD | 600 | 利用可能な JMX Bean のリストのリフレッシュ頻度 (秒)。 |
dd.jmxfetch.statsd.host | DD_JMXFETCH_STATSD_HOST | agent.host と同じ | JMX メトリクスの送信先の Statsd ホスト。Unix Domain Sockets を使用している場合、‘unix://PATH_TO_UDS_SOCKET’ のような引数を使用します。例、unix:///var/datadog-agent/dsd.socket |
dd.jmxfetch.statsd.port | DD_JMXFETCH_STATSD_PORT | 8125 | JMX メトリクスの送信先の StatsD ポート。Unix Domain Sockets を使用している場合、0 を入力します。 |
dd.integration.opentracing.enabled | DD_INTEGRATION_OPENTRACING_ENABLED | true | デフォルトで、トレーシングクライアントは GlobalTracer がロードされており、トレーサーを動的に登録しているかどうかを検知します。これを false に設定すると、OpenTracing 上のトレーサーの依存関係がすべて消去されます。 |
dd.hystrix.tags.enabled | DD_HYSTRIX_TAGS_ENABLED | 偽 | デフォルトでは、Hystrix のグループ、コマンド、サーキット状態のタグは有効になっていません。このプロパティにより有効になります。 |
dd.trace.servlet.async-timeout.error | DD_TRACE_SERVLET_ASYNC_TIMEOUT_ERROR | 真 | デフォルトでは、長時間実行されている非同期リクエストはエラーとしてマークされます。この値を false に設定すると、すべてのタイムアウトを成功したリクエストとしてマークできます。 |
dd.trace.startup.logs | DD_TRACE_STARTUP_LOGS | 真 | false の場合は起動ログの収集が無効化されます。バージョン 0.64 以上で使用可能です。 |
注:
両方に同じキータイプが設定された場合、システムプロパティコンフィギュレーションが優先されます。
システムプロパティは JVM パラメーターとして使用できます。
デフォルトで、アプリケーションからの JMX メトリクスは、DogStatsD によりポート 8125
で Datadog Agent に送信されます。DogStatsD が Agent に対して有効になっていることを確認してください。
DD_DOGSTATSD_NON_LOCAL_TRAFFIC
が true
に設定されていることと、Agent コンテナでポート 8125
が開いていることを確認してください。インテグレーションを無効にする方法に関しては、インテグレーション の互換性セクションを参照してください。
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 インテグレーションドキュメントを参照してください。
Datadog APM トレーサーは、分散型トレーシングの B3 ヘッダーの抽出と挿入をサポートしています。
分散したヘッダーの挿入と抽出は、挿入/抽出スタイルを構成することで制御されます。現在、次の 2 つのスタイルがサポートされています:
Datadog
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 にトレースをレポートすると、次のことが発生します:
Datadog がサポートするライブラリやフレームワークの実際のコード、ドキュメント、使用例を確認したい場合は、インテグレーションセクションの Java アプリケーションの自動インスツルメンテーションされたコンポーネントの全一覧を参照してください。
プロジェクトに dd-trace-api
依存関係を追加します。Maven の場合、次を pom.xml
に追加します:
<dependency>
<groupId>com.datadoghq</groupId>
<artifactId>dd-trace-api</artifactId>
<version>{バージョン}</version>
</dependency>
Gradle の場合は、次を追加します:
compile group: 'com.datadoghq', name: 'dd-trace-api', version: {バージョン}
次に @Trace
をメソッドに追加して、dd-java-agent.jar
での実行時にメソッドがトレースされるようにします。Agent が添付されていない場合は、このアノテーションはアプリケーションに影響しません。
@Trace
アノテーションにはデフォルトのオペレーション名 trace.annotation
がある一方、トレースされるメソッドにはデフォルトでリソースがあります。
Java APM がアプリケーションのオーバーヘッドに与える影響は最小限です:
アプリケーションレベルのトレーサーを設定し、以下のカスタム Agent ホスト名にトレースを送信します。
Java Tracing Module が自動的に検索し環境変数の 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
お役に立つドキュメント、リンクや記事: