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

実行中のプロセスから診断トレースを収集するか、子プロセスを起動してそれをトレースします (.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

• --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 collect-linux

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

[前提条件]

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

構文

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

• --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>

  プロファイルは、一般的なトレース シナリオ用のプロバイダー構成の定義済みセットです。 一度に複数のプロファイルをコンマで区切って指定できます。 --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-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>

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

dotnet-trace ps

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

構文

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 キーまたは + キーを押すと、トレースの収集を停止できます。これを行うと、も終了します。

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

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

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

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

1. 次のコマンド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
   

2. 別のコンソールで、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 を使用します。

1. dotnet-symbol をインストールします。

   dotnet tool install -g dotnet-symbol
   

2. ランタイム バージョンのデバッグ シンボルをダウンロードします。 たとえば、ランタイムが /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
   

3. 対応するランタイム ライブラリの横に、ダウンロードした.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 で表示することもできます。

.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

関連項目

• .NET の既知のイベント プロバイダー