.NET Framework アプリケーションのトレース

.NET Framework アプリケーションのトレース

互換性要件

.NET トレーサーは、.NET Framework 4.5 以上の自動インスツルメンテーションをサポートします。サポート対象のライブラリについては、互換性要件ページをご覧ください。

インストールと利用開始

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

注: 自動インスツルメンテーションとカスタムインスツルメンテーションの両方を使用している場合は、パッケージバージョン (MSI や NuGet など) の同期を維持することが重要です。

次の手順に従って .NET アプリケーションのトレーシングを開始します。

IIS でホストされているアプリケーション

IIS でホストされているアプリケーションのトレースを開始するには:

  1. Windows Datadog Agent をインストールして構成します。

  2. .NET トレーサー MSI インストーラーをダウンロードします。オペレーティングシステム (x64 または x86) に一致するアーキテクチャの MSI インストーラーを選択します。

  3. 管理者権限で .NET トレーサー MSI インストーラーを実行します。

  4. 管理者として次のコマンドに従って、IIS を停止してから起動します。

    Note: You must use a stop and start command. This is not the same as a reset or restart command.
    net stop /y was
    net start w3svc
    
  5. アプリケーションロードを作成します。

  6. APM ライブトレースにアクセスします。

IIS でホストされていないアプリケーション

IIS に存在しない Windows アプリケーションの自動インスツルメンテーションを有効にするには、アプリケーションを起動する前に 2 つの環境変数を設定する必要があります。

名前
COR_ENABLE_PROFILING 1
COR_PROFILER {846F5F1C-F9AE-4B07-969E-05C26BC060D8}
注: .NET ランタイムは、これらの環境変数が設定された状態で開始されたあらゆる .NET プロセスにプロファイラーをロードしようとします。インスツルメンテーションは、トレースする必要のあるアプリケーションのみに制限する必要があります。これらの環境変数をグローバルに設定しないでください。こうすると、ホスト上のすべての .NET プロセスがプロファイラーをロードします。
Windows サービス

Windows サービスを自動的にインスツルメントするには、COR_ENABLE_PROFILING および COR_PROFILER 環境変数を設定します。

  1. Windows レジストリエディタで、HKLM\System\CurrentControlSet\Services\<SERVICE NAME>Environment という複数の文字列値を作成します。

  2. 値データを次のように設定します。

    COR_ENABLE_PROFILING=1
    COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    

または、次の PowerShell スニペットを使用して環境変数を設定することもできます。

