互換性要件

サポートされている .NET Core のランタイム

.NET Tracer は、.NET Core 2.1、3.1、.NET 5、.NET 6、.NET 7. でのインスツルメンテーションをサポートします。

Datadog の .NET Core ライブラリとプロセッサアーキテクチャーのサポート一覧 (レガシーバージョンとメンテナンスバージョンを含む) については、互換性要件を参照してください。

インストールと利用開始

Datadog は、最高の体験を得るために、Datadog アプリのクイックスタートの説明書に従うことをお勧めします。これには以下が含まれます。
- デプロイメント構成 (ホスト、Docker、Kubernetes、または Amazon ECS) に合わせたステップバイステップの説明。
- サービスタグ、環境タグ、バージョンタグを動的に設定する。
- セットアップ時にトレースの 100% インジェストとログへのトレース ID インジェクションを有効にする。

また、AWS Lambda で Datadog APM を設定するには、サーバーレス関数のトレース、Azure App Service では、Azure App Service のトレースをご覧ください。
**注**: Datadog 自動インスツルメンテーションは、.NET CLR Profiling API に依存します。この API に許可されるサブスクライバーは 1 つのみです(たとえば Datadog の .NET トレーサーでプロファイラーを有効にした状態)。可視性を最大限に向上するため、アプリケーション環境で 1 つの APM ソリューションのみを実行してください。
トリミングされたアプリをインスツルメンテーションするには、プロジェクトで Datadog.Trace.Trimming NuGet パッケージを参照してください。トリミングされたアプリのサポートはベータ版です。

インストール

  1. APM 用に Datadog Agent を構成します。
  2. トレーサーをインストールします。
  3. Enable the tracer for your service.
  4. ライブデータを表示します。

APM 用に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は apm_config 下にある datadog.yaml ファイルの enabled: true で有効になっており、http://localhost:8126 でトレースデータをリッスンします。

コンテナ化、サーバーレス、クラウド環境の場合:

  1. メイン datadog.yaml コンフィギュレーションファイルapm_config セクションで apm_non_local_traffic: true を設定します。

  2. コンテナ化された環境でトレースを受信するように Agent を構成する方法については、それぞれの説明を参照してください。

Docker
Kubernetes
Amazon ECS
ECS Fargate

  1. トレースクライアントは以下にトレースの送信を試みます。

    • デフォルトでは /var/run/datadog/apm.socket の Unix ドメインソケット。
    • ソケットが存在しない場合、トレースは localhost:8126 に送信されます。
    • もし、別のソケット、ホスト、ポートが必要な場合は、環境変数 DD_TRACE_AGENT_URL を使用します: DD_TRACE_AGENT_URL=http://custom-hostname:1234 または DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
    • トレース転送に Unix Domain Socket を使用することは、.NET Core 3.1 以降でサポートされています。

これらの設定方法の詳細については、構成を参照してください。

  1. Agent が正しい Datadog のロケーションにデータを送信するようにするには、Datadog Agent で DD_SITE に設定します。

トレースは、HerokuCloud FoundryAWS Elastic Beanstalk など、他の環境で利用できます。

その他のすべての環境については、その環境のインテグレーションのドキュメントを参照し、セットアップの問題が発生した場合は Datadog サポートにお問い合わせください。

トレーサーをインストールする

Kubernetes アプリケーション、または Linux ホストやコンテナ上のアプリケーションからトレースを収集する場合、以下の説明の代わりに、アプリケーションにトレーシングライブラリを挿入することができます。手順については、ライブラリの挿入をお読みください。

Datadog .NET Tracer は、マシン上のすべてのサービスがインスツルメントされるようにマシン全体にインストールすることも、アプリケーションごとにインストールすることも可能で、開発者はアプリケーションの依存関係を通じてインスツルメンテーションを管理することができます。マシン全体のインストール手順を見るには、Windows または Linux タブをクリックします。アプリケーションごとのインストール手順を見るには、NuGet タブをクリックします。

