dotnet-trace パフォーマンス分析ユーティリティ

この記事の対象: ✔️ dotnet-trace 9.0.661903 以降のバージョン

インストール

dotnet-trace をダウンロードしてインストールするには、次の 2 つの方法があります。

dotnet グローバルツール:

dotnet-trace NuGet パッケージの最新のリリースバージョンをインストールするには、次のように dotnet tool install コマンドを使用します。
```
dotnet tool install --global dotnet-trace
```

直接ダウンロード:

ご利用のプラットフォームに適したツールの実行可能ファイルをダウンロードします。

オペレーティングシステム (OS)	プラットフォーム
ウィンドウズ	x86 \| x64 \| Arm \| Arm-x64
Linux	x64 \| Arm \| Arm64 \| musl-x64 \| musl-Arm64

構文

dotnet-trace [-h, --help] [--version] <command>

説明

dotnet-trace ツール:

クロスプラットフォームの .NET 診断ツールです。
ネイティブプロファイラーを使用せずに、実行中のプロセスの .NET トレースのコレクションを有効にします。
.NET ランタイムの EventPipe 上に構築されます。

トレースを収集する 2 つの異なる方法がサポートされています。

collect動詞は、任意の OS で一貫した機能を提供します。
collect-linux動詞では、Linux 固有の OS 機能を使用して追加の機能を提供します。

特徴	`collect`	`collect-linux`
サポートされている OS	[任意]	Linux のみ、カーネルバージョン >= 6.4
管理者/ルート権限が必要です	いいえ	イエス
すべてのプロセスを同時にトレースする	いいえ	サポートされています
ネイティブライブラリとカーネルイベントをキャプチャする	いいえ	サポートされています
イベント呼び出し履歴にはネイティブフレームが含まれます	いいえ	イエス

オプション

-h|--help

コマンドラインヘルプを表示します。
--version

dotnet-trace ユーティリティのバージョンを表示します。

コマンド

コマンド
dotnet-trace collect
dotnet-trace collect-linux
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace レポート

dotnet-trace collect

実行中のプロセスから診断トレースを収集するか、子プロセスを起動してそれをトレースします (.NET 5 以降)。ツールに子プロセスを実行させ、その起動からトレースさせるには、collect コマンドに -- を追加します。

構文

