- はじめに
- エージェント
- インテグレーション
- Watchdog
- イベント
- ダッシュボード
- モバイルアプリケーション
- インフラストラクチャー
- サーバーレス
- メトリクス
- ノートブック
- アラート設定
- APM & Continuous Profiler
- CI Visibility
- RUM & セッションリプレイ
- データベース モニタリング
- ログ管理
- セキュリティプラットフォーム
- Synthetic モニタリング
- ネットワークモニタリング
- 開発者
- API
- アカウントの管理
- データセキュリティ
- ヘルプ
Java Tracing Library は、バージョン 7 以降のすべてのプラットフォームですべての JVM をサポートします。Continuous Profiler でトレースを利用するには、OpenJDK 11 以降、Oracle Java 11 以降、ほとんどのベンダー向けの OpenJDK 8 (バージョン8u262 以降)、および Zulu Java 8 以降 (マイナーバージョン 1.8.0_212 以降) がサポートされています。バージョン 8u272 以降、すべてのベンダーがプロファイラーでサポートされるようになります。
Scala (バージョン 2.10.x - 2.13.x)、Groovy、Kotlin、Clojure などのすべての JVM ベースの言語が、Java トレーサーとプロファイラーでサポートされています。サポート対象のライブラリの一覧については、互換性要件ページをご覧ください。
トレースを設定すると、Continuous Profiler も設定され、アプリからプロファイリングデータの受信を開始するために必要なのはプロファイラーを有効にすることだけです。
Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:
service
、env
、version
タグを動的に設定します。もしくは、アプリケーションをトレースする場合は以下の操作を行ってください。
最新の Agent クラスファイルが含まれる dd-java-agent.jar
をダウンロードします:
wget -O dd-java-agent.jar https://dtdg.co/latest-java-tracer
トレーサーの特定のバージョンにアクセスするには、Datadog の Maven リポジトリを参照してください。
IDE、Maven または Gradle アプリケーションスクリプト、java -jar
コマンドから、継続的プロファイラー、デプロイ追跡、ログ挿入(Datadog へログを送信する場合)、およびトレースボリュームコントロールを使用してアプリケーションを実行するには、-javaagent
JVM 引数と、該当する以下のコンフィギュレーションオプションを追加します。
java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -XX:FlightRecorderOptions=stackdepth=256 -Ddd.logs.injection=true -Ddd.trace.sample.rate=1 -Ddd.service=my-app -Ddd.env=staging -jar path/to/your/app.jar -Ddd.version=1.0
注: プロファイリングを有効にすると、APM のバンドルによっては請求に影響を与える場合があります。詳しくは、料金ページを参照してください。
環境変数 | システムプロパティ | 説明 |
---|---|---|
DD_ENV | dd.env | アプリケーション環境(production 、staging など) |
DD_SERVICE | dd.service | 同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。 |
DD_VERSION | dd.version | アプリケーションのバージョン(例: 2.5 、202003181415 、1.3-alpha など) |
DD_PROFILING_ENABLED | dd.profiling.enabled | 継続的プロファイラーを有効化 |
DD_LOGS_INJECTION | dd.logs.injection | Datadog トレース ID とスパン ID に対する自動 MDC キー挿入を有効にします。詳しくは、高度な使用方法を参照してください。 |
DD_TRACE_SAMPLE_RATE | dd.trace.sample.rate | トレースボリュームコントロールを有効にする |
追加のコンフィギュレーションオプション は以下で説明されています。
インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は apm_config
下にある datadog.yaml
ファイルの enabled: true
で有効になっており、http://localhost:8126
でトレースデータをリッスンします。コンテナ化環境の場合、以下のリンクに従って、Datadog Agent 内でトレース収集を有効にします。
メイン datadog.yaml
コンフィギュレーションファイルの apm_config
セクションで apm_non_local_traffic: true
を設定します。
コンテナ化された環境でトレースを受信するように Agent を構成する方法については、それぞれの説明を参照してください。
アプリケーションがインスツルメントされた後、トレースクライアントはデフォルトで Unix ドメインソケット /var/run/datadog/apm.socket
にトレースを送信しようとします。ソケットが存在しない場合、トレースは http://localhost:8126
に送信されます。
別のソケット、ホスト、またはポートが必要な場合は、環境変数 DD_TRACE_AGENT_URL
を使用します。以下にいくつかの例を示します。
DD_TRACE_AGENT_URL=http://custom-hostname:1234
DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
java -javaagent:<DD-JAVA-AGENT-PATH>.jar -jar <YOUR_APPLICATION_PATH>.jar
システムプロパティを使うこともできます:
java -javaagent:<DD-JAVA-AGENT-PATH>.jar \
-Ddd.trace.agent.url=$DD_TRACE_AGENT_URL \
-jar <YOUR_APPLICATION_PATH>.jar
同様に、トレースクライアントは Unix ドメインソケット /var/run/datadog/dsd.socket
に統計情報を送信しようと試みます。ソケットが存在しない場合、統計情報は http://localhost:8125
に送信されます。
DD_SITE
を
に設定して、Agent が正しい Datadog の場所にデータを送信するようにします。AWS Lambda で Datadog APM を設定するには、サーバーレス関数のトレースドキュメントを参照してください。
トレースは、Heroku、Cloud Foundry、AWS Elastic Beanstalk、Azure App Service など、他の多くの環境で利用できます。
その他の環境については、その環境のインテグレーションのドキュメントを参照し、セットアップの問題が発生した場合はサポートにお問い合わせください。
アプリケーションサーバーのドキュメントを使用して、-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"
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
管理コンソールで:
-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 のドキュメントを参照してください。
classpath に dd-java-agent
を追加しないでください。予期せぬ挙動が生じる場合があります。
Java の自動インスツルメンテーションは、JVM によって提供される java-agent
インスツルメンテーション機能を使用します。java-agent
が登録されている場合は、ロード時にクラスファイルを変更することができます。
インスツルメンテーションの由来は自動インスツルメンテーション、OpenTracing api、または両者の混合になる場合があります。一般的に、インスツルメンテーションは次の情報を取得します:
以下のすべてのコンフィギュレーションオプションには、同等のシステムプロパティと環境変数があります。 両方に同じキータイプが設定されている場合は、システムプロパティコンフィギュレーションが優先されます。 システムプロパティは、JVM フラグとして設定できます。
注: Java トレーサーのシステムプロパティを使用する場合は、JVM オプションとして読み込まれるように、-jar
の前にリストされていることを確認してください。
dd.service
DD_SERVICE
unnamed-java-app
dd.tags
DD_TAGS
null
layer:api,team:intake
dd.env
DD_ENV
none
dd.version
DD_VERSION
null
dd.logs.injection
DD_LOGS_INJECTION
true
dd.trace.config
DD_TRACE_CONFIG
null
-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
LoggingWriter
で構成すると、トレースがコンソールに書き出されます。dd.agent.host
DD_AGENT_HOST
localhost
dd.trace.agent.port
DD_TRACE_AGENT_PORT
8126
dd.trace.agent.unix.domain.socket
DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET
null
dd.trace.agent.url
DD_TRACE_AGENT_URL
null
http://
(HTTP を使用) もしくは unix://
(Unix ドメインソケットを使用) のいずれかで始まります。この設定は DD_AGENT_HOST
および DD_TRACE_AGENT_PORT
よりも優先されます。バージョン 0.65 以上で使用可能です。dd.trace.agent.timeout
DD_TRACE_AGENT_TIMEOUT
10
dd.trace.header.tags
DD_TRACE_HEADER_TAGS
null
CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
http.request.headers.<header-name>
と http.response.headers.<header-name>
という形式のタグに自動的にマップされます。Ddd.trace.header.tags.legacy.parsing.enabled=true
を追加するか、環境変数 DD_TRACE_HEADER_TAGS_LEGACY_PARSING_ENABLED=true
を設定することで可能です。dd.trace.request_header.tags
DD_TRACE_REQUEST_HEADER_TAGS
null
CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
http.request.headers.<header-name>
という形式のタグに自動的にマップされます。dd.trace.response_header.tags
DD_TRACE_RESPONSE_HEADER_TAGS
null
CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
http.response.headers.<header-name>
という形式のタグに自動的にマップされます。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];package.ClassName[*]
@Trace
の追加と似ていますが、コードの変更はありません。注: ワイルドカード型メソッドのサポート ([*]
) は、コンストラクター、get アクセス操作子、set アクセス操作子、synthetic、toString、等号、ハッシュコード、またはファイナライザーメソッドのコールに対応しません。dd.trace.classes.exclude
DD_TRACE_CLASSES_EXCLUDE
null
package.ClassName,package.ClassName$Nested,package.Foo*,package.other.*
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
と同じdd.trace.health.metrics.statsd.port
DD_TRACE_HEALTH_METRICS_STATSD_PORT
dd.jmxfetch.statsd.port
と同じ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
dd.http.client.error.statuses=400-403,405,410-499
dd.http.server.error.statuses
DD_HTTP_SERVER_ERROR_STATUSES
500-599
dd.http.server.error.statuses=500,502-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
dd.jmxfetch.config.dir
DD_JMXFETCH_CONFIG_DIR
null
/path/to/directory/etc/conf.d
yaml
ファイルの instance
セクションの jvm_direct:true
を探してコンフィギュレーションを変更します。dd.jmxfetch.config
DD_JMXFETCH_CONFIG
null
path/to/file/conf.yaml,other/path/to/file/conf.yaml
yaml
ファイルの instance
セクションの jvm_direct:true
を探してコンフィギュレーションを変更します。dd.jmxfetch.check-period
DD_JMXFETCH_CHECK_PERIOD
1500
dd.jmxfetch.refresh-beans-period
DD_JMXFETCH_REFRESH_BEANS_PERIOD
600
dd.jmxfetch.statsd.host
DD_JMXFETCH_STATSD_HOST
agent.host
と同じunix:///var/datadog-agent/dsd.socket
dd.jmxfetch.statsd.port
DD_JMXFETCH_STATSD_PORT
8125
dd.integration.opentracing.enabled
DD_INTEGRATION_OPENTRACING_ENABLED
true
dd.hystrix.tags.enabled
DD_HYSTRIX_TAGS_ENABLED
false
dd.trace.servlet.async-timeout.error
DD_TRACE_SERVLET_ASYNC_TIMEOUT_ERROR
true
dd.trace.startup.logs
DD_TRACE_STARTUP_LOGS
true
false
の場合は起動ログの収集が無効化されます。バージョン 0.64 以上で使用可能です。dd.trace.servlet.principal.enabled
DD_TRACE_SERVLET_PRINCIPAL_ENABLED
false
true
の場合は、ユーザープリンシパルが収集されます。バージョン 0.61 以降で使用可能です。注:
両方に同じキータイプが設定された場合、システムプロパティコンフィギュレーションが優先されます。
システムプロパティは 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 の場合は、次を追加します:
implementation group: 'com.datadoghq', name: 'dd-trace-api', version: {バージョン}
次に @Trace
をメソッドに追加して、dd-java-agent.jar
での実行時にメソッドがトレースされるようにします。Agent が添付されていない場合は、このアノテーションはアプリケーションに影響しません。
@Trace
アノテーションにはデフォルトのオペレーション名 trace.annotation
がある一方、トレースされるメソッドにはデフォルトでリソースがあります。
Java APM がアプリケーションのオーバーヘッドに与える影響は最小限です:
お役に立つドキュメント、リンクや記事: