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

互換性

.NET トレーサーは、.NET コア 2.1、3.1 および Microsoft が非推奨とするバージョン 2.0、2.2、3.0. での自動インスツルメンテーションをサポートしています。サポート対象のライブラリについては、互換性要件ページをご覧ください。

はじめに

アプリ内のドキュメントに従ってください (推奨)

Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:

  • デプロイコンフィギュレーション (ホスト、Docker、Kubernetes、または Amazon ECS) を範囲とする段階的な手順。
  • service、env、version タグを動的に設定します。
  • セットアップ中に App Analytics およびトレース ID お挿入を有効にします。

それ以外の場合、何らかの言語で記述されたアプリケーションのトレースを始めるには、まず Datadog Agent をインストール、構成します。.NET トレーサーはプロセス中に実行し、アプリケーションをインスツルメントし、トレースをアプリケーションから Agent に送信します。

注: .NET トレーサーは .NET ベースのすべての言語 (C#、F#、Visual Basic など) をサポートしています。

自動でデータと収集

自動インスツルメンテーションは、ゼロコード変更と最小限のコンフィギュレーションでアプリケーションのパフォーマンスデータを収集します。.NET トレーサーはすべてのサポートライブラリのインスツルメンテーションをすぐに、そして自動的に行います。

自動インスツルメンテーションは以下を取得します。

  • インスツルメンテーションされたコールの実行時間
  • Web リクエスト用 URL やステータスレスポンスコード、またはデータベースアクセス用 SQL クエリなどの関連するトレースデータ
  • 未処理の例外（該当する場合スタックトレースを含む）
  • システムを通過するトレース (例: ウェブリクエスト) の合計数

インストール

    Windows で自動インスツルメンテーションを使用するには、 Windows 用 MSI インストーラーを使ってホストに .NET トレーサーをインストールします。OS のアーキテクチャ (x64 または x86) に合致するインストーラーを選択してください。

    .NET トレーサーをインストールしたら、アプリケーションを再起動して新しい環境変数の読み込みを行います。IIS を再起動する際は、以下のコマンドを管理者として実行します。

    net stop /y was
net start w3svc

    更新: .NET トレーサーバージョン 1.8.0 以降、.NET コアでの自動インスツルメンテーションでは、Datadog.Trace.ClrProfiler.Managed NuGet パッケージは不要になりました。.NET トレーサーを更新するときに、アプリケーションから削除してください。

    Linux で自動インスツルメンテーションを使用するには、次の 3 つの手順に従います。

    1. dd-trace-dotnet リリースページから取得できるいずれかのパッケージを使って、アプリケーションが実行される環境に .NET トレーサーをインストールします。

    2. 必要な環境変数を作成します。詳細については、以下の必要な環境変数を参照してください。

    3. /opt/datadog/createLogPath.sh スクリプトを実行します。これにより、ログファイル用のディレクトリが作成され、適切なディレクトリアクセス許可が設定されます。ログファイルのデフォルトのディレクトリは /var/log/datadog/dotnet です。

    更新: .NET トレーサーバージョン 1.8.0 以降、.NET コアでの自動インスツルメンテーションでは、Datadog.Trace.ClrProfiler.Managed NuGet パッケージは不要になり、非推奨になりました。.NET トレーサーを更新するときに、アプリケーションから削除し、新しい環境変数 DD_DOTNET_TRACER_HOME を追加してください。詳細については、以下の必要な環境変数を参照してください。

    更新: .NET トレーサーバージョン 1.13.0 は、Alpine およびその他の Musl ベースのディストリビューションのサポートを追加します。

    Debian または Ubuntu の場合は、Debian パッケージをダウンロード、インストールします:

    curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb
sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb

    CentOS または Fedora の場合は、RPM パッケージをダウンロード、インストールします。

    curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<トレーサーバージョン>/datadog-dotnet-apm-<トレーサーバージョン>-1.x86_64.rpm
sudo rpm -Uvh datadog-dotnet-apm-<トレーサーバージョン>-1.x86_64.rpm

    Alpine またはその他の Musl ベースのディストリビューションの場合は、musl にリンクされたバイナリを含む tar アーカイブをダウンロードします。

    sudo mkdir -p /opt/datadog
curl -L https://github.com/DataDog/dd-trace-dotnet/releases/download/v<トレーサーバージョン>/datadog-dotnet-apm-<トレーサーバージョン>-musl.tar.gz \
| sudo tar xzf - -C /opt/datadog

    他のディストリビューションの場合は、glibc にリンクされたバイナリを含む tar アーカイブをダウンロードします。

    sudo mkdir -p /opt/datadog
curl -L https://github.com/DataDog/dd-trace-dotnet/releases/download/v<トレーサーバージョン>/datadog-dotnet-apm-<トレーサーバージョン>.tar.gz \
| sudo tar xzf - -C /opt/datadog

    必要な環境変数

      アプリケーションを IIS 内で実行している場合は、以下の手順をスキップしてください。

      IIS で実行していない Windows アプリケーションの場合は、アプリケーションの起動前に以下の 2 つの環境変数を設定し、自動インスツルメンテーションを有効にします。

      注: .NET ランタイムはプロファイラーをこれらの環境変数の設定時に開始した_あらゆる_ .NET プロセスにロードしようとします。このため、インスツルメンテーションをトレースされる必要があるアプリケーションのみに制限してください。ホストの_すべての_ .NET プロセスがプロファイラーをロードすることになるため、これらの環境変数をグローバルに設定しないでください。

      名前値
      CORECLR_ENABLE_PROFILING1
      CORECLR_PROFILER{846F5F1C-F9AE-4B07-969E-05C26BC060D8}

      Windows Services

      Windows Service を自動的にインスツルメントするには、そのサービスの環境変数を Windows Registry で設定します。Environment と呼ばれる複数文字列値を HKLM\System\CurrentControlSet\Services\<SERVICE NAME> キー に作成します。次に、キーのデータを表の値に設定します。

      CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

      これは、レジストリエディター（下図参照）を使うか PowerShell スニペットを使い実行できます。

      レジストリエディター
      [String[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<NAME> -Name Environment -Value $v

      コンソールアプリ

      アプリケーションの起動前にバッチファイルから環境変数を設定するには、

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

rem Start application
dotnet.exe example.dll

      Linux では、自動インスツルメンテーションを有効にするために次の環境変数が必要です:

      名前値
      CORECLR_ENABLE_PROFILING1
      CORECLR_PROFILER{846F5F1C-F9AE-4B07-969E-05C26BC060D8}
      CORECLR_PROFILER_PATH/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
      DD_INTEGRATIONS/opt/datadog/integrations.json
      DD_DOTNET_TRACER_HOME/opt/datadog

      注: .NET トレーサーをデフォルト以外のパスにインストールする場合は、上記のパスを変更する必要があります。

      たとえば、アプリケーションの起動前に bash ファイルから環境変数を設定するには:

      # 環境変数を設定
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
export DD_INTEGRATIONS=/opt/datadog/integrations.json
export DD_DOTNET_TRACER_HOME=/opt/datadog

# アプリケーションを起動
dotnet example.dll

      Linux Docker コンテナに環境変数を設定するには、ENV を使います:

      # 環境変数を設定
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_INTEGRATIONS=/opt/datadog/integrations.json
ENV DD_DOTNET_TRACER_HOME=/opt/datadog

# アプリケーションを起動
CMD ["dotnet", "example.dll"]

      Systemctl (サービスごと)

      systemctl を使用して、サービスとして .NET アプリケーションを実行する場合、特定のサービスに必要な環境変数がロードされるよう追加することができます。

      以下を含む、environment.env というファイルを作成します。

      CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
DD_INTEGRATIONS=/opt/datadog/integrations.json
DD_DOTNET_TRACER_HOME=/opt/datadog
# アプリケーションで使用されるその他の環境変数

      サービスのコンフィギュレーションファイルで、サービスブロックの EnvironmentFile としてこれを参照します。

      [Service]
EnvironmentFile=/path/to/environment.env
ExecStart=<アプリケーションを起動するために使用するコマンド>

      変数を設定したら、.NET サービスを再起動して環境変数を有効にします。

      Systemctl (すべてのサービス)

      systemctl を使用して、サービスとして .NET アプリケーションを実行する場合、systemctl を通じて実行されるすべてのサービスにロードされるよう環境変数を設定することも可能です。この変数が設定されていることを確認するには、systemctl show-environment を使用します。この方法を実行する前に、すべての .NET プロセスのインスツルメンテーションに関する注意を以下でご確認ください。

      systemctl set-environment CORECLR_ENABLE_PROFILING=1
systemctl set-environment CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
systemctl set-environment CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
systemctl set-environment DD_INTEGRATIONS=/opt/datadog/integrations.json
systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog

      設定できたら、環境変数がsystemctl show-environment でセットされていることを確認します。

      注: .NET ランタイムはプロファイラーをこれらの環境変数の設定時に開始した_あらゆる_ .NET プロセスにロードしようとします。このため、インスツルメンテーションをトレースされる必要があるアプリケーションのみに制限してください。ホストの_すべての_ .NET プロセスがプロファイラーをロードすることになるため、これらの環境変数をグローバルに設定しないでください。

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

      コードのインスツルメンテーションを手動で行うには、Datadog.Trace NuGet パッケージをアプリケーションに追加します。コード内で、Datadog.Trace.Tracer.Instance プロパティを通じてグローバルトレーサーにアクセスし、スパンを新規作成します。

      手動インスツルメンテーションとカスタムタグの詳細については、手動インスツルメンテーションのドキュメントを参照してください。

      手動インスツルメンテーションは、Windows の .NET Framework 4.5 以上と、Windows および Linux の .NET Core 2.1、3.0、3.1 でサポートされています。

      注: 手動と自動両方のインスツルメンテーションを使用する場合、MSI インストーラーと NuGet パッケージのバージョンの同期を保つ必要があります。

      コンフィギュレーション

      .NET トレーサーを構成する方法は複数あります:

      • 環境変数を設定する
      • .NET コードで
      • datadog.json ファイルを作成する

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

        たとえば、Windows の場合:

        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\{サービス名}\Environment を使います。

        Linux の場合

        # 環境変数を設定
export DD_TRACE_AGENT_URL=http://localhost:8126
export DD_ENV=prod
export DD_SERVICE=MyService
export DD_VERSION=abc123

# アプリケーションを起動
dotnet example.dll

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

        using Datadog.Trace;

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

// AdoNet インテグレーションを無効化
settings.Integrations["AdoNet"].Enabled = false;

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

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

        注: 設定は Tracer を作成する_前_に TracerSettings に設定される必要があります。Tracer 作成後の TracerSettings プロパティの変更は無視されます。

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

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

        構成変数

        次の表は、サポートされた構成変数の一覧です。環境変数またはコンフィギュレーションファイルの設定には最初の名前 (DD_TRACE_AGENT_URL など) を使用します。2 つ目の名前 (存在する場合、AgentUri など) は、コードの設定を変更するときに TracerSettings プロパティが使用する名前を示します。

        統合サービスタグ付け

        設定名説明
        DD_ENV

        Environment        		指定された場合、生成されたすべてのスパンに指定された値で env タグを追加します。env タグの詳細については、[Agent コンフィギュレーション][8]を参照してください。バージョン 1.17.0 以降で利用可能。
        DD_SERVICE

        ServiceName        		指定された場合、サービス名を設定します。指定されなかった場合は、.NET トレーサーがアプリケーション名から自動的にサービス名を決定しようとします (例: IIS アプリケーション名、プロセスエントリアセンブリ、またはプロセス名)。バージョン 1.17.0 以降で利用可能。
        DD_VERSION

        ServiceVersion        		指定された場合、サービスのバージョンを設定します。バージョン 1.17.0 以降で利用可能。
        DD_TAGS

        GlobalTags        		指定された場合、指定されたすべてのタグを生成されたすべてのスパンに追加します (例、layer:api,team:intake)。バージョン 1.17.0 以降で利用可能。

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

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

        次の表は、自動インスツルメンテーションと手動インスツルメンテーションの両方で利用できる構成変数の一覧です。

        設定名説明
        DD_TRACE_AGENT_URL

        AgentUri        		トレースが送信される URL エンドポイントを設定します。設定された場合、DD_AGENT_HOST と DD_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

        LogsInjectionEnabled        		アプリケーションログへの相関識別子の自動挿入を有効または無効にします。
        DD_TRACE_GLOBAL_TAGS

        GlobalTags        		指定された場合、指定されたすべてのタグを生成されたすべてのスパンに追加します。
        DD_TRACE_DEBUGデバッグのロギングを有効または無効にします。有効な値は true または false (デフォルト) です。
        DD_TRACE_HEADER_TAGS名前をタグ付けするヘッダーキー（大文字小文字の区別なし）のマップを受け入れ、一致するヘッダー値がルートスパンのタグとして自動的に提供されます。(例、CASE-insensitive-Header:my-tag-name,User-ID:userId)。バージョン 1.18.3 以降で使用可能。

        次の表は、自動インスツルメンテーションの使用時にのみ利用できる構成変数の一覧です。

        設定名説明
        DD_TRACE_ENABLED

        TraceEnabled        		すべての自動インスツルメンテーションを有効または無効にします。環境変数を false に設定すると、CLR プロファイラーが完全に無効になります。他の構成メソッドの場合は、CLR プロファイラーはロードされ続けますが、トレースは生成されません。有効な値は true (デフォルト) または false です。
        DD_TRACE_DEBUGトレーサーのデバッグログを有効または無効にします。有効な値は、true または false（デフォルト）です。これを環境変数として設定すると、CLR プロファイラーのデバッグログも有効になります。
        DD_TRACE_LOG_PATHCLR プロファイラーのログファイルのパスを設定します。

        Windows のデフォルト: %ProgramData%\Datadog .NET Tracer\logs\dotnet-profiler.log

        Linux のデフォルト: /var/log/datadog/dotnet/dotnet-profiler.log
        DD_DISABLED_INTEGRATIONS

        DisabledIntegrationNames        		無効にするインテグレーションのリストを設定します。他のインテグレーションはすべて有効のままになります。設定しなかった場合、すべてのインテグレーションが有効になります。セミコロンで区切ることで複数の値がサポートされます。有効な値は、上記のインテグレーションセクションでリストされているインテグレーション名です。
        DD_TRACE_ANALYTICS_ENABLED

        AnalyticsEnabled        		ウェブフレームワークインテグレーションのデフォルトの App Analytics 設定を有効にする省略表現。有効な値は true または false (デフォルト) です。

        次の表は、自動インスツルメンテーションの使用時にのみ利用できる構成変数の一覧で、インテグレーションごとに設定できます。環境変数またはコンフィギュレーションファイルの設定には最初の名前 (DD_<INTEGRATION>_ENABLED など) を使用します。2 つ目の名前 (Enabled など) は、コードの設定を変更する際に使用する IntegrationSettings プロパティの名前を示します。これらのプロパティには TracerSettings.Integrations[] インデクサを通じてアクセスします。インテグレーション名については、インテグレーションセクションを参照してください。注: Linux では、環境変数の名前は大文字と小文字が区別されます。

        設定名説明
        DD_TRACE_<INTEGRATION>_ENABLED

        Enabled        		特定のインテグレーションを有効または無効にします。有効な値は true (デフォルト) または false です。
        DD_TRACE_<INTEGRATION>_ANALYTICS_ENABLED

        AnalyticsEnabled        		特定のインテグレーションの App Analytics を有効または無効にします。有効な値は true または false (デフォルト) です。
        DD_TRACE_<INTEGRATION>_ANALYTICS_SAMPLE_RATE

        AnalyticsSampleRate        		特定のインテグレーションの App Analytics サンプリングレートを設定します。0.0〜1.0 (デフォルト) の浮動小数点数。

        その他の参考資料

        お役に立つドキュメント、リンクや記事:

        ソースコードGITHUB more more Datadog APM と分散型トレーシングを使用した .NET のモニタリングブログ more more サービス、リソース、トレースを調査するドキュメント more more 高度な使用方法高度な使用方法 more more