.NET Tracer をマシン全体にインストールするには

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

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

PowerShell で次を実行することで、MSI セットアップをスクリプト化することもできます: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'

.NET Tracer をマシン全体にインストールするには

  1. お使いの OS とアーキテクチャに対応した最新の .NET Tracer パッケージをダウンロードします。

  2. 以下のコマンドのいずれかを実行して、パッケージをインストールし、適切な権限で .NET トレーサーのログディレクトリ /var/log/datadog/dotnet を作成します。

    Debian または Ubuntu
    sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && /opt/datadog/createLogPath.sh
    CentOS または Fedora
    sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /opt/datadog/createLogPath.sh
    Alpine などの musl ベースの分布
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>-musl.tar.gz && sh /opt/datadog/createLogPath.sh
    その他の分布
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && /opt/datadog/createLogPath.sh
注: このインストールは、IIS で動作するアプリケーションをインスツルメントするものではありません。IIS で実行されるアプリケーションについては、Windows マシン全体のインストールプロセスに従ってください。

.NET Tracer をアプリケーション単位でインストールするには

  1. Datadog.Trace.Bundle NuGet パッケージをアプリケーションに追加します。

サービスのトレーサーを有効にする

サービスの .NET Tracer を有効にするには、必要な環境変数を設定し、アプリケーションを再起動します。

環境変数の設定方法の違いについては、プロセス環境変数の構成を参照してください。

Internet Information Services (IIS)

  1. .NET Tracer の MSI インストーラーは、必要な環境変数をすべて追加します。構成する必要のある環境変数はありません。

    Note: You must set the .NET CLR version for the application pool to No Managed Code as recommended by Microsoft.
  2. IIS でホストされるアプリケーションを自動でインスツルメントするには、管理者として次のコマンドを実行して IIS を完全に停止してから起動します。

    net stop /y was
    net start w3svc
    # Also, start any other services that were stopped when WAS was shut down.
    
    Note: Always use the commands above to completely stop and restart IIS to enable the tracer. Avoid using the IIS Manager GUI application or iisreset.exe.

IIS にないサービス

v2.14.0 より、MSI を使用してトレーサーをインストールした場合、CORECLR_PROFILER を設定する必要がありません。
  1. 自動インスツルメンテーションをアプリケーションにアタッチするために、以下の必要な環境変数を設定します。

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    
  2. スタンドアロンアプリケーションや Windows サービスの場合は、手動でアプリケーションを再起動します。

  1. 自動インスツルメンテーションをアプリケーションにアタッチするために、以下の必要な環境変数を設定します。

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
    DD_DOTNET_TRACER_HOME=/opt/datadog
    
  2. スタンドアロンアプリケーションの場合は、通常通り手動でアプリケーションを再起動します。

パッケージの Readme に書かれている手順に従ってください。dd-trace-dotnet リポジトリでも公開されています。 Docker のサンプルもリポジトリで公開されています。

ライブデータの表示

サービスの .NET Tracer を有効にした後:

  1. サービスを再起動します。

  2. アプリケーションロードを作成します。

  3. Datadog で APM > APM Traces の順に移動します。

構成

必要に応じて、統合サービスタグ付けの設定など、アプリケーションパフォーマンスのテレメトリーデータを送信するためのトレースライブラリーを構成します。詳しくは、ライブラリの構成を参照してください。

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

カスタムインスツルメンテーションのセットアップは、自動インスツルメンテーションによって異なり、メソッドによっては追加の手順が含まれます。

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

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

  1. Datadog.Trace NuGet パッケージをアプリケーションに追加します。
  2. アプリケーションコードで、Datadog.Trace.Tracer.Instance プロパティを介してグローバルトレーサーにアクセスし、新しいスパンを作成します。
注: 自動インスツルメンテーションとカスタムインスツルメンテーションの両方を使用している場合は、パッケージバージョン (MSI や NuGet など) の同期を維持する必要があります。

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

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

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

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

