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

コードを使用してトレーシングライブラリをセットアップし、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
すべてのスパン、プロファイル、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 キー挿入の有効化。詳しくは、高度な使用方法を参照してください。
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,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 を設定することで可能です。
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.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.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 に設定すると、クエリ文字列パラメーターとフラグメントがウェブクライアントスパンに追加されます
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
デフォルト: 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
: /path/to/directory/etc/conf.d
JMX メトリクスコレクションの追加構成ディレクトリ。Java エージェントは 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 エージェントは 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
デフォルト: 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.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 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 のフェッチ例

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

B3 ヘッダーの抽出と挿入

Datadog APM トレーサーは、分散型トレーシングの B3 ヘッダーの抽出と挿入をサポートしています。

分散したヘッダーの挿入と抽出は、挿入/抽出スタイルを構成することで制御されます。現在、次の 2 つのスタイルがサポートされています:

  • Datadog: Datadog
  • B3: 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 抽出スタイルのみが有効になっています。

複数の抽出スタイルが有効になっている場合、抽出試行はスタイルの構成順で実行され、最初に成功した抽出値が使われます。

その他の参考資料