Программа анализа производительности dotnet-tracedotnet-trace performance analysis utility

Эта статья относится к следующему. ✔️ SDK для .NET Core 3.0 и более поздних версийThis article applies to: ✔️ .NET Core 3.0 SDK and later versions

Установка dotnet-traceInstall dotnet-trace

Установите пакет NuGet dotnet-trace с помощью команды dotnet tool install: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.
  • Создано на основе кроссплатформенной технологии EventPipe для среды выполнения .NET Core.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 МБ.Default 256 MB.

  • --clreventlevel <clreventlevel>

    Уровень детализации создаваемых событий среды выполнения.Verbosity of CLR events to be emitted.

  • --clrevents <clrevents>

    Список вызываемых событий среды выполнения.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>

    Идентификатор процесса, из которого нужно получить трассировку.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-traceCollect a trace with dotnet-trace

Для сбора трассировок с помощью dotnet-trace выполните указанные ниже действия.To collect traces using dotnet-trace:

  • Получите идентификатор процесса (PID) для трассируемого приложения .NET Core.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-traceView 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-trace создаст файл speedscope.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

Эта команда означает, что счетчики среды выполнения будут отслеживаться каждую секунду, то есть реализует не требовательную к ресурсам схему мониторинга работоспособности.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
Ключевые слова среды выполнения CLRCLR Runtime Keywords
Microsoft-Windows-DotNETRuntimeRundown Поставщик очисткиThe Rundown Provider
Ключевые слова очистки CLRCLR Rundown Keywords
Microsoft-DotNETCore-SampleProfiler Включает пример профилировщика.Enables the sample profiler.