Java トレーシングライブラリの構成

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

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

Converting between system properties and environment variables

Unless otherwise stated, you can convert between system properties and environment variables with the following transformations:

  • To set a system property as an environment variable, uppercase the property name and replace . or - with _. For example, dd.service becomes DD_SERVICE.
  • To set an environment variable as a system property, lowercase the variable name and replace _ with . For example, DD_TAGS becomes dd.tags.

Note: When using the Java tracer’s system properties, list the properties before -jar. This ensures the properties are read in as JVM options.

コンフィギュレーションオプション

統合サービスタグ付け

dd.service
環境変数: DD_SERVICE
デフォルト: unnamed-java-app
同一のジョブを実行するプロセスセットの名前。アプリケーションの統計のグループ化に使われます。バージョン 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.trace.enabled
環境変数: DD_TRACE_ENABLED
デフォルト: true
false の場合、トレース Agent は無効になります。
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.trace.agent.port
Environment Variable: DD_TRACE_AGENT_PORT
Default: 8126
The port number the Agent is listening on for configured host. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then dd.trace.agent.port or dd.trace.agent.url must match it.
dd.trace.agent.unix.domain.socket
環境変数: DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET
デフォルト: null
これは、トレーストラフィックをプロキシに送り、その後リモート Datadog Agent に送信するために使うことができます。
dd.trace.agent.url
Environment Variable: DD_TRACE_AGENT_URL
Default: null
The URL to send traces to. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then dd.trace.agent.port or dd.trace.agent.url must match it. The URL value can start with http:// to connect using HTTP or with unix:// to use a Unix Domain Socket. When set this takes precedence over DD_AGENT_HOST and DD_TRACE_AGENT_PORT. Available for versions 0.65+.
dd.trace.agent.timeout
環境変数: DD_TRACE_AGENT_TIMEOUT
デフォルト: 10
Datadog Agent とのネットワークインタラクションのタイムアウト (秒)。
dd.trace.header.tags
Environment Variable: DD_TRACE_HEADER_TAGS
Default: null
Example: CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
Accepts a map of case-insensitive header keys to tag names and automatically applies matching header values as tags on traces. Also accepts entries without a specified tag name that are automatically mapped to tags of the form http.request.headers.<header-name> and http.response.headers.<header-name> respectively.

Prior to version 0.96.0 this setting only applied to request header tags. To change back to the old behavior, add the setting -Ddd.trace.header.tags.legacy.parsing.enabled=true or the environment variable DD_TRACE_HEADER_TAGS_LEGACY_PARSING_ENABLED=true.

Beta: Starting in version 1.18.3, if Agent Remote Configuration is enabled where this service runs, you can set DD_TRACE_HEADER_TAGS in the Service Catalog UI.
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
Environment Variable: DD_TRACE_ANNOTATIONS
Default: (listed here)
Example: com.some.Trace;io.other.Trace
A list of method annotations to treat as @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.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.trace.obfuscation.query.string.regexp
環境変数: DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
デフォルト: null
http.url タグで報告されるリクエストのクエリ文字列から機密データを削除するための正規表現 (マッチした場合は に置き換え)。
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.trace.rate.limit
Environment Variable: DD_TRACE_RATE_LIMIT
Default: 100
Maximum number of spans to sample per second, per process, when DD_TRACE_SAMPLING_RULES or DD_TRACE_SAMPLE_RATE is set. Otherwise, the Datadog Agent controls rate limiting.
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.128.bit.traceid.generation.enabled
Environment Variable: DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED
Default: true
When true, the tracer generates 128 bit Trace IDs, and encodes Trace IDs as 32 lowercase hexadecimal characters with zero padding.
dd.trace.128.bit.traceid.logging.enabled
Environment Variable: DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED
Default: false
When true, the tracer will inject 128 bit Trace IDs as 32 lowercase hexadecimal characters with zero padding, and 64 bit Trace IDs as decimal numbers. Otherwise, the tracer always injects Trace IDs as decimal numbers.
dd.trace.otel.enabled
Environment Variable: DD_TRACE_OTEL_ENABLED
Default: false
When true, OpenTelemetry-based tracing for custom instrumentation is enabled.

Agent

