この記事の対象: ✔️ dotnet-trace 9.0.661903 以降のバージョン
インストール
dotnet-trace をダウンロードしてインストールするには、次の 2 つの方法があります。
dotnet グローバル ツール:
dotnet-traceNuGet パッケージの最新のリリース バージョンをインストールするには、次のように 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 Core ツールです。
ネイティブ プロファイラーなしで実行中のプロセスの .NET Core トレースを回収できます。
.NET Core ランタイムの
EventPipeに基づいています。トレースを収集する 2 つの異なる方法がサポートされています。
-
collect動詞は、任意の OS で一貫した機能を提供します。 -
collect-linux動詞では、Linux 固有の OS 機能を使用して追加の機能を提供します。
特徴 collectcollect-linuxサポートされている OS [任意] Linux のみ、カーネル バージョン >= 6.4 管理者/ルート特権が必要です いいえ イエス すべてのプロセスを同時にトレースする いいえ サポートされています ネイティブ ライブラリとカーネル イベントをキャプチャする いいえ サポートされています イベント呼び出し履歴にはネイティブ フレームが含まれます いいえ イエス -
オプション
-h|--helpコマンド ライン ヘルプを表示します。
--versiondotnet-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
[--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>]
オプション
--buffersize <size>メモリ内のバッファーのサイズをメガバイトに設定します。 既定は 256 MB です。
注意
イベントがディスクに書き込まれるよりも速くターゲット プロセスによって作成される場合、このバッファーがオーバーフローし、一部のイベントが削除される可能性があります。 この問題を軽減するには、バッファー サイズを大きくするか、記録されるイベントの数を減らします。
--clreventlevel <clreventlevel>生成される CLR イベントの詳細度。 このオプションは、
--clreventsが指定されている場合にのみ適用され、--profileまたは--providersによってオーバーライドされません。 次の表に、使用可能なイベント レベルを示します。文字列値 数値 logalways0critical1error2warning3informational4verbose5--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 進値 gc0x1gchandle0x2assemblyloader0x4loader0x8jit0x10ngen0x20startenumeration0x40endenumeration0x80security0x400appdomainresourcemanagement0x800jittracing0x1000interop0x2000contention0x4000exception0x8000threading0x10000jittedmethodiltonativemap0x20000overrideandsuppressngenevents0x40000type0x80000gcheapdump0x100000gcsampledobjectallocationhigh0x200000gcheapsurvivalandmovement0x400000managedheapcollect0x800000gcheapandtypenames0x1000000gcsampledobjectallocationlow0x2000000perftrack0x20000000stack0x40000000threadtransfer0x80000000debugger0x100000000monitoring0x200000000codesymbols0x400000000eventsource0x800000000compilation0x1000000000compilationdiagnostic0x2000000000methoddiagnostic0x4000000000typediagnostic0x8000000000jitinstrumentationdata0x10000000000profiler0x20000000000waithandle0x40000000000allocationsampling0x80000000000CLR プロバイダーの詳細については、 .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.socketUnix ドメイン ソケットをリッスンしている .NET ランタイム プロセスに接続します。このオプションを使用してアプリの起動時からトレースを収集する方法については、「 診断ポートを使用してアプリの起動時からトレースを収集する」を参照してください。
- Linux と macOS -
--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 スレッド スタック (最大 100 Hz) をサンプリングして、時間の経過と同時にホットスポットを識別します。 マネージド スタックでランタイム サンプル プロファイラーを使用します。 gc-verboseGC コレクションを追跡し、オブジェクトの割り当てをサンプリングします。 gc-collectオーバーヘッドが非常に低い場合にのみ GC コレクションを追跡します。 databaseADO.NET および Entity Framework データベース コマンドをキャプチャします。 注意
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
注意
collect-linux動詞は新しいプレビュー機能であり、.nettrace ファイル形式の更新バージョンに依存しています。 最新の PerfView リリースではこれらのトレース ファイルがサポートされていますが、トレース ファイルを使用する他の方法 ( convert や reportなど) はまだ機能しない可能性があります。
Linux OS テクノロジである perf_events を使用して診断トレースを収集します。
collect-linux では、 collectに対して次の追加機能が有効になります。
| 特徴 | collect |
collect-linux |
|---|---|---|
| サポートされている OS | [任意] | Linux のみ、カーネル バージョン >= 6.4 |
| 管理者/ルート権限が必要です | いいえ | イエス |
| すべてのプロセスを同時にトレースする | いいえ | サポートされています |
| ネイティブ ライブラリとカーネル イベントをキャプチャする | いいえ | サポートされています |
| イベント呼び出し履歴にはネイティブ フレームが含まれます | いいえ | イエス |
[前提条件]
-
CONFIG_USER_EVENTS=yがサポートされている Linux カーネル (カーネル 6.4 以降) - ルートのアクセス許可
- .NET 10 以降
注意
collect-linux動詞は、glibc バージョン 2.35 以上の linux x64 および linux arm64 環境でのみ実行されます。
公式にサポートされているすべての .NET 10 Linux ディストリビューションでは、Alpine 3.22、CentOS Stream 9、Red Hat Enterprise Linux 9 に基づくディストリビューションを除き、この要件がサポートされています。
システムの libc のバージョンを簡単に確認するには、コマンド ldd --version を使用するか、libc ライブラリを直接実行します。
構文
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によってオーバーライドされません。 次の表に、使用可能なイベント レベルを示します。文字列値 数値 logalways0critical1error2warning3informational4verbose5--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 進値 gc0x1gchandle0x2assemblyloader0x4loader0x8jit0x10ngen0x20startenumeration0x40endenumeration0x80security0x400appdomainresourcemanagement0x800jittracing0x1000interop0x2000contention0x4000exception0x8000threading0x10000jittedmethodiltonativemap0x20000overrideandsuppressngenevents0x40000type0x80000gcheapdump0x100000gcsampledobjectallocationhigh0x200000gcheapsurvivalandmovement0x400000managedheapcollect0x800000gcheapandtypenames0x1000000gcsampledobjectallocationlow0x2000000perftrack0x20000000stack0x40000000threadtransfer0x80000000debugger0x100000000monitoring0x200000000codesymbols0x400000000eventsource0x800000000compilation0x1000000000compilationdiagnostic0x2000000000methoddiagnostic0x4000000000typediagnostic0x8000000000jitinstrumentationdata0x10000000000profiler0x20000000000waithandle0x40000000000allocationsampling0x80000000000CLR プロバイダーの詳細については、 .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>プロファイルは、一般的なトレース シナリオ用のプロバイダー構成の定義済みセットです。 一度に複数のプロファイルをコンマで区切って指定できます。
--providersによって構成されたプロバイダーは、プロファイルの構成をオーバーライドします。 同様に、いずれかのプロファイルで CLR ランタイム プロバイダーが構成されている場合、--clreventsによって規定されたすべての構成がオーバーライドされます。--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-timeCPU のオン/オフとスケジューラの分析のために、 Universal.Events/cswitchとして出力されるカーネル スレッド コンテキスト スイッチ。gc-verboseGC コレクションを追跡し、オブジェクトの割り当てをサンプリングします。 gc-collectオーバーヘッドが非常に低い場合にのみ GC コレクションを追跡します。 databaseADO.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 Core アプリケーションのプロセス識別子 (PID) を取得します。
- Windows で、タスク マネージャーや、たとえば、
tasklistコマンドを使用できます。 - Linux の場合、たとえば、
psコマンドを使用できます。 - dotnet-trace ps
- Windows で、タスク マネージャーや、たとえば、
次のコマンドを実行します。
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> または <Ctrl + C> キーを押します。 この操作を行うと、hello.exe も終了します。
注意
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-traceでmyport.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 を使用してマシン全体のトレースを収集する
この例では、コンピューター上のすべてのプロセスの CPU サンプルをキャプチャします。 .NET 10 以降を実行しているプロセスには、GC、JIT、アセンブリの読み込み動作を記述する追加の軽量イベントも含まれます。
$ sudo dotnet-trace collect-linux
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
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
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
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
関連項目
GitHub で Microsoft と共同作業する
このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。 詳細については、共同作成者ガイドを参照してください。
.NET