コードを使用してトレーシングライブラリをセットアップし、APM データを収集するように Agent を構成した後、オプションで統合サービスタグ付けのセットアップなど、必要に応じてトレーシングライブラリを構成してください。

以下のすべてのコンフィギュレーションオプションには、同等のシステムプロパティと環境変数があります。 両方に同じキータイプが設定されている場合は、システムプロパティコンフィギュレーションが優先されます。 システムプロパティは、JVM フラグとして設定できます。

注: Java トレーサーのシステムプロパティを使用する場合は、JVM オプションとして読み込まれるように、-jar の前にリストされていることを確認してください。

dd.service

環境変数: DD_SERVICE
デフォルト: unnamed-java-app
同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。バージョン 0.50.1 以降で利用可能。

dd.tags

環境変数: DD_TAGS
デフォルト: null
例: layer:api,team:intake,key:value
すべてのスパン、プロファイル、JMX メトリクスに追加されるデフォルトタグのリスト。DD_ENV または DD_VERSION が使用される場合、DD_TAGS で定義される env または version タグをオーバーライドします。バージョン 0.50.0 以降で利用可能。

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
デフォルト: true
Datadog のトレース ID とスパン ID に対する MDC キーの自動挿入を有効にします。詳細については、高度な使用方法を参照してください。

ベータ版: バージョン 1.18.3 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログ UI で DD_LOGS_INJECTION を設定できます。

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, postgresql: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 がリッスンしているポート番号。Agent 構成で receiver_port または DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、dd.trace.agent.port または dd.trace.agent.url はそれに合わせる必要があります。

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。Agent 構成で receiver_port または DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、dd.trace.agent.port または dd.trace.agent.url をそれに合わせる必要があります。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,My-Header-And-Tag-Name
大文字・小文字を区別しないヘッダーキーとタグ名のマップを受け取り、一致するヘッダー値を自動的にタグとしてトレースに適用します。また、タグ名を指定しないエントリーも受け入れ、それぞれ http.request.headers.<header-name> と http.response.headers.<header-name> という形式のタグに自動的にマップされます。

バージョン 0.96.0 以前は、この設定はリクエストヘッダータグにのみ適用されました。以前の動作に戻すには、設定 -Ddd.trace.header.tags.legacy.parsing.enabled=true または環境変数 DD_TRACE_HEADER_TAGS_LEGACY_PARSING_ENABLED=true を追加することで可能です。

ベータ版: バージョン 1.18.3 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログ UI で DD_TRACE_HEADER_TAGS を設定できます。

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> という形式のタグに自動的にマップされます。
バージョン 0.96.0 以降で利用可能です。

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> という形式のタグに自動的にマップされます。
バージョン 0.96.0 以降で利用可能です。

dd.trace.header.baggage

環境変数: DD_TRACE_HEADER_BAGGAGE
デフォルト: null
例: CASE-insensitive-Header:my-baggage-name,User-ID:userId,My-Header-And-Baggage-Name

大文字・小文字を区別しないヘッダキーとバゲッジキーのマップを受け取り、 一致したリクエストヘッダ値をトレース時にバゲッジとして自動的に適用します。伝搬時には、逆のマッピングが適用されます。バゲッジはヘッダーにマップされます。 バージョン 1.3.0 以降で利用可能です。

dd.trace.annotations

環境変数: DD_TRACE_ANNOTATIONS
デフォルト: (listed here)
例: 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.*
トレーサーによって無視される (変更されない) 完全修飾クラス (プレフィックスを示すワイルドカードで終わる場合があります) のリスト。名前には jvm 内部表現を使用する必要があります (例: package.ClassName$Nested and not package.ClassName.Nested)

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.elasticsearch.body.enabled

環境変数: DD_TRACE_ELASTICSEARCH_BODY_ENABLED
デフォルト: false
true に設定すると、Elasticsearch と OpenSearch のスパンに body が追加されます。

dd.trace.elasticsearch.params.enabled

環境変数: DD_TRACE_ELASTICSEARCH_PARAMS_ENABLED
デフォルト: true
true に設定すると、Elasticsearch と OpenSearch のスパンに query string パラメーターが追加されます。

