- はじめに
- エージェント
- インテグレーション
- Watchdog
- イベント
- ダッシュボード
- モバイルアプリケーション
- インフラストラクチャー
- サーバーレス
- メトリクス
- ノートブック
- アラート設定
- APM & Continuous Profiler
- CI Visibility
- RUM & セッションリプレイ
- データベース モニタリング
- ログ管理
- セキュリティプラットフォーム
- Synthetic モニタリング
- ネットワークモニタリング
- 開発者
- API
- アカウントの管理
- データセキュリティ
- ヘルプ
.NET トレーサーは、.NET コア 2.1、3.1 および Microsoft が非推奨とするバージョン 2.0、2.2、3.0. での自動インスツルメンテーションをサポートしています。サポート対象のライブラリについては、互換性要件ページをご覧ください。
Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:
service
、env
、version
タグを動的に設定します。それ以外の場合、何らかの言語で記述されたアプリケーションのトレースを始めるには、まず Datadog Agent をインストール、構成します。.NET トレーサーはプロセス中に実行し、アプリケーションをインスツルメントし、トレースをアプリケーションから Agent に送信します。
注: .NET トレーサーは .NET ベースのすべての言語 (C#、F#、Visual Basic など) をサポートしています。
自動インスツルメンテーションは、ゼロコード変更と最小限のコンフィギュレーションでアプリケーションのパフォーマンスデータを収集します。.NET トレーサーはすべてのサポートライブラリのインスツルメンテーションをすぐに、そして自動的に行います。
自動インスツルメンテーションは以下を取得します。
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 つの手順に従います。
dd-trace-dotnet
リリースページから取得できるいずれかのパッケージを使って、アプリケーションが実行される環境に .NET トレーサーをインストールします。
必要な環境変数を作成します。詳細については、以下の必要な環境変数を参照してください。
/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_PROFILING | 1 |
CORECLR_PROFILER | {846F5F1C-F9AE-4B07-969E-05C26BC060D8} |
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_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 |
注: .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
を使用して、サービスとして .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
を使用して、サービスとして .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 トレーサーを構成する方法は複数あります:
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_PATH | CLR プロファイラーのログファイルのパスを設定します。 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 (デフォルト) の浮動小数点数。 |