dd.tags
環境変数: DD_TAGS
デフォルト: null
例: layer:api,team:intake,key:value
すべてのスパン、プロファイル、JMX メトリクスに追加されるデフォルトタグのリスト。DD_ENV または DD_VERSION が使用される場合、DD_TAGS で定義される env または version タグをオーバーライドします。バージョン 0.50.0 以降で利用可能。
dd.agent.host
Environment Variable: DD_AGENT_HOST
Default: localhost
Hostname for where to send traces to. If using a containerized environment, configure this to be the host IP. See Tracing Docker Applications for more details.
dd.instrumentation.telemetry.enabled
Environment Variable: DD_INSTRUMENTATION_TELEMETRY_ENABLED
Default: true
When true, the tracer collects telemetry data. Available for versions 0.104+. Defaults to true for versions 0.115+.

データベース

dd.trace.db.client.split-by-instance
環境変数: DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE
デフォルト: false
true に設定すると、db スパンにインスタンス名がサービス名として割り当てられます
dd.trace.db.client.split-by-host
Environment Variable: DD_TRACE_DB_CLIENT_SPLIT_BY_HOST
Default: false
When set to true db spans get assigned the remote database hostname as the service name

エラー

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

Logs

dd.logs.injection
Environment Variable: DD_LOGS_INJECTION
Default: true
Enabled automatic MDC key injection for Datadog trace and span IDs. See Advanced Usage for details.

Beta: Starting in version 1.18.3, if Agent Remote Configuration is enabled where this service runs, you can set DD_LOGS_INJECTION in the Service Catalog UI.

Trace context propagation

For information about valid values and using the following configuration options, see Propagating Java Trace Context.

dd.trace.propagation.style.inject
Environment Variable: DD_TRACE_PROPAGATION_STYLE_INJECT
Default: datadog,tracecontext
A comma-separated list of header formats to include to propagate distributed traces between services.
Available since version 1.9.0
dd.trace.propagation.style.extract
Environment Variable: DD_TRACE_PROPAGATION_STYLE_EXTRACT
Default: datadog,tracecontext
A comma-separated list of header formats from which to attempt to extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue.
Available since version 1.9.0
dd.trace.propagation.style
Environment Variable: DD_TRACE_PROPAGATION_STYLE
Default: datadog,tracecontext
A comma-separated list of header formats from which to attempt to inject and extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue. The more specific dd.trace.propagation.style.inject and dd.trace.propagation.style.extract configuration settings take priority when present.
Available since version 1.9.0
trace.propagation.extract.first
Environment Variable: DD_TRACE_PROPAGATION_EXTRACT_FIRST
Default: false
When set to true, stop extracting trace context when a valid one is found.

JMX metrics

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.jmxfetch.<integration-name>.enabled
Environment Variable: DD_JMXFETCH_<INTEGRATION_NAME>_ENABLED
Default: false
JMX integration to enable (for example, Kafka or ActiveMQ).

インテグレーション

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

dd.integration.opentracing.enabled
環境変数: DD_INTEGRATION_OPENTRACING_ENABLED
デフォルト: true
デフォルトで、トレーシングクライアントは GlobalTracer がロードされており、トレーサーを動的に登録しているかどうかを検出します。これを false に設定すると、OpenTracing 上のトレーサーの依存関係がすべて消去されます。
dd.hystrix.tags.enabled
環境変数: DD_HYSTRIX_TAGS_ENABLED
デフォルト: false
デフォルトでは、Hystrix のグループ、コマンド、サーキット状態のタグは有効になっていません。このプロパティにより有効になります。
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.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
JMX タグのトレース

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 スパンのメタデータと同じサービス名が付けられます。

インスタンス 1

これで、DB インスタンス 2 である secondwebappdb に、db.instance スパンのメタデータと同じサービス名が付けられます。

インスタンス 2

同様に、サービスマップで、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 のフェッチ例

JMX フェッチを使った Java メトリクス収集についての詳細は Java インテグレーションドキュメントを参照してください。

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

These extraction and injection settings have been deprecated in favor of the dd.trace.propagation.style.inject, dd.trace.propagation.style.extract, and dd.trace.propagation.style settings since version 1.9.0. See Propagating Java Trace Context. The previous b3 setting for both B3 multi header and B3 single header has been replaced with the new settings b3multi and 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 以降、非推奨

その他の参考資料

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

Datadog Java APM ソースコードソースコード more more サービス、リソース、トレースを調査するドキュメント more more ヘッダーを使ったトレースコンテキストの伝搬DOCUMENTATION more more OpenTelemetry Environment Variable Configurationsドキュメント more more
PREVIEWING: may/unit-testing