Node.js トレーシングライブラリの構成

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

トレーサーの設定は、以下の環境変数で構成することができます。

タグ付け

DD_ENV
構成: env
デフォルト: Datadog Agent で構成された環境
アプリケーションの環境を設定します (例えば、prodpre-prodstage など)。
DD_SERVICE
構成: service
デフォルト: package.jsonname フィールド
このアプリケーションで使用するサービス名。
DD_VERSION
構成: version
デフォルト: package.jsonversion フィールド
アプリケーションのバージョン番号。
DD_TAGS
構成: tags
デフォルト: {}
すべてのスパンおよびランタイムメトリクスに適用されるグローバルタグを設定します。環境変数として渡される場合、形式は key:value,key:value となります。プログラムで設定する場合は、tracer.init({ tags: { foo: 'bar' } }) のような形式になります。

サービスに envserviceversion を設定するには、DD_ENVDD_SERVICEDD_VERSION を使用することをおすすめします。このような環境変数の構成におすすめについては、統合サービスタグ付けのドキュメントをご参照ください。

インスツルメンテーション

DD_TRACE_ENABLED
構成: N/A
デフォルト: true
dd-trace を有効にするかどうか。false に設定すると、ライブラリの全ての機能が無効になります。
DD_TRACE_DEBUG
構成: N/A
デフォルト: false
トレーサーのデバッグロギングを有効にします。
DD_TRACING_ENABLED
構成: N/A
デフォルト: true
トレースを有効にするかどうか。
DD_TRACE_AGENT_URL
構成: url
デフォルト: http://localhost:8126
トレーサーが送信するトレース 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 のポート。
DD_DOGSTATSD_PORT
構成: dogstatsd.port
デフォルト: 8125
メトリクスの送信先となる DogStatsD Agent のポート。
DD_LOGS_INJECTION
構成: logInjection
デフォルト: false
対応するログライブラリのログにトレース ID の自動挿入を有効にします。
DD_TRACE_SAMPLE_RATE
構成: sampleRate
デフォルト: Agent に判断を委ねます。
Agent とバックエンド間の取り込みサンプルレート (0.0~1.0 の間) を制御します。
DD_TRACE_RATE_LIMIT
構成: rateLimit
デフォルト: DD_TRACE_SAMPLE_RATE が設定されている場合は、1.0。そうでない場合は、Datadog Agent にレート制限を委ねます。 0.01.0 の間の浮動小数点数で、サンプリングするスパンの比率を指定します。
DD_TRACE_SAMPLING_RULES
構成: samplingRules
デフォルト: []
優先的にサンプリングする際に適用するサンプリングルール。オブジェクトの JSON 配列。各オブジェクトは、0.0 から 1.0 の間の sample_rate 値を持たなければなりません (この値を含む)。各ルールはオプションで nameservice フィールドを持ち、これらはトレースの servicename に対してマッチする正規表現文字列です。ルールは、トレースのサンプルレートを決定するために設定された順番で適用されます。省略された場合、トレーサーは Agent に従い、すべてのトレースでサンプルレートを動的に調整します。
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_RUNTIME_METRICS_ENABLED
構成: runtimeMetrics
デフォルト: false
ランタイムメトリクスのキャプチャを有効にするかどうか。Agent 上でポート 8125 (または DD_DOGSTATSD_PORT で構成) を UDP 用に開いておく必要があります。
DD_SERVICE_MAPPING
構成: serviceMapping
デフォルト: N/A
: mysql:my-mysql-service-name-db,pg:my-pg-service-name-db
各プラグインのサービス名を提供します。カンマ区切りの plugin:service-name ペア (スペースありまたはなし) を許容します。
DD_TRACE_DISABLED_PLUGINS
構成: N/A
デフォルト: N/A
: DD_TRACE_DISABLED_PLUGINS=express,dns
トレーサー初期化時に自動的に無効になるインテグレーション名のカンマ区切り文字列。
DD_TRACE_LOG_LEVEL
構成: logLevel
デフォルト: debug
デバッグログが有効な場合に、トレーサーが使用する最小のログレベルを表す文字列で、例えば errordebug などです。
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_PROFILING_ENABLED
構成: profiling
デフォルト: false
プロファイリングを有効にするかどうか。
DD_TRACE_REPORT_HOSTNAME
構成: reportHostname
デフォルト: false
各トレースについて、システムのホスト名を報告するかどうか。無効の場合、Agent のホスト名が代わりに使用されます。
Experimental Features
構成: experimental
デフォルト: {}
実験的な機能は、あらかじめ定義されたキーに true という値を追加することで有効にすることができます。利用可能な実験的機能の詳細については、サポートに連絡してください。
Automatically Instrument External Libraries
構成: plugins
デフォルト: true
ビルトインプラグインを使用して、外部ライブラリの自動インスツルメンテーションを有効にするかどうか。
DD_TRACE_STARTUP_LOGS
構成: startupLogs
デフォルト: false
トレーサーのスタートアップ構成と診断ログを有効にします。
DD_DBM_PROPAGATION_MODE
構成: dbmPropagationMode
デフォルト: 'disabled'
タグインジェクションを用いた DBM と APM のリンクを有効にするには、'service' または 'full' に設定します。'service' オプションは DBM と APM サービス間の接続を可能にします。'full' オプションは、データベースクエリイベントを持つデータベーススパン間の接続を可能にします。Postgres で利用可能です。
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
攻撃報告において、機密データをその値で冗長化するための正規表現文字列。

ライブラリの操作例については、API ドキュメントを参照してください。

その他の参考資料