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

Docs > APM > Datadog へのトレースの送信 > Datadog トレーシングライブラリの構成 > .NET Framework トレーシングライブラリの構成

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

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

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

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

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

// デフォルトの構成ソースを読み取る (env vars、web.config、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);

app.config または web.config ファイルを使ってトレーサーを構成するには、<appSettings> セクションを使います。例:

<configuration>
  <appSettings>
    <add key="DD_TRACE_AGENT_URL" value="http://localhost:8126"/>
    <add key="DD_ENV" value="prod"/>
    <add key="DD_SERVICE" value="MyService"/>
    <add key="DD_VERSION" value="abc123"/>
  </appSettings>
</configuration>

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

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

コンフィギュレーション設定

上記の方法を使用して、次の変数を使用してトレースコンフィギュレーションをカスタマイズします。環境変数またはコンフィギュレーションファイルを設定するときは、環境変数の名前 (たとえば、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 プロパティ: Exporter.AgentUri
トレースが送信される URL のエンドポイントを設定します。設定されている場合は DD_AGENT_HOST と DD_TRACE_AGENT_PORT をオーバーライドします。Agent 構成で receiver_port または DD_APM_RECEIVER_PORT をデフォルトの 8126 以外に設定した場合、DD_TRACE_AGENT_PORT または DD_TRACE_AGENT_URL はそれにマッチしなければなりません。
デフォルト: 設定されている場合は http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>、または 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 プロパティ: GlobalSamplingRate
デフォルト: デフォルトは、Datadog Agent から返される率です
取り込み率コントロールを有効にします。このパラメーターは、サンプリングするスパンのパーセンテージを表す浮動小数点数です。有効な値は 0.0 から 1.0 までです。詳しくは、取り込みメカニズムを参照してください。

ベータ版: バージョン 2.35.0 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログの UI で DD_TRACE_SAMPLE_RATE を設定できます。

DD_TRACE_SAMPLING_RULES

TracerSettings プロパティ: CustomSamplingRules
デフォルト: null
オブジェクトの JSON 配列。各オブジェクトは "sample_rate" を持たなければなりません。"name" と "service" フィールドは省略可能です。"sample_rate" の値は 0.0 と 1.0 の間でなければなりません (この値を含む)。ルールは、トレースのサンプルレートを決定するために設定された順序で適用されます。詳しくは、取り込みメカニズムを参照してください。
例:

サンプルレートを 20% に設定: '[{"sample_rate": 0.2}]'
‘a’ で始まるサービスとスパン名 ‘b’ のサービスのサンプルレートを 10% に、それ以外のサービスのサンプルレートを 20% に設定: '[{"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

デフォルト: null

オブジェクトの JSON 配列。ルールは、スパンのサンプルレートを決定するために構成された順序で適用されます。sample_rate の値は、0.0 から 1.0 までの間でなければなりません (この値を含む)。詳しくは、[取り込みメカニズム][1]を参照してください。例: サービス名 my-service と操作名 http.request のスパンのサンプルレートを 50% に設定し、最大で 1 秒間に 50 個のトレースにします: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'

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

DD_TRACE_HEADER_TAGS: TracerSettings プロパティ:HeaderTags
大文字と小文字を区別しないヘッダーキーとタグ名のキーと値のペアのカンマ区切りリストを受け入れ、一致するヘッダー値をルートスパンのタグとして自動的に適用します。特定のタグ名のないエントリも受け入れます。
例: CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
バージョン 1.18.3 で追加されました。レスポンスヘッダーのサポートとタグ名なしのエントリはバージョン 1.26.0 で追加されました。

ベータ版: バージョン 2.35.0 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログの UI で DD_TRACE_HEADER_TAGS を設定できます。
DD_TRACE_CLIENT_IP_ENABLED: 関連する IP ヘッダーからクライアント IP を収集できるようにします。
バージョン 2.19.0 で追加されました。
デフォルト: false
DD_TRACE_CLIENT_IP_HEADER: クライアント IP の収集に使用する IP ヘッダー、例: x-forwarded-for
バージョン 2.19.0 で追加されました。
デフォルト: Datadog は以下をパースします: "x-forwarded-for", "x-real-ip", "client-ip", "x-forwarded", "x-cluster-client-ip", "forwarded-for", "forwarded", "via", "true-client-ip" 複数存在する場合は、何も報告されません。
DD_TAGS: TracerSettings プロパティ: GlobalTags
指定した場合、指定したすべてのタグを、生成されたすべてのスパンに追加します。
例: layer:api, team:intake, key:value
注: デリミタはコンマとスペース: , です。
バージョン 1.17.0 で追加されました。
DD_TRACE_LOG_DIRECTORY: .NET Tracer ログのディレクトリを設定します。
デフォルト: %ProgramData%\Datadog .NET Tracer\logs\
DD_TRACE_LOGGING_RATE: ログメッセージへのレート制限を設定します。設定した場合、x 秒ごとに一意のログ行が記述されます。たとえば、任意のメッセージを 60 秒ごとに一回ログに残したい場合は 60 を設定します。ログのレート制限を無効化したい場合は 0 を設定します。バージョン 1.24.0 で追加されました。デフォルトでは無効です。
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

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

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

DD_TRACE_ENABLED: TracerSettings プロパティ: TraceEnabled

すべての自動インスツルメンテーションを有効または無効にします。環境変数を false に設定すると、CLR プロファイラーが完全に無効になります。他の構成メソッドの場合は、CLR プロファイラーはロードされ続けますが、トレースは生成されません。有効な値は true または false です。 デフォルト: true
DD_DBM_PROPAGATION_MODE: 'service' または 'full' に設定すると、APM から送信されるデータとデータベースモニタリング製品との連携が可能になります。'service' オプションは、DBM と APM のサービス間の接続を有効にします。'full' オプションは、データベースクエリイベントを持つデータベーススパン間の接続を有効にします。Postgres と MySQL で利用可能です。
デフォルト: 'disabled'
DD_HTTP_CLIENT_ERROR_STATUSES: HTTP クライアントスパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 400-499
DD_HTTP_SERVER_ERROR_STATUSES: HTTP サーバースパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 500-599
DD_LOGS_INJECTION: TracerSettings プロパティ: LogsInjectionEnabled
アプリケーションログに相関識別子を自動的に注入することを有効または無効にします。
ロガーは trace_id のマッピングを正しく設定する source を持つ必要があります。.NET アプリケーションのデフォルトのソースである csharp は、自動的にこれを行います。詳しくは、トレース ID パネルの相関するログを参照してください。

ベータ版: バージョン 2.35.0 から、このサービスが実行される場所で Agent リモート構成が有効になっている場合、サービスカタログの UI で DD_LOGS_INJECTION を設定できます。
DD_RUNTIME_METRICS_ENABLED: .NET ランタイムメトリクスを有効にします。有効な値は true または false です。
デフォルト: false
バージョン 1.23.0 で追加されました。
DD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLED: ASP.NET/ASP.NET Core 用アプリケーションのすべてのルートパラメーター (ID パラメーターを除く) を拡張します
これは、フォームの値を区別するためにパラメーター名を使用している場合や、GraphQL のようなスラッグを使用している場合に便利です。 デフォルト: false バージョン 2.5.2 で追加されました
DD_TRACE_METHODS: トレースするメソッドのリスト。セミコロン (;) で区切られたリストで、各エントリーが 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_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