add-env-var.ps1

   [String[]] $v = @("COR_ENABLE_PROFILING=1", "COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
   Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<NAME> -Name Environment -Value $v
   
コンソールアプリケーション

コンソールアプリケーションを自動的にインスツルメントするには、アプリケーションを起動する前に、バッチファイルから COR_ENABLE_PROFILING および COR_PROFILER 環境変数を設定します。

rem Set environment variables
SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Start application
example.exe

APM に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は datadog.yaml ファイルの apm_enabled: true で有効になっており、localhost:8126 でトレーストラフィックをリッスンします。コンテナ化環境の場合、アプリ内のクイックスタート手順に従って、Datadog Agent 内でトレース収集を有効にします。

確実に Datadog Agent の DD_SITE に設定して、Agent が正しい Datadog の場所にデータを送信するようにします。

カスタムインスツルメンテーション

注: 自動インスツルメンテーションとカスタムインスツルメンテーションの両方を使用している場合は、パッケージバージョン (MSI や NuGet など) の同期を維持することが重要です。

.NET アプリケーションでカスタムインスツルメンテーションを使用するには

  1. Datadog.Trace NuGet パッケージをアプリケーションに追加します。
  2. アプリケーションコードで、Datadog.Trace.Tracer.Instance プロパティを介してグローバルトレーサーにアクセスし、新しいスパンを作成します。

カスタムインスツルメンテーションとカスタムタグ付けの詳細については、.NET カスタムインスツルメンテーションを参照してください。

コンフィギュレーション

.NET トレーサーには、次のいずれかの方法で設定できるコンフィギュレーション設定があります。

環境変数を使ってトレーサーを構成するには、インスツルメンテーションされたアプリケーションを起動する前に変数を設定します。

例:

rem Set environment variables
SET DD_TRACE_AGENT_URL=http://localhost:8126
SET DD_ENV=prod
SET DD_SERVICE=MyService
SET DD_VERSION=abc123

rem Launch application
example.exe
注: Windows Service に対して環境変数を設定するには、上記のように Windows レジストリで複数文字列キーHKLM\System\CurrentControlSet\Services\{service name}\Environment を使います。

アプリケーションコードでトレーサーを構成するには、デフォルトの構成ソースから TracerSettings インスタンスを作成します。Tracer コンストラクタに渡す前にこの 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.AgentUri = new Uri("http://localhost:8126/");

// この設定を使ってトレーサーを新規作成
var tracer = new Tracer(settings);

// グローバルトレーサーを設定
Tracer.Instance = tracer;

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 プロパティの名前 (たとえば、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 プロパティ: AgentUri

トレースが送信される URL エンドポイントを設定します。設定された場合、DD_AGENT_HOSTDD_TRACE_AGENT_PORT をオーバーライドします。 デフォルト: http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>
DD_AGENT_HOST
トレースが送信されるホストを設定します (Agent を実行するホスト)。ホスト名または IP アドレスにできます。DD_TRACE_AGENT_URL が設定されている場合は無視されます。
デフォルト: localhost
DD_TRACE_AGENT_PORT
トレースが送信されるポートを設定します (Agent が接続のためにリッスンしているポート)。DD_TRACE_AGENT_URL が設定されている場合は無視されます。
デフォルト: 8126
DD_LOGS_INJECTION
TracerSettings プロパティ: LogsInjectionEnabled
アプリケーションログへの相関識別子の自動挿入を有効または無効にします。
DD_TRACE_DEBUG
TracerSettings プロパティ: DebugEnabled

デバッグのロギングを有効または無効にします。有効な値は true または false です。 デフォルト: false
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 で追加されました。
DD_TAGS
TracerSettings プロパティ: GlobalTags
指定した場合、指定したすべてのタグを、生成されたすべてのスパンに追加します。バージョン 1.17.0 で追加されました。
: layer:api,team:intake
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_TRACE_ENABLED
TracerSettings プロパティ: TraceEnabled

すべての自動インスツルメンテーションを有効または無効にします。環境変数を false に設定すると、CLR プロファイラーが完全に無効になります。他の構成メソッドの場合は、CLR プロファイラーはロードされ続けますが、トレースは生成されません。有効な値は true または falseデフォルト: true
DD_TRACE_LOG_DIRECTORY
.NET Tracer ログのディレクトリを設定します。
デフォルト: %ProgramData%\Datadog .NET Tracer\logs\
DD_TRACE_LOG_PATH
自動インスツルメンテーション・ログファイルにパスを設定し、他の .NET Tracer ログファイルすべてのディレクトリを決定します。DD_TRACE_LOG_DIRECTORY が設定されている場合、無視されます。
DD_DISABLED_INTEGRATIONS
TracerSettings プロパティ: DisabledIntegrationNames
無効にするインテグレーションのリストを設定します。他のインテグレーションはすべて有効のままになります。設定しなかった場合、すべてのインテグレーションが有効になります。セミコロンで区切ることで複数の値がサポートされます。有効な値は、インテグレーションセクションでリストされているインテグレーション名です。
DD_HTTP_CLIENT_ERROR_STATUSES
HTTP クライアントスパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 400-499
DD_HTTP_SERVER_ERROR_STATUSES
HTTP サーバースパンがエラーとしてマークされる原因となるステータスコード範囲を設定します。
デフォルト: 500-599
DD_RUNTIME_METRICS_ENABLED
.NET ランタイムメトリクスを有効にします。有効な値は true または false です。バージョン 1.23.0 で追加されました。
デフォルト: false
DD_TRACE_ADONET_EXCLUDED_TYPES
TracerSettings プロパティ: AdoNetExcludedTypes
自動インスツルメンテーションから除外される AdoNet タイプ (たとえば、System.Data.SqlClient.SqlCommand) のリストを設定します。

インテグレーションコンフィギュレーションを無効にする

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

DD_TRACE_<INTEGRATION_NAME>_ENABLED
TracerSettings プロパティ: Integrations[<INTEGRATION_NAME>].Enabled

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

試験機能

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

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

その他の参考資料