.NET Core トレーシングライブラリの構成

Docs > APM > アプリケーションインスツルメンテーション > Datadog トレーシングライブラリの構成 > .NET Core トレーシングライブラリの構成

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

.NET Tracer のコンフィギュレーション設定は、以下のいずれかの方法で行うことができます。

アプリケーションコードでトレーサーを構成するには、デフォルトの構成ソースから TracerSettings インスタンスを作成します。Tracer.Configure() を呼び出す前に、この TracerSettings インスタンスにプロパティを設定します。例:

注: 設定は、トレーサーを作成する前に TracerSettings で設定する必要があります。トレーサーの作成後に TracerSettings プロパティに加えられた変更は無視されます。

using Datadog.Trace;
using Datadog.Trace.Configuration;

// デフォルトの構成ソースを読み取る (env vars または datadog.json)
var settings = TracerSettings.FromDefaultSources();

// 一部の設定を変更
settings.Environment = "prod";
settings.ServiceName = "MyService";
settings.ServiceVersion = "abc123";
settings.Exporter.AgentUri = new Uri("http://localhost:8126/");

// Tracer のグローバル設定を構成
Tracer.Configure(settings);

JSON ファイルを使ってトレーサーを構成するには、インスツルメンテーションされたアプリケーションのディレクトリに datadog.json を作成します。ルート JSON オブジェクトは各設定のキー値を持つオブジェクトである必要があります。例:

{
  "DD_TRACE_AGENT_URL": "http://localhost:8126",
  "DD_ENV": "prod",
  "DD_SERVICE": "MyService",
  "DD_VERSION": "abc123",
}

構成設定

注: Linux では、環境変数の名前では大文字と小文字が区別されます。

上記の方法を使用して、次の変数を使用してトレースコンフィギュレーションをカスタマイズします。環境変数またはコンフィギュレーションファイルを設定するときは、環境変数の名前 (たとえば、DD_TRACE_AGENT_URL) を使用します。コードの設定を変更するときには、TracerSettings プロパティの名前 (たとえば、Exporter.AgentUri) を使用します。

統合サービスタグ付け

統合サービスタグ付けを使用するには、サービスに対して次の設定を構成します。

DD_ENV: TracerSettings プロパティ: Environment
指定した場合、生成されたすべてのスパンに、指定された値の env タグを追加します。バージョン 1.17.0 で追加されました。
DD_SERVICE: TracerSettings プロパティ: ServiceName
指定した場合、サービス名を設定します。それ以外の場合、.NET トレーサーは、アプリケーション名 (IIS アプリケーション名、プロセスエントリアセンブリ、またはプロセス名) からサービス名を自動的に判別しようとします。バージョン 1.17.0 で追加されました。
DD_VERSION: TracerSettings プロパティ: ServiceVersion
指定した場合、サービスのバージョンを設定します。バージョン 1.17.0 で追加されました。

任意のコンフィギュレーション

自動インスツルメンテーションとカスタムインスツルメンテーションの両方で、次の構成変数を利用できます。

トレース

DD_TRACE_AGENT_URL

TracerSettings property: Exporter.AgentUri
Sets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set. 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.
It can contain a Unix Domain Socket (UDS) path by prefixing the path with unix://.
Note that UDS is only supported on .NET Core 3.1 and above.
Default: http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT> if they are set, unix:///var/run/datadog/apm.socket if the file exists, or http://localhost:8126.

DD_AGENT_HOST

Agent が接続をリッスンするホストを設定します。ホスト名または IP アドレスを指定します。このパラメーターより優先される DD_TRACE_AGENT_URL を使用します。
デフォルト: localhost

DD_TRACE_AGENT_PORT

Agent が接続を待機している TCP ポートを設定します。このパラメーターより優先される DD_TRACE_AGENT_URL を使用します。Agent 構成で receiver_port または DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、DD_TRACE_AGENT_PORT または DD_TRACE_AGENT_URL はそれにマッチしなければなりません。
デフォルト: 8126

