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

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

インストール

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

• dotnet グローバル ツール:

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

  dotnet tool install --global dotnet-trace
  

• 直接ダウンロード:

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

  OS	プラットフォーム
  Windows	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 に基づいています。
• Windows、Linux または macOS でも同じエクスペリエンスを提供します。

オプション

• -h|--help

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

• --version

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

• --duration

  トレースを実行する時間。 --duration 00:00:00:05 は、5 秒間実行されることを示します。

コマンド

dotnet-trace collect

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

構文

dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--clrevents <clrevents>]
    [--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 <profile-name>] [--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 イベントの詳細度。 次の表に、使用可能なイベント レベルを示します。

  文字列値	数値
  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 と同じイベントのセットが要求されます。 次の表に、使用できるキーワードの一覧を示します。

  キーワードの文字列別名	キーワードの 16 進値
  gc	0x1
  gchandle	0x2
  fusion	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
  gcheapcollect	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

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

• --format {Chromium|NetTrace|Speedscope}

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

• -n, --name <name>

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

• --diagnostic-port <path-to-port>

  作成する診断ポートの名前。 このオプションを使用してアプリの起動からトレースを収集する方法については、「診断ポートを使用してアプリの起動からトレースを収集する」を参照してください。

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

• --profile <profile-name>

  共通のトレース シナリオを簡潔に指定できるようにする、事前定義されたプロバイダーの名前付き構成のセット。 次のプロファイルを利用できます。

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

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

  プロバイダーの一覧の形式は、次のとおりです。

  • Provider[,Provider]
  • Provider は、KnownProviderName[:Flags[:Level][:KeyValueArgs]] という形式です。
  • KeyValueArgs は、[key1=value1][;key2=value2] という形式です。

  .NET でのいくつかの既知のプロバイダーの詳細については、既知のイベント プロバイダーに関するページを参照してください。

• -- <command> (対象アプリケーションが .NET 5.0 以降を実行している場合)

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

  Note

  このオプションを使用すると、ツールに通信する最初の .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 は、Microsoft-Windows-DotNETRuntime イベント プロバイダーによって出力された最初の Method/JittingStarted イベントにヒットしたときにトレースを停止します。

• --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 は、Microsoft-Windows-DotNETRuntime イベント プロバイダーによって出力された Program 名前空間の OnButtonClick メソッドに対する最初の Method/JittingStarted イベントでトレースを停止します。

• 大きなアプリケーションの場合、トレースの停止に時間がかかることがあります (最大数分)。 ランタイムでは、トレースにキャプチャされたすべてのマネージド コードを対象に、型キャッシュを送信する必要があります。

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

• dotnet-trace を使ってトレースを収集するには、ターゲット プロセスを実行しているユーザーと同じユーザーまたはルートとして実行する必要があります。 それ以外の場合、このツールでターゲット プロセスとの接続を確立することはできません。

• dotnet-trace collect の実行中にハンドルされない例外が発生した場合、トレースが不完全になります。 例外の根本原因を見つけることが優先される場合、「クラッシュ時にダンプの収集」に移動してください。 ハンドルされない例外の結果として、ランタイムがシャットダウンするときにトレースが切り捨てられ、ハングやデータの破損などの他の望ましくない動作を防ぐことができます。 トレースが不完全な場合でも、それを開いて、障害に至るまで何が起こったかを確認することができます。 ただし、ランダウン情報 (これはトレースの最後に発生します) が欠落しているので、スタックが解決されない可能性があります (有効になっているプロバイダーによって異なります)。 コマンドラインで /ContinueOnError フラグを指定して PerfView を実行し、トレースを開きます。 ログには、例外が発生した場所も含まれます。

• --stopping-event-* オプションを使用して停止イベントを指定すると、EventStream が非同期的に解析されるため、指定された停止イベント オプションに一致するトレース イベントが解析されてから、EventPipeSession が停止されるまでの間に、パススルーするイベントがいくつか発生します。

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 report

以前に生成されたトレースから 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 を使用してトレースを収集するには:

• トレースを収集する .NET Core アプリケーションのプロセス識別子 (PID) を取得します。

  • Windows で、タスク マネージャーや、たとえば、tasklist コマンドを使用できます。
  • Linux の場合、たとえば、ps コマンドを使用できます。
  • dotnet-trace ps

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

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

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

  Press <Enter> to exit...
  Connecting to process: <Full-Path-To-Process-Being-Profiled>/dotnet.exe
  Collecting to file: <Full-Path-To-Trace>/trace.nettrace
  Session Id: <SessionId>
  Recording trace 721.025 (KB)
  

• <Enter> キーを押すと、コレクションが停止します。 dotnet-trace では、trace.nettrace ファイルにイベントをログ記録する作業が完了します。

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

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

これを使用すると、コマンドライン引数として arg1 と arg2 を含む hello.exe が起動され、そのランタイム スタートアップからトレースが収集されます。

dotnet-trace collect -- hello.exe arg1 arg2

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

No profile or providers specified, defaulting to trace profile 'cpu-sampling'

Provider Name                           Keywords            Level               Enabled By
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile
Microsoft-Windows-DotNETRuntime         0x00000014C14FCCBD  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 も終了します。

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

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

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

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

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

2. 別のコンソールで、dotnet-trace の出力値に設定された環境変数 DOTNET_DiagnosticPorts を使用して対象アプリケーションを起動します。

   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 を使用することをお勧めします。

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 ファイルを使用し、長いコマンドの入力を避ける

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

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

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 の既知のイベント プロバイダー