互換性要件

サポートされている .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 ソリューションのみを実行してください。

APM に Datadog Agent を構成する

  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 サービスを再起動して、環境変数を有効にします。

その他の参考資料