dd.trace.health.metrics.enabled

環境変数: DD_TRACE_HEALTH_METRICS_ENABLED
デフォルト: true
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 に設定すると、クエリ文字列パラメーターとフラグメントが Web クライアントスパンに追加されます

dd.http.client.error.statuses

環境変数: DD_HTTP_CLIENT_ERROR_STATUSES
デフォルト: 400-499
許容可能なエラーの範囲。デフォルトで 4xx エラーは HTTP クライアントのエラーとしてレポートされます。この構成はこれをオーバーライドします。例: dd.http.client.error.statuses=400-403,405,410-499

dd.http.server.error.statuses

環境変数: DD_HTTP_SERVER_ERROR_STATUSES
デフォルト: 500-599
許容可能なエラーの範囲。デフォルトで 5xx ステータスコードは HTTP サーバーのエラーとしてレポートされます。この構成はこれをオーバーライドします。例: dd.http.server.error.statuses=500,502-599

dd.http.server.tag.query-string

環境変数: DD_HTTP_SERVER_TAG_QUERY_STRING
デフォルト: true
true に設定すると、クエリ文字列パラメーターとフラグメントが Web サーバースパンに追加されます

dd.http.server.route-based-naming

環境変数: DD_HTTP_SERVER_ROUTE_BASED_NAMING
デフォルト: true
false に設定すると、http フレームワークのルートはリソース名に使用されません。この場合、変更されるとリソース名と派生メトリクスが変更される可能性があります。

dd.trace.enabled

環境変数: DD_TRACE_ENABLED
デフォルト: true
false の場合、トレース Agent は無効になります。

dd.jmxfetch.enabled

環境変数: DD_JMXFETCH_ENABLED
デフォルト: true
Java トレース Agent による JMX メトリクスの収集を有効にします。

dd.jmxfetch.config.dir

環境変数: DD_JMXFETCH_CONFIG_DIR
デフォルト: null
例: /path/to/directory/etc/conf.d
JMX メトリクスコレクションの追加構成ディレクトリ。Java Agent は yaml ファイルの instance セクションの jvm_direct:true を探して構成を変更します。

dd.jmxfetch.config

環境変数: DD_JMXFETCH_CONFIG
デフォルト: null
例: path/to/file/conf.yaml,other/path/to/file/conf.yaml
JMX メトリクスコレクションの追加メトリクスコンフィギュレーションファイル。Java Agent は 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.trace.obfuscation.query.string.regexp

環境変数: DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
デフォルト: null
http.url タグで報告されるリクエストのクエリ文字列から機密データを削除するための正規表現 (マッチした場合は に置き換え)。

dd.integration.opentracing.enabled

環境変数: DD_INTEGRATION_OPENTRACING_ENABLED
デフォルト: true
デフォルトで、トレーシングクライアントは GlobalTracer がロードされており、トレーサーを動的に登録しているかどうかを検出します。これを false に設定すると、OpenTracing 上のトレーサーの依存関係がすべて消去されます。

dd.hystrix.tags.enabled

環境変数: DD_HYSTRIX_TAGS_ENABLED
デフォルト: false
デフォルトでは、Hystrix のグループ、コマンド、サーキット状態のタグは有効になっていません。このプロパティにより有効になります。

dd.trace.servlet.async-timeout.error

環境変数: DD_TRACE_SERVLET_ASYNC_TIMEOUT_ERROR
デフォルト: true
デフォルトでは、長時間実行されている非同期リクエストはエラーとしてマークされます。この値を false に設定すると、すべてのタイムアウトを成功したリクエストとしてマークできます。

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 以降で使用可能です。

dd.instrumentation.telemetry.enabled

環境変数: DD_INSTRUMENTATION_TELEMETRY_ENABLED
デフォルト: true
true の場合、トレーサーはテレメトリーデータを収集します。バージョン 0.104+ で利用可能です。バージョン 0.115+ では true がデフォルトとなります。

注:

• 両方に同じキータイプが設定された場合、システムプロパティ構成が優先されます。

• システムプロパティは JVM パラメーターとして使用できます。

