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

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

dotnet-trace をインストールするInstall dotnet-trace

dotnet tool install コマンドで dotnet-trace NuGet パッケージをインストールします。Install dotnet-trace NuGet package with the dotnet tool install command:

dotnet tool install --global dotnet-trace

構文Synopsis

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

説明Description

dotnet-trace ツール:The dotnet-trace tool:

  • クロスプラットフォーム .NET Core ツールです。Is a cross-platform .NET Core tool.
  • ネイティブ プロファイラーなしで実行中のプロセスの .NET Core トレースを回収できます。Enables the collection of .NET Core traces of a running process without a native profiler.
  • .NET Core ランタイムのクロスプラットフォームの EventPipe テクノロジを中心に構築されています。Is built around the cross-platform EventPipe technology of the .NET Core runtime.
  • Windows、Linux または macOS でも同じエクスペリエンスを提供します。Delivers the same experience on Windows, Linux, or macOS.

オプションOptions

  • -h|--help

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

  • --version

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

コマンドCommands

コマンドCommand
dotnet-trace collectdotnet-trace collect
dotnet-trace convertdotnet-trace convert
dotnet-trace psdotnet-trace ps
dotnet-trace list-profilesdotnet-trace list-profiles

dotnet-trace collectdotnet-trace collect

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

構文Synopsis

dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--clrevents <clrevents>]
    [--format <Chromium|NetTrace|Speedscope>] [-h|--help]
    [-n, --name <name>]  [-o|--output <trace-file-path>] [-p|--process-id <pid>]
    [--profile <profile-name>] [--providers <list-of-comma-separated-providers>]

オプションOptions

  • --buffersize <size>

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

  • --clreventlevel <clreventlevel>

    生成される CLR イベントの詳細度。Verbosity of CLR events to be emitted.

  • --clrevents <clrevents>

    生成する CLR ランタイム イベントの一覧。List of CLR runtime events to emit.

  • --format {Chromium|NetTrace|Speedscope}

    トレース ファイルの出力の変換形式を設定します。Sets the output format for the trace file conversion. 既定値は、NetTrace です。The default is NetTrace.

  • -n, --name <name>

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

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

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

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

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

  • --profile <profile-name>

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

  • --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, this configuration 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].

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>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

引数Arguments

  • <input-filename>

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

オプションOptions

  • --format <Chromium|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 psdotnet-trace ps

トレースを収集できる dotnet プロセスを一覧表示します。Lists the dotnet processes that traces can be collected from.

構文Synopsis

dotnet-trace ps [-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 を使用してトレースを収集するには:To collect traces using dotnet-trace:

  • トレースを収集する .NET Core アプリケーションのプロセス識別子 (PID) を取得します。Get the process identifier (PID) of the .NET Core application to collect traces from.

    • Windows で、タスク マネージャーや、たとえば、tasklist コマンドを使用できます。On Windows, you can use Task Manager or the tasklist command, for example.
    • Linux の場合、たとえば、ps コマンドを使用できます。On Linux, for example, the ps command.
    • dotnet-trace psdotnet-trace ps
  • 次のコマンドを実行します。Run the following command:

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

    上のコマンドを実行すると、次のような出力が生成されます。The preceding command generates output similar to the following:

    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> キーを押すと、コレクションが停止します。Stop collection by pressing the <Enter> key. dotnet-trace では、trace.nettrace ファイルにイベントをログ記録する作業が完了します。dotnet-trace will finish logging events to the trace.nettrace file.

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

Windows の場合、 .nettrace ファイルを PerfView で表示し、分析できます。他のプラットフォームで収集されたトレースについては、トレース ファイルを Windows コンピューターに移動し、PerfView で表示できます。On Windows, .nettrace files can be viewed on PerfView for analysis: For traces collected on other platforms, the trace file can be moved to a Windows machine to be viewed on PerfView.

Linux の場合、dotnet-trace の出力形式を speedscope に変更することでトレースを表示できます。On Linux, the trace can be viewed by changing the output format of dotnet-trace to speedscope. 出力ファイル形式は -f|--format オプションで変更できます。-f speedscope により、dotnet-tracespeedscope ファイルが生成されます。The output file format can be changed using the -f|--format option - -f speedscope will make dotnet-trace produce a speedscope file. nettrace (既定のオプション) か speedscope を選択できます。You can 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 形式でトレースが生成されます。The .NET Core runtime generates traces in the nettrace format. トレースの完了後、トレースは speedscope に変換されます (指定されている場合)。The traces are 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 を使用して経時的なカウンター値を収集するUse dotnet-trace to collect counter values over time

dotnet-trace でできること:dotnet-trace can:

  • パフォーマンスで左右される環境で基本的な正常性監視を行うには EventCounter を使用します。Use EventCounter for basic health monitoring in performance-sensitive environments. たとえば、運用環境です。For example, in production.
  • リアルタイムで表示する必要がないようにトレースを収集します。Collect traces so they don't need to be viewed in real time.

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

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

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

次のコマンドでは、先のコマンドよりオーバーヘッドとトレース サイズが少なくなります。The following command reduces overhead and trace size more than the preceding one:

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

上のコマンドでは、ランタイム イベントとマネージド スタック プロファイラーが無効になります。The preceding command disables runtime events and the managed stack profiler.

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