カスタムインスツルメンテーションのスパンやタグの追加について詳しくは、.NET カスタムインスツルメンテーションのドキュメントを参照してください。

プロセス環境変数の構成

サービスに自動インスツルメンテーションをアタッチするには、アプリケーションを起動する前に、必要な環境変数を設定する必要があります。.NET Tracer のインストール方法に応じて設定する環境変数を特定するために、 サービスのトレーサーを有効にするのセクションを参照し、以下の例に従って、インスツルメントされたサービスの環境に基づいて環境変数を正しく設定します。

Windows

Windows サービス

v2.14.0 より、MSI を使用してトレーサーをインストールした場合、CORECLR_PROFILER を設定する必要がありません。

レジストリエディターで、HKLM\System\CurrentControlSet\Services\<SERVICE NAME> キーに Environment 複数の文字列値を作成します。

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
レジストリエディタを使用して Windows サービスに環境変数を作成
[string[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<SERVICE NAME> -Name Environment -Value $v

IIS

MSI をインストールした後、IIS サイトを自動的にインスツルメンテーションするための追加構成は必要ありません。すべての IIS サイトに継承される追加の環境変数を設定するには、次の手順を実行します。

  1. Registry Editor を開き、HKLM\System\CurrentControlSet\Services\WAS キーにある Environment という複数文字列の値を探し、1 行に 1 つずつ環境変数を追加します。例えば、ログの挿入とランタイムメトリクスを追加するには、値データに以下の行を追加します。
    DD_LOGS_INJECTION=true
    DD_RUNTIME_METRICS_ENABLED=true
    
  2. 以下のコマンドを実行し、IIS を再起動します。
    net stop /y was
    net start w3svc
    # Also, start any other services that were stopped when WAS was shut down.
    
Registry Editor を使用して、すべての IIS サイトの環境変数を作成する

コンソールアプリケーション

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

rem Set environment variables
SET CORECLR_ENABLE_PROFILING=1
rem Unless v2.14.0+ and you installed the tracer with the MSI
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Set additional Datadog environment variables
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem Start application
dotnet.exe example.dll

Linux

Bash スクリプト

アプリケーションを起動する前に、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_DOTNET_TRACER_HOME=/opt/datadog

# Datadog の環境変数を追加で設定
export DD_LOGS_INJECTION=true
export DD_RUNTIME_METRICS_ENABLED=true

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

Linux Docker コンテナ

Linux Docker コンテナに必要な環境変数を設定するには

# 環境変数を設定
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_DOTNET_TRACER_HOME=/opt/datadog

# Datadog の環境変数を追加で設定
ENV DD_LOGS_INJECTION=true
ENV DD_RUNTIME_METRICS_ENABLED=true

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

systemctl (per service)

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

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

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
    DD_DOTNET_TRACER_HOME=/opt/datadog
    
    # Set additional Datadog environment variables
    DD_LOGS_INJECTION=true
    DD_RUNTIME_METRICS_ENABLED=true
    
  2. サービスのコンフィギュレーションファイルで、サービスブロックの EnvironmentFile としてこれを参照します。

    [Service]
    EnvironmentFile=/path/to/environment.env
    ExecStart=<command used to start the application>
    
  3. .NET サービスを再起動して、環境変数の設定を有効にします。

systemctl (all services)

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

systemctl を使用して .NET アプリケーションをサービスとして実行する場合、systemctl によって実行されるすべてのサービスに対してロードされる環境変数を設定することもできます。

  1. systemctl set-environment を実行して、必要な環境変数を設定します。

    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_DOTNET_TRACER_HOME=/opt/datadog
    
    # Set additional Datadog environment variables
    systemctl set-environment DD_LOGS_INJECTION=true
    systemctl set-environment DD_RUNTIME_METRICS_ENABLED=true
    
  2. systemctl show-environment を実行して、環境変数が設定されていることを確認します。

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

その他の参考資料