DD_TRACE_SAMPLE_RATE

TracerSettings property: GlobalSamplingRate
Default: Defaults to the rates returned by the Datadog Agent
Enables ingestion rate control. This parameter is a float representing the percentage of spans to sample. Valid values are from 0.0 to 1.0. For more information, see Ingestion Mechanisms.

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

DD_TRACE_SAMPLING_RULES

TracerSettings property: CustomSamplingRules
Default: null
A JSON array of objects. Each object must have a sample_rate. The name and service fields are optional. The sample_rate value must be between 0.0 and 1.0 (inclusive). Rules are applied in configured order to determine the trace’s sample rate. For more information, see Ingestion Mechanisms.
Examples:

Set the sample rate to 20%: [{"sample_rate": 0.2}]
Set the sample rate to 10% for services starting with ‘a’ and span name ‘b’ and set the sample rate to 20% for all other services: [{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]

DD_TRACE_RATE_LIMIT

TracerSettings プロパティ: MaxTracesSubmittedPerSecond
1 秒間に送信できるトレースの数 (DD_MAX_TRACES_PER_SECOND は非推奨)。
デフォルト: DD_TRACE_SAMPLE_RATE が設定されている場合、100。それ以外の場合は、Datadog Agent にレート制限を委ねます。

DD_SPAN_SAMPLING_RULES

Default: null
A JSON array of objects. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive). For more information, see Ingestion Mechanisms.
Example: Set the span sample rate to 50% for the service my-service and operation name http.request, up to 50 traces per second: [{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]

自動インスツルメンテーションオプションコンフィギュレーション

DD_TRACE_HEADER_TAGS: TracerSettings property:HeaderTags
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.

Example (with specified tag names): User-ID:userId
If the Request has a header User-ID, its value is applied as tag userId to the spans produced by the service.

Example (without specified tag names): User-ID
If the Request has a header User-ID, its value is applied as tag http.request.headers.User-ID.
If the Response has a header User-ID, its value is applied as tag http.response.headers.User-ID.

Added in version 1.18.3.
Response header support and entries without tag names added in version 1.26.0.
Beta: Starting in version 2.35.0, if Agent Remote Configuration is enabled where this service runs, you can set DD_TRACE_HEADER_TAGS in the Service Catalog UI.
DD_TRACE_CLIENT_IP_ENABLED: 関連する IP ヘッダーからクライアント IP を収集できるようにします。
バージョン 2.19.0 で追加されました。
デフォルト: false
DD_TRACE_CLIENT_IP_HEADER: The IP header to be used for client IP collection, for example: x-forwarded-for.
Added in version 2.19.0.
Default: Datadog parses the following: x-forwarded-for, x-real-ip, true-client-ip, x-client-ip, x-forwarded, forwarded-for, x-cluster-client-ip, fastly-client-ip, cf-connecting-ip, cf-connecting-ipv6. If several are present, the first from the list to parse correctly will be used.
DD_TAGS: TracerSettings プロパティ: GlobalTags
指定した場合、指定したすべてのタグを、生成されたすべてのスパンに追加します。
例: layer:api, team:intake, key:value
注: デリミタはコンマとスペース: , です。
バージョン 1.17.0 で追加されました。

Agent

DD_TRACE_SERVICE_MAPPING: コンフィギュレーションを使用してサービスの名前を変更します。名前を変更するサービス名（キー）と、代わりに使う名前（値）のペアを [from-key]:[to-name] の形式で指定したカンマ区切りのリストを受け入れます。
例: mysql:main-mysql-db, mongodb:offsite-mongodb-service
from-key はインテグレーションタイプに固有で、アプリケーション名のプレフィックスは取り除く必要があります。たとえば、my-application-sql-server の名前を main-db に変更するには、sql-server:main-db を使用します。バージョン 1.23.0 で追加されました。
DD_HTTP_SERVER_TAG_QUERY_STRING: true に設定すると、http.url にクエリ文字列パラメーターが含まれます。詳しくは、url 内のクエリを再編集するに記載されています。 デフォルト: true
DD_HTTP_SERVER_TAG_QUERY_STRING_SIZE: DD_HTTP_SERVER_TAG_QUERY_STRING が true のとき、難読化する前に報告するクエリ文字列の最大サイズが設定されます。サイズに制限を設けない場合は 0 を設定します。
デフォルト: 5000
DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP: DD_HTTP_SERVER_TAG_QUERY_STRING が true の場合、この正規表現は http.url タグで報告されるリクエストのクエリ文字列から機密データを削除します (マッチすると <redacted> に置き換えられます)。この正規表現は、受信するリクエストごとに実行されます。
DD_INSTRUMENTATION_TELEMETRY_ENABLED: Datadog は、製品の改良のため、システムの環境・診断情報を収集することがあります。false の場合、このテレメトリーデータは収集されません。
デフォルト: true

Diagnostic logs

DD_TRACE_LOG_DIRECTORY: .NET Tracer ログのディレクトリを設定します。
デフォルト: Windows は %ProgramData%\Datadog .NET Tracer\logs\、Linux は /var/log/datadog/dotnet
DD_TRACE_LOGFILE_RETENTION_DAYS: トレーサーの起動中に、この構成は、トレーサーの現在のログディレクトリを使用して、指定された日数と同じかそれよりも古いログファイルを削除します。バージョン 2.19.0 で追加されました。
デフォルト: 31
DD_TRACE_LOGGING_RATE: ログメッセージへのレート制限を設定します。設定した場合、x 秒ごとに一意のログ行が記述されます。たとえば、任意のメッセージを 60 秒ごとに一回ログに残したい場合は 60 を設定します。ログのレート制限を無効化したい場合は 0 を設定します。バージョン 1.24.0 で追加されました。デフォルトでは無効です。

OpenTelemetry

DD_TRACE_OTEL_ENABLED: Enables or disables OpenTelemetry based tracing, both for custom or automatic instrumentation. Valid values are: true or false.
Default: false

自動インスツルメンテーションオプション構成

以下の構成変数は、自動インスツルメンテーションの使用時にのみ利用できます。

トレース

DD_TRACE_ENABLED: TracerSettings property: TraceEnabled
Enables or disables all instrumentation. Valid values are: true or false.
Default: true Note: Setting the environment variable to false completely disables the client library, and it cannot be enabled through other configuration methods. If it is set to false through another configuration method (not an environment variable), the client library is still loaded, but traces will not be generated.
DD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLED: ASP.NET/ASP.NET Core 用アプリケーションのすべてのルートパラメーター (ID パラメーターを除く) を拡張します
これは、フォームの値を区別するためにパラメーター名を使用している場合や、GraphQL のようなスラッグを使用している場合に便利です。 デフォルト: false バージョン 2.5.1 で追加されました。
DD_TRACE_METHODS: トレースするメソッドのリスト。セミコロン (;) で区切られたリストで、各エントリーが Namespace.TypeName[MethodNames] という形式であることを指定します (MethodNames はカンマ (,) 区切りのメソッド名のリストまたは * ワイルドカードのいずれかです)。汎用型の場合は、角括弧と型パラメーターの名前をバックスティック( ) に置き換え、その後に汎用型パラメーターの数を記述します。例えば、Dictionary<TKey, TValue> は Dictionary`2 と記述しなければなりません。汎用メソッドの場合は、指定する必要があるのはメソッド名のみです。
例: Namespace1.Class1[Method1,GenericMethod];Namespace1.GenericTypeWithOneTypeVariable`1[ExecuteAsync];Namespace2.Class2[*]
注: ワイルドカードメソッドサポート ([*]) は、コンストラクタ、プロパティゲッターとセッター、 Equals、Finalize、GetHashCode そして ToString 以外の型のすべてのメソッドを選択します。
バージョン 2.6.0 で追加されました。ワイルドカードのサポート [*] はバージョン 2.7.0 で追加されました。
DD_TRACE_KAFKA_CREATE_CONSUMER_SCOPE_ENABLED: Kafka コンシューマースパンの動作を変更します
デフォルト: true
true に設定すると、メッセージが消費されたときにコンシューマースパンが作成され、次のメッセージを消費する前に閉じられます。このスパンの長さは、あるメッセージの消費と次のメッセージの消費との間の計算を代表するものです。この設定は、メッセージの消費がループで実行される場合に使用します。
false に設定すると、メッセージが消費されたときにコンシューマスパンが作成され、すぐに閉じられます。この設定は、メッセージが完全に処理されないまま次のメッセージを消費する場合や、複数のメッセージを一度に消費する場合に使用します。このパラメーターを false に設定すると、コンシューマースパンはすぐに閉じられます。トレースする子スパンがある場合は、コンテキストを手動で抽出する必要があります。詳しくは、ヘッダーの抽出と挿入をお読みください。

データベースモニタリング

DD_DBM_PROPAGATION_MODE: Enables linking between data sent from APM and the Database Monitoring product when set to service or full. The service option enables the connection between DBM and APM services. The full option enables connection between database spans with database query events. Available for Postgres and MySQL.
Default: disabled

ランタイムメトリクス

DD_RUNTIME_METRICS_ENABLED: .NET ランタイムメトリクスを有効にします。有効な値は true または false です。
デフォルト: false
バージョン 1.23.0 で追加されました。

エラー

DD_HTTP_CLIENT_ERROR_STATUSES: HTTP クライアントスパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 400-499
DD_HTTP_SERVER_ERROR_STATUSES: HTTP サーバースパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 500-599

Logs

DD_LOGS_INJECTION: TracerSettings property: LogsInjectionEnabled
Enables or disables automatic injection of correlation identifiers into application logs.
Your logger needs to have a source that sets the trace_id mapping correctly. The default source for .NET Applications, csharp, does this automatically. For more information, see correlated logs in the Trace ID panel.

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

自動インスツルメンテーションインテグレーション構成

次の表に、自動インスツルメンテーションを使用しており、インテグレーションごとの設定が可能な場合にのみ使用できる構成変数を示します。

DD_DISABLED_INTEGRATIONS: TracerSettings プロパティ: DisabledIntegrationNames
無効にするインテグレーションのリストを設定します。他のインテグレーションはすべて有効のままになります。設定しなかった場合、すべてのインテグレーションが有効になります。セミコロンで区切ることで複数の値がサポートされます。有効な値は、インテグレーションセクションでリストされているインテグレーション名です。
DD_TRACE_<INTEGRATION_NAME>_ENABLED: TracerSettings プロパティ: Integrations[<INTEGRATION_NAME>].Enabled

特定のインテグレーションを有効または無効にします。有効な値は、true (デフォルト) または false です。インテグレーション名は、インテグレーションセクションにリストされています。 デフォルト: true

試験機能

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

DD_TRACE_PARTIAL_FLUSH_ENABLED: Datadog Agent への大規模トレースのフラッシュをインクリメント形式で有効化し、Agent に拒否される可能性を低減します。保持期間が長いトレースまたは多数のスパンを持つトレースがある場合にのみ使用してください。有効な値は true または false です。バージョン 1.26.0 で追加され、Datadog Agent 7.26.0 以降とのみ互換性を有しています。
デフォルト: false

非推奨の設定

DD_TRACE_LOG_PATH: 自動インスツルメンテーションログファイルにパスを設定し、他の .NET Tracer ログファイルすべてのディレクトリを決定します。DD_TRACE_LOG_DIRECTORY が設定されている場合、無視されます。
DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED: true に設定すると、Web スパンに対する改善されたリソース名を有効化します。利用可能なルートテンプレート情報を使用して ASP.NET のコアインテグレーションにスパンを追加し、追加のタグを有効化します。バージョン 1.26.0 で追加されました。2.0.0 ではデフォルトで有効になっています。
デフォルト: true