• デフォルトで、アプリケーションからの JMX メトリクスは、DogStatsD によりポート 8125 で Datadog Agent に送信されます。DogStatsD が Agent に対して有効になっていることを確認してください。

  • Agent をコンテナとして実行している場合は、DD_DOGSTATSD_NON_LOCAL_TRAFFIC が true に設定されていることと、Agent コンテナでポート 8125 が開いていることを確認してください。
  • Kubernetes の場合は、DogStatsD ポートをホストポートにバインドします。ECS の場合は、タスク定義で適当なフラグを設定します。

インテグレーション

インテグレーションを無効にする方法については、インテグレーションの互換性セクションを参照してください。

例

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 と dd.jmxfetch.config

構成サンプル

• 以下のいずれかのコンビネーションを使用: DD_JMXFETCH_CONFIG_DIR=<ディレクトリパス> + DD_JMXFETCH_CONFIG=conf.yaml
• または直接指定: DD_JMXFETCH_CONFIG=<DIRECTORY_PATH>/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 インテグレーションドキュメントを参照してください。

ヘッダーの抽出と挿入

有効な値と以下の構成オプションの使用に関する情報については、Java トレースコンテキストの伝播を参照してください。

dd.trace.propagation.style.inject

環境変数: DD_TRACE_PROPAGATION_STYLE_INJECT
デフォルト: datadog
サービス間で分散型トレーシングを伝播するために含めるべきヘッダー形式のカンマ区切りリスト。
バージョン 1.9.0 以降で利用可能

dd.trace.propagation.style.extract

環境変数: DD_TRACE_PROPAGATION_STYLE_EXTRACT
デフォルト: datadog
分散型トレーシングの伝播データの抽出を試みるヘッダーフォーマットのカンマ区切りのリスト。完全で有効なヘッダーを持つ最初のフォーマットが、トレースを継続するために定義するために使用されます。
バージョン 1.9.0 以降で利用可能

dd.trace.propagation.style

環境変数: DD_TRACE_PROPAGATION_STYLE
デフォルト: datadog
分散型トレーシングの伝播データの挿入および抽出を試みるヘッダーフォーマットのカンマ区切りのリスト。完全で有効なヘッダーを持つ最初のフォーマットが、トレースを継続するために定義するために使用されます。より具体的な dd.trace.propagation.style.inject と dd.trace.propagation.style.extract の構成が存在する場合は、そちらが優先されます。
バージョン 1.9.0 以降で利用可能

非推奨の抽出と挿入の設定

これらの抽出と挿入の設定は廃止され、バージョン 1.9.0 以降では dd.trace.propagation.style.inject、dd.trace.propagation.style.extract、dd.trace.propagation.style の設定に変更されました。Java トレースコンテキストの伝播を参照してください。B3 マルチヘッダーと B3 シングルヘッダーに対する以前の b3 設定は、新しい b3multi と b3single 設定に置き換えられました。

dd.propagation.style.inject

環境変数: DD_PROPAGATION_STYLE_INJECT
デフォルト: datadog
サービス間で分散型トレーシングを伝播するために含めるべきヘッダー形式のカンマ区切りリスト。
バージョン 1.9.0 以降、非推奨

dd.propagation.style.extract

環境変数: DD_PROPAGATION_STYLE_EXTRACT
デフォルト: datadog
分散型トレーシングの伝播データの抽出を試みるヘッダーフォーマットのカンマ区切りのリスト。完全で有効なヘッダーを持つ最初のフォーマットが、トレースを継続するために定義するために使用されます。
バージョン 1.9.0 以降、非推奨

試験機能

以下の構成オプションは現在利用可能な機能向けですが、今後のリリースで変更される場合があります。

dd.integration.opentelemetry.experimental.enabled

環境変数: DD_INTEGRATION_OPENTELEMETRY_EXPERIMENTAL_ENABLED
デフォルト: false
OpenTelemetry の試験機能を有効にします。この設定を有効にすると、Datadog Trace Agent によって支えられた OpenTelemetry トレーシング API を使用できます。
バージョン 1.10.0 以降で利用可能

その他の参考資料

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

Datadog Java APM ソースコードGITHUB サービス、リソース、トレースを調査するドキュメント ヘッダーを使ったトレースコンテキストの伝搬DOCUMENTATION