パフォーマンス分析ユーティリティ (dotnet-trace) 用のトレースTrace for performance analysis utility (dotnet-trace)

この記事の対象: .NET Core 3.0 SDK 以降のバージョンThis article applies to: .NET Core 3.0 SDK and later versions

dotnet-trace のインストールInstalling dotnet-trace

dotnet-trace NuGet パッケージの最新のリリース バージョンをインストールするには、次のように dotnet tool install コマンドを使用します。To install the latest release version of the dotnet-trace NuGet package, use the dotnet tool install command:

dotnet tool install --global dotnet-trace

構文Synopsis

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

説明Description

dotnet-trace ツールは、ネイティブ プロファイラーを使用せずに、実行中のプロセスの .NET Core のトレースを収集するクロスプラットフォームの CLI グローバル ツールです。The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. これは、.NET Core ランタイムのクロスプラットフォームの EventPipe テクノロジを中心に構築されています。It's built around the cross-platform EventPipe technology of the .NET Core runtime. dotnet-trace は、Windows、Linux または macOS でも同じエクスペリエンスを提供します。dotnet-trace delivers the same experience on Windows, Linux, or macOS.

オプションOptions

  • --version

dotnet-counters ユーティリティのバージョンを表示します。Display the version of the dotnet-counters utility.

  • -h|--help

コマンド ラインのヘルプを表示します。Show command-line help.

コマンドCommands

コマンドCommand
dotnet-trace collectdotnet-trace collect
dotnet-trace convertdotnet-trace convert
dotnet-trace list-processesdotnet-trace list-processes
dotnet-trace list-profilesdotnet-trace list-profiles

dotnet-trace collectdotnet-trace collect

実行中のプロセスから診断トレースを収集します。Collects a diagnostic trace from a running process.

構文Synopsis

dotnet-trace collect [-h|--help] [-p|--process-id] [--buffersize <size>] [-o|--output]
    [--providers] [--profile <profile-name>] [--format]

オプションOptions

  • -p|--process-id <PID>

    トレースを収集するプロセス。The process to collect the trace from.

  • --buffersize <size>

    メモリ内の循環バッファーのサイズをメガバイトに設定します。Sets the size of the in-memory circular buffer in megabytes. 既定は 256 MB です。Default 256 MB.

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

    収集されたトレース データの出力パス。The output path for the collected trace data. 指定しない場合の既定は、trace.nettrace です。If not specified it defaults to trace.nettrace.

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

    有効にする EventPipe プロバイダーのコンマ区切りのリスト。A comma-separated list of EventPipe providers to be enabled. これらのプロバイダーは、--profile <profile-name> で示されている任意のプロバイダーを補完します。These providers supplement any providers implied by --profile <profile-name>. 特定のプロバイダーに不整合がある場合、この構成がプロファイルの暗黙的な構成に優先されます。If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile.

    プロバイダーの一覧の形式は、次のとおりです。This list of providers is in the form:

    • Provider[,Provider]
    • Provider は、KnownProviderName[:Flags[:Level][:KeyValueArgs]] という形式です。Provider is in the form: KnownProviderName[:Flags[:Level][:KeyValueArgs]].
    • KeyValueArgs は、[key1=value1][;key2=value2] という形式です。KeyValueArgs is in the form: [key1=value1][;key2=value2].
  • --profile <profile-name>

    共通のトレース シナリオを簡潔に指定できるようにする、事前定義されたプロバイダーの名前付き構成のセット。A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly.

  • --format <NetTrace|Speedscope>

    トレース ファイルの出力の変換形式を設定します。Sets the output format for the trace file conversion.

dotnet-trace convertdotnet-trace convert

nettrace トレースを、別のトレース分析ツールで使用するために、別の形式に変換します。Converts nettrace traces to alternate formats for use with alternate trace analysis tools.

構文Synopsis

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

引数Arguments

  • <input-filename>

    変換する入力トレース ファイル。Input trace file to be converted. 既定は trace.nettrace です。Defaults to trace.nettrace.

オプションOptions

  • --format <NetTrace|Speedscope>

    トレース ファイルの出力の変換形式を設定します。Sets the output format for the trace file conversion.

  • -o|--output <output-filename>

    出力ファイルの名前。Output filename. ターゲットの形式の拡張子が追加されます。Extension of target format will be added.

dotnet-trace list-processesdotnet-trace list-processes

トレースできる dotnet プロセスの一覧を示します。Lists dotnet processes that can be traced.

構文Synopsis

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

dotnet-trace list-profilesdotnet-trace list-profiles

各プロファイルに含まれるプロバイダーとフィルターの記述と共に、事前に構築されているトレースのプロファイルを一覧表示します。Lists pre-built tracing profiles with a description of what providers and filters are in each profile.

