コードを使用してトレーシングライブラリをセットアップし、APM データを収集するように Agent を構成した後、オプションで統合サービスタグ付けのセットアップなど、必要に応じてトレーシングライブラリを構成してください。
トレーサーの設定は、以下の環境変数で構成することができます。
統合サービスタグ付け
DD_ENV- 構成:
env
デフォルト: Datadog Agent で構成された環境
アプリケーションの環境を設定します (例えば、prod、pre-prod、stage など)。 DD_SERVICE- 構成:
service
デフォルト: package.json の name フィールド
このアプリケーションで使用するサービス名。 DD_VERSION- 構成:
version
デフォルト: package.json の version フィールド
アプリケーションのバージョン番号。
サービスに env、service、version を設定するには、DD_ENV、DD_SERVICE、DD_VERSION を使用することをおすすめします。このような環境変数の構成におすすめについては、統合サービスタグ付けのドキュメントをご参照ください。
トレース
DD_TRACE_ENABLED- 構成: N/A
デフォルト: true
dd-trace を有効にするかどうか。false に設定すると、ライブラリの全ての機能が無効になります。 DD_TRACE_DEBUG- 構成: N/A
デフォルト: false
トレーサーのデバッグロギングを有効にします。 DD_TRACING_ENABLED- 構成: N/A
デフォルト: true
トレースを有効にするかどうか。 DD_TRACE_RATE_LIMIT- Configuration:
rateLimit
Default: 100 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent.
The maximum number of traces per second per service instance.
DD_TRACE_HEADER_TAGS- Configuration:
headerTags
Default: N/A
Accepts a comma-delimited list of case-insensitive HTTP headers optionally mapped to tag names. Automatically applies matching header values as tags on traces. When a tag name is not specified, it defaults to tags of the form http.request.headers.<header-name> for requests and http.response.headers.<header-name> for responses. Note: This option is only supported for HTTP/1.
Example: User-ID:userId,Request-ID
- If the Request/Response has a header
User-ID, its value is applied as tag userId to the spans produced by the service.
- If the Request/Response has a header
Request-ID, its value is applied as tag http.request.headers.Request-ID for requests and http.response.headers.Request-ID for responses.
DD_TRACE_SAMPLE_RATE- 構成:
sampleRate
デフォルト: Agent に判断を委ねます。
Agent とバックエンド間の取り込みサンプルレート (0.0～1.0 の間) を制御します。 DD_TRACE_SAMPLING_RULES- 構成:
samplingRules
デフォルト: []
優先的にサンプリングする際に適用するサンプリングルール。オブジェクトの JSON 配列。各オブジェクトは、0.0 から 1.0 の間の sample_rate 値を持たなければなりません (この値を含む)。各ルールはオプションで name と service フィールドを持ち、これらはトレースの service と name に対してマッチする正規表現文字列です。ルールは、トレースのサンプルレートを決定するために設定された順番で適用されます。省略された場合、トレーサーは Agent に従い、すべてのトレースでサンプルレートを動的に調整します。 DD_SERVICE_MAPPING- 構成:
serviceMapping
デフォルト: N/A
例: mysql:my-mysql-service-name-db,pg:my-pg-service-name-db
各プラグインのサービス名を提供します。カンマ区切りの plugin:service-name ペア (スペースありまたはなし) を許容します。 - Flush Interval
- 構成:
flushInterval
デフォルト: 2000
トレーサーが Agent にトレースを送信する間隔 (ミリ秒)。 DD_TRACE_PARTIAL_FLUSH_MIN_SPANS- 構成:
flushMinSpans
デフォルト: 1000
トレースを部分的にエクスポートする前のスパン数。これにより、非常に大きなトレースに対して、すべてのスパンをメモリに保持することを防ぎます。 DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP- 構成: N/A
デフォルト: N/A
http.url タグで報告されるリクエストのクエリ文字列から、機密性の高いデータを削除するための正規表現 (マッチしたデータは <redacted> に置き換えられます)。空文字列を指定すると編集を無効にし、.* を指定するとすべてのクエリ文字列を編集することができます。警告: この正規表現は安全でない入力 (url) からのリクエストに対して実行されるので、安全な正規表現を使用するようにしてください。 DD_TRACE_CLIENT_IP_HEADER- 構成: N/A
デフォルト: N/A
http.client_ip タグのソースとなるカスタムヘッダー名。 - DNS Lookup Function
- 構成:
lookup
デフォルト: require('dns').lookup
Agent にリクエストを送信する際の DNS ルックアップのカスタム関数です。セットアップによっては、何百ものサービスが実行されており、それぞれがフラッシュ間隔ごとに DNS ルックアップを行い、スケーリングの問題を引き起こしています。これをオーバーライドして、独自のキャッシュまたは解決メカニズムを提供します。 DD_TRACE_AGENT_PROTOCOL_VERSION- 構成:
protocolVersion
デフォルト: 0.4
Agent へのリクエストに使用するプロトコルのバージョン。構成されたバージョンは、インストールされた Agent のバージョンによってサポートされている必要があり、そうでない場合はすべてのトレースが削除されます。 DD_TRACE_REPORT_HOSTNAME- 構成:
reportHostname
デフォルト: false
各トレースについて、システムのホスト名を報告するかどうか。無効の場合、Agent のホスト名が代わりに使用されます。 DD_TRACE_STARTUP_LOGS- 構成:
startupLogs
デフォルト: false
トレーサーのスタートアップ構成と診断ログを有効にします。 DD_SPAN_SAMPLING_RULES- 構成:
spanSamplingRules
デフォルト: []
スパンのサンプリングルールで、トレースの残りがドロップされる場合に、個々のスパンを保持します。オブジェクトの JSON 配列。ルールは、スパンのサンプルレートを決定するために構成された順序で適用されます。sample_rate 値は 0.0 から 1.0 の間でなければなりません (この値を含む)。
詳しくは、取り込みメカニズムを参照してください。
例:
- サービス名
my-service と演算子名 http.request のスパンサンプリングレートを 50% に設定し、1 秒間に最大 50 トレースします: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'
DD_SPAN_SAMPLING_RULES_FILE- 構成: N/A
デフォルト: N/A
スパンサンプリングルールを含む JSON ファイルへのポインタを指定します。この変数よりも DD_SPAN_SAMPLING_RULES が優先されます。ルールのフォーマットは DD_SPAN_SAMPLING_RULES を参照してください。 DD_TRACE_DISABLED_PLUGINS- 構成: N/A
デフォルト: N/A
例: DD_TRACE_DISABLED_PLUGINS=express,dns
トレーサー初期化時に自動的に無効になるインテグレーション名のカンマ区切り文字列。 - Experimental Features
- 構成:
experimental
デフォルト: {}
実験的な機能は、あらかじめ定義されたキーに true という値を追加することで有効にすることができます。利用可能な実験的機能の詳細については、サポートに連絡してください。 - Automatically Instrument External Libraries
- 構成:
plugins
デフォルト: true
ビルトインプラグインを使用して、外部ライブラリの自動インスツルメンテーションを有効にするかどうか。
Agent
DD_TAGS- 構成:
tags
デフォルト: {}
すべてのスパンおよびランタイムメトリクスに適用されるグローバルタグを設定します。環境変数として渡される場合、形式は key:value,key:value となります。プログラムで設定する場合は、tracer.init({ tags: { foo: 'bar' } }) のような形式になります。 DD_TRACE_AGENT_URL- 構成:
url
デフォルト: http://localhost:8126
トレーサーが送信するトレース Agent の URL。設定した場合、ホスト名およびポートより優先されます。Agent 構成で receiver_port や DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、DD_TRACE_AGENT_PORT や DD_TRACE_AGENT_URL をそれに一致させる必要があります。datadog.yaml ファイルの apm_config.receiver_socket または DD_APM_RECEIVER_SOCKET 環境変数と組み合わせて、Unix ドメインソケットをサポートします。 DD_TRACE_AGENT_HOSTNAME- 構成:
hostname
デフォルト: localhost
トレーサーが送信する Agent のアドレス。 DD_TRACE_AGENT_PORT- 構成:
port
デフォルト: 8126
トレーサーが送信する Trace Agent のポート。Agent 構成で receiver_port や DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、DD_TRACE_AGENT_PORT や DD_TRACE_AGENT_URL をそれに一致させる必要があります。 DD_DOGSTATSD_PORT- 構成:
dogstatsd.port
デフォルト: 8125
メトリクスを送信する DogStatsD Agent のポート。Agent 構成で dogstatsd_port や DD_DOGSTATSD_PORT がデフォルトの 8125 以外に設定されている場合、このトレーシングライブラリ DD_DOGSTATSD_PORT はそれに合わせなければなりません。 DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS- 構成:
remoteConfig.pollInterval
デフォルト: 5
リモート構成のポーリング間隔 (秒)。
ASM
DD_APPSEC_ENABLED- 構成:
appsec.enabled
デフォルト: false
Application Security Management の機能を有効にします。 DD_APPSEC_RULES- 構成:
appsec.rules
デフォルト: N/A
カスタム AppSec ルールファイルへのパス。 DD_APPSEC_WAF_TIMEOUT- 構成:
appsec.wafTimeout
デフォルト: 5000
WAF の同期実行時間 (マイクロ秒) を制限します。 DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP- 構成:
appsec.obfuscatorKeyRegex
デフォルト: N/A
攻撃報告において、機密データをそのキーで冗長化するための正規表現文字列。 DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP- 構成:
appsec.obfuscatorValueRegex
デフォルト: N/A
攻撃報告において、機密データをその値で冗長化するための正規表現文字列。
データベースモニタリング
DD_DBM_PROPAGATION_MODE- 構成:
dbmPropagationMode
デフォルト: 'disabled'
タグインジェクションを用いた DBM と APM のリンクを有効にするには、'service' または 'full' に設定します。'service' オプションは DBM と APM サービス間の接続を可能にします。'full' オプションは、データベースクエリイベントを持つデータベーススパン間の接続を可能にします。Postgres で利用可能です。
Logs
DD_LOGS_INJECTION- 構成:
logInjection
デフォルト: false
対応するログライブラリのログにトレース ID の自動挿入を有効にします。 DD_TRACE_LOG_LEVEL- 構成:
logLevel
デフォルト: debug
デバッグログが有効な場合に、トレーサーが使用する最小のログレベルを表す文字列で、例えば error や debug などです。
OpenTelemetry
DD_TRACE_OTEL_ENABLED- Configuration: N/A
Default: undefined
When true, OpenTelemetry-based tracing for custom instrumentation is enabled.
プロファイリング
DD_PROFILING_ENABLED- 構成:
profiling
デフォルト: false
プロファイリングを有効にするかどうか。
ランタイムメトリクス
DD_RUNTIME_METRICS_ENABLED- 構成:
runtimeMetrics
デフォルト: false
ランタイムメトリクスのキャプチャを有効にするかどうか。Agent 上でポート 8125 (または DD_DOGSTATSD_PORT で構成) を UDP 用に開いておく必要があります。
Trace context propagation
有効な値と以下の構成オプションの使用に関する情報については、Node.js トレースコンテキストの伝播を参照してください。
DD_TRACE_PROPAGATION_STYLE_INJECT- 構成:
tracePropagationStyle.inject
デフォルト: Datadog,tracecontext
サービス間で分散型トレースを伝播させるために含めるヘッダーフォーマットのカンマ区切りリスト。 DD_TRACE_PROPAGATION_STYLE_EXTRACT- 構成:
tracePropagationStyle.extract
デフォルト: Datadog,tracecontext
分散型トレーシングの伝搬データを抽出しようと試みるヘッダーフォーマットのカンマ区切りリスト。完全かつ有効なヘッダーを持つ最初のフォーマットが見つかった場合、トレースを続行するためにそれが使用されます。 DD_TRACE_PROPAGATION_STYLE- 構成:
tracePropagationStyle
デフォルト: Datadog,tracecontext
分散型トレーシングの伝搬データを挿入および抽出しようと試みるヘッダーフォーマットのカンマ区切りリスト。完全かつ有効なヘッダーを持つ最初のフォーマットが見つかった場合、トレースを続行するためにそれが使用されます。存在する場合、より具体的な DD_TRACE_PROPAGATION_STYLE_INJECT と DD_TRACE_PROPAGATION_STYLE_EXTRACT の構成が優先されます。
ライブラリの操作例については、API ドキュメントを参照してください。
その他の参考資料