dotnet-trace collect
    [--buffering-mode <Drop|Block>]
    [--buffersize <size>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--dsrouter <ios|ios-sim|android|android-emu>]
    [--format <Chromium|NetTrace|Speedscope>]
    [-h|--help]
    [--duration dd:hh:mm:ss]
    [-n, --name <name>]
    [--diagnostic-port]
    [-o|--output <trace-file-path>]
    [-p|--process-id <pid>]
    [--profile <list-of-comma-separated-profile-names>]
    [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io]
    [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

オプション

--buffering-mode <Drop|Block>

dotnet-trace バージョン 10.0.750501 以降で使用できます。

ランタイムがイベントをバッファーする方法を設定します。 DropまたはBlock (大文字と小文字を区別しない) を受け入れ、既定値はDrop。
- Drop (既定値): バッファーオーバーフロー時にイベントが削除されます。
- Block: イベントを出力するスレッドは、バッファーに格納する空き容量が存在するまで待機します。メモリ不足などの一般的でないエラー条件下では、イベントが破棄される可能性があります。 Blockには、.NET 11 以上のターゲットランタイムが必要であり、バッファーがいっぱいの間にイベントを生成するスレッドが一時停止するため、トレースされたアプリケーションの速度が低下する可能性があります。
--buffersize <size>

メモリ内のバッファーのサイズをメガバイトに設定します。既定は 256 MB です。

注意

イベントがディスクに書き込まれるよりも速くターゲットプロセスによって作成される場合、このバッファーがオーバーフローし、一部のイベントが削除される可能性があります。この問題を軽減するには、バッファーサイズを大きくするか、記録されるイベントの数を減らします。
--clreventlevel <clreventlevel>

生成される CLR イベントの詳細度。このオプションは、 --clrevents が指定されている場合にのみ適用され、 --profile または --providersによってオーバーライドされません。次の表に、使用可能なイベントレベルを示します。

文字列値数値

logalways 0

critical 1

error 2

warning 3

informational 4

verbose 5

文字列値	数値
`logalways`	`0`
`critical`	`1`
`error`	`2`
`warning`	`3`
`informational`	`4`
`verbose`	`5`

--clrevents <clrevents>

有効にする CLR ランタイムプロバイダーのキーワードの、+ 記号で区切られたリスト。これは、16 進値ではなく文字列の別名を使用してイベントキーワードを指定できるようにする、単純なマッピングです。たとえば、dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 では、dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational と同じイベントのセットが要求されます。 CLR ランタイムプロバイダーの Microsoft-Windows-DotNETRuntime が --providers または --profileによっても有効になっている場合、このオプションは無視されます。次の表に、使用可能なキーワードの一覧を示します。

キーワード文字列のエイリアス	キーワードの 16 進値
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`0x4`
`loader`	`0x8`
`jit`	`0x10`
`ngen`	`0x20`
`startenumeration`	`0x40`
`endenumeration`	`0x80`
`security`	`0x400`
`appdomainresourcemanagement`	`0x800`
`jittracing`	`0x1000`
`interop`	`0x2000`
`contention`	`0x4000`
`exception`	`0x8000`
`threading`	`0x10000`
`jittedmethodiltonativemap`	`0x20000`
`overrideandsuppressngenevents`	`0x40000`
`type`	`0x80000`
`gcheapdump`	`0x100000`
`gcsampledobjectallocationhigh`	`0x200000`
`gcheapsurvivalandmovement`	`0x400000`
`managedheapcollect`	`0x800000`
`gcheapandtypenames`	`0x1000000`
`gcsampledobjectallocationlow`	`0x2000000`
`perftrack`	`0x20000000`
`stack`	`0x40000000`
`threadtransfer`	`0x80000000`
`debugger`	`0x100000000`
`monitoring`	`0x200000000`
`codesymbols`	`0x400000000`
`eventsource`	`0x800000000`
`compilation`	`0x1000000000`
`compilationdiagnostic`	`0x2000000000`
`methoddiagnostic`	`0x4000000000`
`typediagnostic`	`0x8000000000`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

CLR プロバイダーの詳細については、 .NET ランタイムプロバイダーのリファレンスドキュメントを参照してください。

'--dsrouter {ios|ios-sim|android|android-emu}

dotnet-dsrouter を起動し、それに接続します。 dotnet-dsrouter をインストールする必要があります。詳細については、 dotnet-dsrouter -h を実行します。
--format {Chromium|NetTrace|Speedscope}

トレースファイルの出力の変換形式を設定します。既定値は、NetTrace です。
-n, --name <name>

トレースを収集するプロセスの名前。

注意

Linux と macOS では、このオプションを使用するには、ターゲットアプリケーションと dotnet-trace が同じ TMPDIR 環境変数を共有する必要があります。それ以外の場合、このコマンドはタイムアウトします。
--diagnostic-port <port-address[,(listen|connect)]>

トレースするプロセスとの通信に使用する診断ポートを設定します。ターゲットプロセス内の dotnet-trace と .NET ランタイムは、ポートアドレスに同意する必要があります。1 つはリッスンし、もう 1 つは接続している必要があります。 dotnet-trace は、 --process-id または --name オプションを使用して接続するとき、または -- <command> オプションを使用してプロセスを起動するときに、正しいポートを自動的に決定します。通常、ポートを明示的に指定する必要があるのは、将来開始されるプロセスを待機するとき、または現在のプロセス名前空間の一部ではないコンテナー内で実行されているプロセスと通信する場合のみです。

port-addressは OS によって異なります。
- Linux と macOS - /foo/tool1.socketなどの Unix ドメインソケットへのパス。
- Windows - \\.\pipe\my_diag_port1などの名前付きパイプへのパス。
- Android、iOS、tvOS - 127.0.0.1:9000などの IP:port。
既定では、 dotnet-trace は指定したアドレスでリッスンします。アドレスの後にdotnet-traceを追加することで、代わりに接続する,connectを要求できます。たとえば、 --diagnostic-port /foo/tool1.socket,connect は、 /foo/tool1.socket Unix ドメインソケットをリッスンしている .NET ランタイムプロセスに接続します。

このオプションを使用してアプリの起動時からトレースを収集する方法については、「診断ポートを使用してアプリの起動時からトレースを収集する」を参照してください。
--duration <time-to-run>

トレースが実行される時間。 dd:hh:mm:ss という形式を使用します。たとえば 00:00:00:05 は、5 秒間実行されることを示します。
-o|--output <trace-file-path>

収集されたトレースデータの出力パス。指定しない場合、既定値は <appname>_<yyyyMMdd>_<HHmmss>.nettrace (例: 'myapp_20210315_111514.nettrace') になります。
-p|--process-id <PID>

トレースを収集するプロセス ID。

注意

Linux と macOS では、このオプションを使用するには、ターゲットアプリケーションと dotnet-trace が同じ TMPDIR 環境変数を共有する必要があります。それ以外の場合、このコマンドはタイムアウトします。

--profile <list-of-comma-separated-profile-names>

プロファイルは、一般的なトレースシナリオ用のプロバイダー構成の定義済みセットです。一度に複数のプロファイルをコンマで区切って指定できます。 --providersによって構成されたプロバイダーは、プロファイルの構成をオーバーライドします。同様に、いずれかのプロファイルで CLR ランタイムプロバイダーが構成されている場合、 --clreventsによって規定されたすべての構成がオーバーライドされます。

--profile、--providers、および--clreventsをすべて省略すると、既定でプロファイルのdotnet-trace collectとdotnet-commonが有効dotnet-sampled-thread-time。

使用可能なプロファイル:

[プロファイル]	説明
`dotnet-common`	低いオーバーヘッドを維持するように設計された軽量の .NET ランタイム診断。 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap、Compilation イベントが含まれます `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`に相当します。
`dotnet-sampled-thread-time`	サンプル .NETスレッドスタックは、ランタイムの既定のレート (マルチスレッドが有効なビルドでは 1 ミリ秒ごとに約 1000 Hz) で、使用されているウォールクロック時間コードの量を推定します。
`gc-verbose`	GC コレクションを追跡し、オブジェクトの割り当てをサンプリングします。
`gc-collect`	オーバーヘッドが非常に低い場合にのみ GC コレクションを追跡します。
`database`	ADO.NET および Entity Framework データベースコマンドをキャプチャします。

ヒント

dotnet-sampled-thread-timeで使用されるサンプリングレートは、DOTNET_EventPipeThreadSamplingRate環境変数 (ミリ秒単位の値) で変更できます。この設定はプロセスグローバルであり、すべての EventPipe セッションに影響します。詳細については、環境変数を使用したトレースを参照してください。

注意

dotnet-trace ツールの以前のバージョンでは、収集動詞は cpu-sampling というプロファイルをサポートしました。名前が誤解を招くため、このプロファイルは削除されました。 CPU 使用率に関係なく、すべてのスレッドをサンプリングしました。 --profile dotnet-sampled-thread-time,dotnet-commonを使用して、同様の結果を得ることができます。以前の cpu-sampling の動作を正確に一致させる必要がある場合は、 --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4"を使用します。

--providers <list-of-comma-separated-providers>

有効にする EventPipe プロバイダーのコンマ区切りのリスト。これらのプロバイダーは、--profile <list-of-comma-separated-profile-names> で示されている任意のプロバイダーを補完します。特定のプロバイダーに不整合がある場合、この構成は、 --profile および --clreventsからの暗黙的な構成よりも優先されます。

次のプロバイダーの一覧は、 Provider[,Provider]形式です。
- Provider は次の形式です。 KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs は次の形式です。 [key1=value1][;key2=value2]
.NET でのいくつかの既知のプロバイダーの詳細については、既知のイベントプロバイダーに関するページを参照してください。
-- <command> (対象アプリケーションが .NET 5.0 以降を実行している場合)

ユーザーは、コレクション構成パラメーターの後にまず --、次にコマンドを追加すれば、5.0 以降のランタイムで .NET アプリケーションを起動することができます。これは、起動時のパフォーマンスの問題やアセンブリローダーおよびバインダーのエラーなど、プロセスの早い段階で発生する問題を診断するのに役立つ場合があります。

注意

このオプションを使用すると、ツールに通信する最初の .NET プロセスが監視されます。つまり、コマンドが複数の .NET アプリケーションを起動した場合、最初のアプリのみが収集されます。このため、このオプションについては、自己完結型アプリケーションに対して使用するか、または dotnet exec <app.dll> オプションを使用することをお勧めします。
--show-child-io

現在のコンソールで起動された子プロセスの入出力ストリームを表示します。
--resume-runtime

セッションが初期化されたらランタイムを再開します。既定値は true です。ランタイムの再開を無効にするには、--resume-runtime:false を使用します。
--stopping-event-provider-name

そのまま解析される文字列で、プロバイダー名が一致するイベントにヒットしたとき、トレースを停止します。より具体的な停止イベントの場合は、--stopping-event-event-name や --stopping-event-payload-filter を追加で指定します。たとえば、--stopping-event-provider-name Microsoft-Windows-DotNETRuntime イベントプロバイダーによって生成された最初のイベントに達したときにトレースを停止Microsoft-Windows-DotNETRuntime。
--stopping-event-event-name

そのまま解析される文字列で、イベント名が一致するイベントにヒットしたとき、トレースを停止します。 --stopping-event-provider-name を設定する必要があります。より具体的な停止イベントの場合は、--stopping-event-payload-filter を追加で指定します。たとえば、--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted イベントプロバイダーによって生成された最初のMethod/JittingStarted イベントに達したときにトレースを停止Microsoft-Windows-DotNETRuntime。
--stopping-event-payload-filter

コンマで区切られた [payload_field_name]:[payload_field_value] ペアとして解析される文字列で、指定されたすべてのペイロードペアを含むイベントにヒットしたとき、トレースを停止します。 --stopping-event-provider-name と --stopping-event-event-name を設定する必要があります。たとえば、--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick イベントプロバイダーによって出力されるMethod/JittingStarted名前空間でOnButtonClickメソッドの最初のProgram イベントでトレースを停止Microsoft-Windows-DotNETRuntime。

注意

大規模なアプリケーションでは、トレースの停止に長い時間 (最大分) かかる場合があります。ランタイムでは、トレースにキャプチャされたすべてのマネージドコードを対象に、型キャッシュを送信する必要があります。
dotnet-trace を使ってトレースを収集するには、ターゲットプロセスを実行しているユーザーと同じユーザーまたはルートとして実行する必要があります。それ以外の場合、このツールでターゲットプロセスとの接続を確立することはできません。
dotnet-trace collect の実行中にハンドルされない例外が発生した場合、トレースが不完全になります。例外の根本原因を見つけることが優先される場合、「クラッシュ時にダンプの収集」に移動してください。ハンドルされない例外の結果として、ランタイムがシャットダウンするときにトレースが切り捨てられ、ハングやデータの破損などの他の望ましくない動作を防ぐことができます。トレースが不完全な場合でも、それを開いて、障害に至るまで何が起こったかを確認することができます。ただし、ランダウン情報 (これはトレースの最後に発生します) が欠落しているので、スタックが解決されない可能性があります (有効になっているプロバイダーによって異なります)。コマンドラインで /ContinueOnError フラグを指定して PerfView を実行し、トレースを開きます。ログには、例外が発生した場所も含まれます。
--stopping-event-* オプションを使用して停止イベントを指定すると、EventStream が非同期的に解析されるため、指定した停止イベントオプションに一致するトレースイベントが解析されてから EventPipeSession が停止されるまでの間に、いくつかのイベントが通過します。

dotnet-trace collect-linux

Linux OS テクノロジである perf_events を使用して診断トレースを収集します。 collect-linux では、 collectに対して次の追加機能が有効になります。

特徴	`collect`	`collect-linux`
サポートされている OS	[任意]	Linux のみ、カーネルバージョン >= 6.4
管理者/ルート権限が必要です	いいえ	イエス
すべてのプロセスを同時にトレースする	いいえ	サポートされています
ネイティブライブラリとカーネルイベントをキャプチャする	いいえ	サポートされています
イベント呼び出し履歴にはネイティブフレームが含まれます	いいえ	イエス

[前提条件]

CONFIG_USER_EVENTS=yがサポートされている Linux カーネル (カーネル 6.4 以降)
マウントされた tracefs (既定値は /sys/kernel/tracing)
ルートのアクセス許可
.NET 10 以降

注意

collect-linux動詞は、glibc バージョン 2.27 以降の Linux x64 および Linux Arm64 環境でのみ実行されます。 .NET 10 の公式にサポートされているすべての Linux ディストリビューションでは、Alpine 3.22 を除き、この要件がサポートされています。システムの libc のバージョンを簡単に確認するには、コマンド ldd --version を使用するか、libc ライブラリを直接実行します。

ヒント

カーネルがサポート user_events かどうかを確認するには、 zgrep CONFIG_USER_EVENTS /proc/config.gzを実行します。 tracefs マウントの下で user_events_data を検索することもできます (既定値は /sys/kernel/tracing/user_events_data)。

構文

dotnet-trace collect-linux
    [-h|--help]

    # Provider/Event Specification
    [--providers <list-of-comma-separated-providers>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--perf-events <list-of-perf-events>]
    [--profile <list-of-comma-separated-profile-names>]

    # Trace Collection
    [-o|--output <trace-file-path>]
    [--duration dd:hh:mm:ss]

    # .NET Process Target (Optional)
    [-n, --name <name>]
    [-p|--process-id <pid>]

    # Probe mode
    [--probe]

既定のコレクション動作

--providers、--profile、--clrevents、および--perf-eventsが指定されていない場合、collect-linuxこれらのプロファイルは既定で有効になります。

dotnet-common — 軽量の .NET ランタイム診断。
cpu-sampling — カーネル CPU サンプリング。

既定では、マシン上のすべてのプロセスがトレースされます。 1 つのプロセスのみをトレースするには、 -n, --name <name> または -p|--process-id <PID>を使用します。

オプション

プロバイダー/イベントの仕様オプション

--providers <list-of-comma-separated-providers>

有効にする EventPipe プロバイダーのコンマ区切りのリスト。これらのプロバイダーは、--profile <list-of-comma-separated-profile-names> で示されている任意のプロバイダーを補完します。特定のプロバイダーに不整合がある場合、この構成は、 --profile および --clreventsからの暗黙的な構成よりも優先されます。

次のプロバイダーの一覧は、 Provider[,Provider]形式です。
- Provider は次の形式です。 KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs は次の形式です。 [key1=value1][;key2=value2]
.NET の一部の既知のプロバイダーの詳細については、「既知のイベントプロバイダー」を参照してください。
--clreventlevel <clreventlevel>

生成される CLR イベントの詳細度。このオプションは、 --clrevents が指定されている場合にのみ適用され、 --profile または --providersによってオーバーライドされません。次の表に、使用可能なイベントレベルを示します。

文字列値数値

logalways 0

critical 1

error 2

warning 3

informational 4

verbose 5

文字列値	数値
`logalways`	`0`
`critical`	`1`
`error`	`2`
`warning`	`3`
`informational`	`4`
`verbose`	`5`

--clrevents <clrevents>

有効にする CLR ランタイムプロバイダーのキーワードの、+ 記号で区切られたリスト。これは、16 進値ではなく文字列の別名を使用してイベントキーワードを指定できるようにする、単純なマッピングです。たとえば、dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 では、dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational と同じイベントのセットが要求されます。 CLR ランタイムプロバイダーの Microsoft-Windows-DotNETRuntime が --providers または --profileによっても有効になっている場合、このオプションは無視されます。次の表に、使用可能なキーワードの一覧を示します。

キーワード文字列のエイリアス	キーワードの 16 進値
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`0x4`
`loader`	`0x8`
`jit`	`0x10`
`ngen`	`0x20`
`startenumeration`	`0x40`
`endenumeration`	`0x80`
`security`	`0x400`
`appdomainresourcemanagement`	`0x800`
`jittracing`	`0x1000`
`interop`	`0x2000`
`contention`	`0x4000`
`exception`	`0x8000`
`threading`	`0x10000`
`jittedmethodiltonativemap`	`0x20000`
`overrideandsuppressngenevents`	`0x40000`
`type`	`0x80000`
`gcheapdump`	`0x100000`
`gcsampledobjectallocationhigh`	`0x200000`
`gcheapsurvivalandmovement`	`0x400000`
`managedheapcollect`	`0x800000`
`gcheapandtypenames`	`0x1000000`
`gcsampledobjectallocationlow`	`0x2000000`
`perftrack`	`0x20000000`
`stack`	`0x40000000`
`threadtransfer`	`0x80000000`
`debugger`	`0x100000000`
`monitoring`	`0x200000000`
`codesymbols`	`0x400000000`
`eventsource`	`0x800000000`
`compilation`	`0x1000000000`
`compilationdiagnostic`	`0x2000000000`
`methoddiagnostic`	`0x4000000000`
`typediagnostic`	`0x8000000000`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

CLR プロバイダーの詳細については、 .NET ランタイムプロバイダーのリファレンスドキュメントを参照してください。

--perf-events <list-of-perf-events>

トレースに含めるパフォーマンスイベントのコンマ区切りの一覧。使用可能なイベントは tracefs の下にあります。これは通常、 /sys/kernel/tracingにマウントされ、使用可能なすべてのイベントの available_events を通じて、またはカテゴリ化されたイベントの events/ サブディレクトリを介して行われます。

例: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

--profile <list-of-comma-separated-profile-names>

--profile、--providers、--clrevents、および--perf-eventsをすべて省略すると、既定でプロファイルのdotnet-trace collect-linuxとdotnet-commonが有効cpu-sampling。

使用可能なプロファイル:

[プロファイル]	説明
`dotnet-common`	低いオーバーヘッドを維持するように設計された軽量の .NET ランタイム診断。 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap、Compilation イベントが含まれます `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`に相当します。
`cpu-sampling`	正確なオン CPU 属性のために、 `Universal.Events/cpu`として出力されるカーネル CPU サンプリング (パフォーマンスベース)。
`thread-time`	CPU のオン/オフとスケジューラの分析のために、 `Universal.Events/cswitch`として出力されるカーネルスレッドコンテキストスイッチ。
`gc-verbose`	GC コレクションを追跡し、オブジェクトの割り当てをサンプリングします。
`gc-collect`	オーバーヘッドが非常に低い場合にのみ GC コレクションを追跡します。
`database`	ADO.NET および Entity Framework データベースコマンドをキャプチャします。

トレース収集オプション

-o|--output <trace-file-path>

収集されたトレースデータの出力パス。指定しない場合、既定では、既定のコンピューター全体のトレースに対してtrace_<yyyyMMdd>_<HHmmss>.nettraceし、プロセス固有のトレース (<appname>_<yyyyMMdd>_<HHmmss>.nettraceまたは--name) に--process-idします。
--duration <time-to-run>

トレースが実行される時間。 dd:hh:mm:ss という形式を使用します。たとえば 00:00:00:05 は、5 秒間実行されることを示します。

.NET プロセスターゲットオプション

既定のコレクション動作を参照してください

-n, --name <name>

トレースを収集するプロセスの名前。
-p|--process-id <PID>

トレースを収集するプロセス ID。

プローブモードのオプション

--probe [-n|--name] [-p|--process-id] [-o|--output <stdout|output-filename>]

トレースを収集せずに、collect-linux で使用される EventPipe UserEvents IPC コマンドをサポートするための .NET プロセスをプローブします。最初にサポートされているプロセスの結果一覧。 '-o stdout' を使用して CSV (pid,processName,supportsCollectLinux) をコンソールに出力するか、'-o output-filename' を使用して CSV を書き込みます。 -n|--name または -p|--process-id を使用して 1 つのプロセスをプローブします。

プローブモードで collect-linux を実行してもトレースは収集されないため、実行にルートアクセス許可は必要ありません。前提条件の検証は提供されず、プレビューバージョンの .NET Runtime '10.0.0' で実行されている .NET プロセスはサポートされていないと見なされます。

注意

dotnet-trace collect-linuxを使用してトレースを収集するには、ルートアクセス許可 (CAP_PERFMON/CAP_SYS_ADMIN) を使用して実行する必要があります。それ以外の場合、ツールはイベントの収集に失敗します。

dotnet-trace convert

nettrace トレースを、別のトレース分析ツールで使用するために、別の形式に変換します。

構文

dotnet-trace convert [<input-filename>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

引数

<input-filename>

変換する入力トレースファイル。既定は trace.nettrace です。

オプション

--format <Chromium|NetTrace|Speedscope>

トレースファイルの出力の変換形式を設定します。
-o|--output <output-filename>

出力ファイルの名前。ターゲットの形式の拡張子が追加されます。

注意

nettrace ファイルを chromium または speedscope ファイルに変換した場合、元に戻せません。 speedscope ファイルと chromium ファイルには、nettrace ファイルを再構築するために必要な情報が一部含まれていません。ただし、convert コマンドによって元の nettrace ファイルが保持されます。今後開くことがある場合、このファイルは削除しないでください。

dotnet-trace ps

トレースを収集できる dotnet プロセスを一覧表示します。 dotnet-trace 6.0.320703 以降では、各プロセスが開始されたコマンドライン引数も表示されます (該当する場合)。

注意

列挙された 64 ビットプロセスの完全な情報を取得するには、 dotnet-trace ツールの 64 ビットバージョンを使用する必要があります。

構文

dotnet-trace ps [-h|--help]

例

コマンド dotnet run --configuration Release を使用して、実行時間の長いアプリを起動するとします。別のウィンドウで dotnet-trace ps コマンドを実行します。表示される出力は次のとおりです。コマンドライン引数 (使用できる場合) は、dotnet-trace バージョン 6.0.320703 以降で表示されます。

> dotnet-trace ps

  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

dotnet-trace list-profiles

各プロファイルに含まれるプロバイダーとフィルターの記述と共に、事前に構築されているトレースのプロファイルを一覧表示します。

構文

dotnet-trace list-profiles [-h|--help]

dotnet-trace レポート

以前に生成されたトレースから stdout にレポートを作成します。

構文

dotnet-trace report [-h|--help] <tracefile> [command]

引数

<tracefile>

分析されているトレースのファイルパス。

コマンド

dotnet-trace report topN

呼び出し履歴で最長の上位 N 個のメソッドを検索します。

構文

dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]

オプション

-n|--number <n>

呼び出し履歴のメソッドの上位 N 個を指定します。

--inclusive

包括時間に基づいて上位 N 個のメソッドを出力します。指定しない場合、排他時間が既定で使用されます。

-v|--verbose

各メソッドのパラメーターを完全に出力します。指定しない場合、パラメーターは切り捨てられます。

dotnet-trace を使用してトレースを収集する

dotnet-trace collect を使用してトレースを収集するには:

トレースを収集する .NET アプリケーションのプロセス識別子 (PID) を取得します。
- Windows で、タスクマネージャーや、たとえば、tasklist コマンドを使用できます。
- Linux の場合、たとえば、ps コマンドを使用できます。
- dotnet-trace ps

次のコマンドを実行します。

dotnet-trace collect --process-id <PID>

上のコマンドを実行すると、次のような出力が生成されます。

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : <full-path-to-process-being-trace>
Output File    : <process>_20251007_154557.nettrace
[00:00:00:02]   Recording trace 178.172  (KB)
Press <Enter> or <Ctrl+C> to exit...
Stopping the trace. This may take several minutes depending on the application being traced.

Trace completed.

Enter キーを押してコレクションを停止します。 dotnet-trace は、 .nettrace ファイルへのイベントのログ記録を完了します。

子アプリケーションを起動し、そのスタートアップからトレースを dotnet-trace を使用して収集します

スタートアップからプロセスのトレースを収集すると便利な場合があります。 .NET 5 以降を実行しているアプリの場合は、dotnet-trace を使用してこれを行うことができます。

次のコマンドは、コマンドライン引数としてhello.exeとarg1を使用してarg2を起動し、ランタイムの起動時からトレースを収集します。

dotnet-trace collect -- hello.exe arg1 arg2

上のコマンドを実行すると、次のような出力が生成されます。

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
Output File    : E:\temp\gcperfsim\trace.nettrace


[00:00:00:05]   Recording trace 122.244  (KB)
Press <Enter> or <Ctrl+C> to exit...

Enter キーまたは + キーを押すと、トレースの収集を停止できます。これを行うと、も終了します。

注意

dotnet-trace を使用して hello.exe を起動すると、その入力/出力がリダイレクトされ、既定ではコンソールで操作できなくなります。その stdin/stdout を操作するには、--show-child-io スイッチを使用します。 Ctrl + C または SIGTERM を使用してツールを終了すると、ツールと子プロセスの両方が安全に終了します。ツールの前に子プロセスが終了すると、ツールも終了し、トレースを安全に表示できます。

診断ポートを使用してアプリの起動からトレースを収集する

診断ポートは、.NET 5 で追加されたランタイム機能であり、アプリの起動からトレースを開始することができます。 dotnet-trace を使用してこれを行うには、上記の例の説明に従って dotnet-trace collect -- <command> を使用するか、--diagnostic-port オプションを使用します。

アプリケーションを起動からすばやくトレースする方法としては、アプリケーションを子プロセスとして起動するために dotnet-trace <collect|monitor> -- <command> を使用するのが最も簡単です。

ただし、(アプリを最初の 10 分だけ監視し、実行を継続するなど) トレースしているアプリの有効期間をより細かく制御する場合、または CLI を使用してアプリと対話する必要がある場合は、--diagnostic-port オプションを使用すると、監視対象アプリと dotnet-trace の両方を制御できます。

次のコマンドdotnet-tracemyport.sockという名前の診断ソケットを作成し、接続を待機します。

dotnet-trace collect --diagnostic-port myport.sock

出力:

Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=/home/user/myport.sock

別のコンソールで、DOTNET_DiagnosticPorts の出力値に設定された環境変数 dotnet-trace を使用して対象アプリケーションを起動します。
```
export DOTNET_DiagnosticPorts=/home/user/myport.sock
./my-dotnet-app arg1 arg2
```
これにより、dotnet-trace による my-dotnet-app のトレースが開始します。
```
Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=myport.sock
Starting a counter session. Press Q to quit.
```
重要

dotnet runを使用してアプリを起動すると、dotnet CLI によってアプリではない多くの子プロセスが生成され、アプリの前にdotnet-traceに接続でき、実行時にアプリが中断される可能性があるため、問題が発生する可能性があります。アプリケーションの起動には、アプリの自己完結型バージョンを直接使用するか、dotnet exec を使用することをお勧めします。

(Linux のみ)dotnet-trace を使用してマシン全体のトレースを収集する

ネイティブランタイムフレームのシンボルを取得する

collect-linux は、呼び出し履歴内のネイティブフレームをキャプチャします。ランタイムライブラリのネイティブメソッド名 ( libcoreclr.so など) を解決するには、対応するデバッグシンボルファイルをライブラリの横のディスクに配置します。これらのシンボルがない場合、ネイティブフレームはトレース内で未解決のアドレスとして表示されます。

collect-linux トレースの開始時に JIT コンパイルコードのパフォーマンスマップ生成が動的に有効になるため、.NET プロセスを再起動する必要はありません。

ネイティブランタイムシンボルをダウンロードするには、 dotnet-symbol を使用します。

dotnet-symbol をインストールします。
```
dotnet tool install -g dotnet-symbol
```
ランタイムバージョンのデバッグシンボルをダウンロードします。たとえば、ランタイムが /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0 にインストールされている場合は、次のようになります。
```
dotnet-symbol --symbols /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0/lib*.so
```
対応するランタイムライブラリの横に、ダウンロードした.so.dbg ファイルを配置します (たとえば、libcoreclr.so.dbgの横にlibcoreclr.so)。既定では、 dotnet-symbol は各入力ファイルの横にシンボルファイルを書き込みます。ランタイムライブラリが /usr/share/dotnet/...などの保護されたパスの下に存在する場合は、昇格されたアクセス許可で dotnet-symbol を実行するか (たとえば、 sudoを使用して)、 -o/--output オプションを使用して書き込み可能なディレクトリに書き込み、ランタイムライブラリの横にある .so.dbg ファイルをコピーします。

シンボルを配置した後、 collect-linux はトレースを収集するときにネイティブメソッド名を解決します。

この例では、コンピューター上のすべてのプロセスの CPU サンプルをキャプチャします。 .NET 10 以降を実行しているプロセスには、GC、JIT、アセンブリの読み込み動作を記述する追加の軽量イベントも含まれます。

$ sudo dotnet-trace collect-linux
No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile

Linux Perf Events                                                               Enabled By
cpu-sampling                                                                    --profile

Output File    : <path-to-nettrace>trace_20251008_181939.nettrace

[00:00:00:03]   Recording trace.
Press <Enter> or <Ctrl-C> to exit...

Recording stopped.
Resolving symbols.
Finished recording trace.
Trace written to <path-to-nettrace>trace_20251008_181939.nettrace

複数の .NET バージョンがインストールされている環境では、collect-linuxでを実行すると、.NET プロセスが collect-linux でトレースできるかどうかを識別するのに役立ちます。

$ dotnet-trace collect-linux --probe
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

dotnet-trace からキャプチャされたトレースを表示する

Windows では、分析のために Visual Studio または PerfView で .nettrace ファイルを表示できます。

Linux の場合、dotnet-trace の出力形式を speedscope に変更することでトレースを表示できます。 -f|--format オプションを使用して、出力ファイルの形式を変更します。 nettrace (既定のオプション) か speedscope を選択できます。オプション -f speedscope を使用すると、dotnet-trace によって speedscope ファイルが生成されます。 Speedscope ファイルは https://www.speedscope.app で開くことができます。

Windows 以外のプラットフォームで収集されたトレースの場合、トレースファイルを Windows マシンに移動して、Visual Studio または PerfView で表示することもできます。

注意

.NET Core ランタイムにより、nettrace 形式でトレースが生成されます。トレースの完了後、トレースは speedscope に変換されます (指定されている場合)。変換によってはデータが失われる場合もあるため、元の nettrace ファイルが変換されたファイルの横に保持されます。

.rsp ファイルを使用し、長いコマンドの入力を避ける

渡す引数が含まれる dotnet-trace ファイルで .rsp を起動できます。これは、文字を取り除くシェル環境を使用しているとき、長い引数を求めるプロバイダーを有効にするときに便利です。

たとえば、次のプロバイダーの場合、トレースのたびに入力するのが面倒です。

dotnet-trace collect --providers Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

また、前の例には、引数の一部として " が含まれています。引用符の処理がシェルごとに異なるため、異なるシェルを使用するとき、さまざまな問題が発生するおそれがあります。たとえば、zsh に入力するコマンドは、cmd のコマンドとは異なります。

これを毎回入力する代わりに、myprofile.rsp という名称のファイルに次のテキストを保存できます。

--providers
Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

myprofile.rsp を保存したら、次のコマンドを使用し、この構成で dotnet-trace を起動できます。

dotnet-trace @myprofile.rsp

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-08-24

dotnet-trace パフォーマンス分析ユーティリティ

インストール

構文

説明

オプション

コマンド

dotnet-trace collect

構文

オプション

dotnet-trace collect-linux

[前提条件]

構文

既定のコレクション動作

オプション

プロバイダー/イベントの仕様オプション

トレース 収集オプション

.NET プロセス ターゲット オプション

プローブ モードのオプション

dotnet-trace convert

構文

引数

オプション

dotnet-trace ps

構文

例

dotnet-trace list-profiles

構文

dotnet-trace レポート

構文

引数

コマンド

dotnet-trace report topN

構文

オプション

dotnet-trace を使用してトレースを収集する

子アプリケーションを起動し、そのスタートアップからトレースを dotnet-trace を使用して収集します

診断ポートを使用してアプリの起動からトレースを収集する

(Linux のみ)dotnet-trace を使用してマシン全体のトレースを収集する

ネイティブ ランタイム フレームのシンボルを取得する

dotnet-trace からキャプチャされたトレースを表示する

.rsp ファイルを使用し、長いコマンドの入力を避ける

関連項目

フィードバック

その他のリソース

トレース収集オプション

.NET プロセスターゲットオプション

プローブモードのオプション

ネイティブランタイムフレームのシンボルを取得する