構文Synopsis

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

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

  • dotnet-trace を使用してトレースを収集するには、まずトレースを収集する .NET Core アプリケーションのプロセス識別子 (PID) を調べます。To collect traces using dotnet-trace, you'll need to first, find out the process identifier (PID) of the .NET Core application to collect traces from.

    • Windows では、タスク マネージャーや tasklist コマンドなどを使用するオプションがあります。On Windows, there are options such as using the task manager or the tasklist command.
    • Linux での簡易オプションは、ps コマンドの使用です。On Linux, the trivial option could be using ps command.

また、その PID と共に dotnet-trace list-processes コマンドを使用して、実行中の .NET Core プロセスを調べることもできます。You may also use the dotnet-trace list-processes command to find out what .NET Core processes are running, along with their PIDs.

  • 次に、次のコマンドを実行します。Then, run the following command:
> 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-tracetrace.nettrace ファイルへのイベントのログ記録を終了します。Finally, stop collection by pressing the <Enter> key, and dotnet-trace will finish logging events to trace.nettrace file.

dotnet-trace でキャプチャしたトレースを表示するViewing the trace captured from dotnet-trace

Windows で .nettrace ファイルは、ETW または LTTng を使用して収集したトレースと同様、PerfView で参照して分析できます。On Windows, .nettrace files can be viewed on PerfView for analysis, just like traces collected with ETW or LTTng. Linux で収集したトレースを PerfView で参照するには、トレースを Windows マシンに移動します。For traces collected on Linux, you can move the trace to a Windows machine to be viewed on PerfView.

また、dotnet-trace の出力形式を speedscope に変更して、Linux マシンでトレースを表示することもできます。You may also view the trace on a Linux machine by changing the output format of dotnet-trace to speedscope. 出力ファイルの形式は、-f|--format オプションを使用して変更できます。-f speedscope が、dotnet-tracespeedscope ファイルを生成させます。You can change the output file format using the -f|--format option - -f speedscope will make dotnet-trace to produce a speedscope file. 現在、nettrace (既定のオプション) と speedscope の間で選択できます。You can currently choose between nettrace (the default option) and speedscope. Speedscope ファイルは https://www.speedscope.app で開くことができます。Speedscope files can be opened at https://www.speedscope.app.

注意

.NET Core ランタイムは、トレースを nettrace 形式で生成し、トレースの完了後 (指定されている場合は)、それを speedscope に変換します。The .NET Core runtime generates traces in the nettrace format, and they're converted to speedscope (if specified) after the trace is completed. 変換によってはデータが失われる場合もあるため、元の nettrace ファイルが変換されたファイルの横に保持されます。Since some conversions may result in loss of data, the original nettrace file is preserved next to the converted file.

dotnet-trace を使用して経時的なカウンター値を収集するUsing dotnet-trace to collect counter values over time

パフォーマンスが影響する運用環境などの正常性の基本監視に EventCounter を使用する場合に、リアルタイムで監視するのではなく、トレースを収集したい場合は、dotnet-trace で行うこともできます。If you're trying to use EventCounter for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real time, you can do that with dotnet-trace as well.

たとえば、実行時のパフォーマンス カウンター値を収集したい場合は、次のコマンドを使用します。For example, if you want to collect runtime performance counter values, you can use the following command:

dotnet-trace collect --process-id <PID> --providers System.Runtime:0:1:EventCounterIntervalSec=1

このコマンドは、正常性の簡易監視のために 1 秒ごとにランタイム カウンターをレポートします。This command tells the runtime counters to be reported once every second for lightweight health monitoring. EventCounterIntervalSec=1 の値を (60 など) 大きい値に置き換えた場合、カウンター データの細分性の詳細度がより低いトレースをより少数収集できるようになります。Replacing EventCounterIntervalSec=1 with a higher value (for example, 60) allows you to collect a smaller trace with less granularity in the counter data.

ランタイム イベントを無効にしてオーバーヘッド (およびトレースのサイズ) をさらに減らしたい場合は、次のコマンドを使用して、ランタイム イベントとマネージド スタック プロファイラーを無効にできます。If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler.

dotnet-trace collect --process-id <PID> --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1

.NET プロバイダー.NET Providers

.NET Core ランタイムでは、次の .NET プロバイダーがサポートされています。The .NET Core runtime supports the following .NET providers. .NET Core では、Event Tracing for Windows (ETW)EventPipe トレースの有効化に、いずれも同じキーワードを使用しています。.NET Core uses the same keywords to enable both Event Tracing for Windows (ETW) and EventPipe traces.

プロバイダー名Provider name 情報Information
Microsoft-Windows-DotNETRuntime ランタイム プロバイダーThe Runtime Provider
CLR ランタイム キーワードCLR Runtime Keywords
Microsoft-Windows-DotNETRuntimeRundown ランダウン プロバイダーThe Rundown Provider
CLR ランダウン キーワードCLR Rundown Keywords
Microsoft-DotNETCore-SampleProfiler サンプル プロファイラーを有効にします。Enables the sample profiler.