dotnet-trace 效能分析公用程式

  • 發行項

本文適用于： ✔️ dotnet-trace 3.0.47001 和更新版本

安裝

有兩種方式可以下載並安裝 dotnet-trace ：

注意

dotnet-trace若要在 x86 應用程式上使用，您需要對應的 x86 版工具。

概要

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

Description

此工具 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
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace 報告

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>]
    [--show-child-io]
    [-- <command>] (for target applications running .NET 5 or later)

選項

  • --buffersize <size>

    設定記憶體內部緩衝區的大小，以 MB 為單位。 預設為 256 MB。

    注意

    如果目標進程發出的事件速度比寫入磁片快，此緩衝區可能會溢位，而且會卸載某些事件。 您可以增加緩衝區大小或減少所記錄的事件數目，來減輕此問題。

  • --clreventlevel <clreventlevel>

    要發出之 CLR 事件的詳細資訊。

  • --clrevents <clrevents>

    要以符號分隔 + 的 CLR 執行時間提供者關鍵字清單。 這是一個簡單的對應，可讓您透過字串別名指定事件關鍵字，而不是其十六進位值。 例如， dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 要求與 相同的事件 dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational 集。 下表顯示可用關鍵字的清單：

    關鍵字字串別名 關鍵字十六進位值
    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>

    所收集追蹤資料的輸出路徑。 如果未指定，則預設為 trace.nettrace 。

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

    要從中收集追蹤的進程識別碼。

  • --profile <profile-name>

    一組具名預先定義的提供者組態，可讓您簡潔地指定常見的追蹤案例。 可用設定檔如下：

設定檔 說明
cpu-sampling 適用于追蹤 CPU 使用量和一般 .NET 執行時間資訊。 如果未指定任何設定檔或提供者，這是預設選項。
gc-verbose 追蹤 GC 集合和範例物件配置。
gc-collect 只追蹤 GC 集合的負擔非常低。

  • --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 或更新版本之目標應用程式 ()

    在集合組態參數之後，使用者可以附加 -- 命令，以啟動至少具有 5.0 執行時間的 .NET 應用程式。 這在診斷程式中早期發生的問題時可能很有説明，例如啟動效能問題或元件載入器和系結器錯誤。

    注意

    使用此選項會監視第一個與工具通訊的 .NET 5 進程，這表示如果您的命令啟動多個 .NET 應用程式，它只會收集第一個應用程式。 因此，建議您在獨立應用程式上使用此選項，或使用 dotnet exec <app.dll> 選項。

  • --show-child-io

    顯示目前主控台中已啟動之子進程的輸入和輸出資料流程。

注意

  • 停止追蹤可能需要很長的時間 (大型應用程式) 幾分鐘。 執行時間必須針對追蹤中擷取的所有 Managed 程式碼，透過類型快取傳送。
  • 在 Linux 和 macOS 上，此命令需要目標應用程式，並 dotnet-trace 共用相同的 TMPDIR 環境變數。 否則，命令將會逾時。
  • 若要使用 dotnet-trace 收集追蹤，它必須以與執行目標進程或根使用者相同的使用者身分執行。 否則，此工具將無法建立與目標進程的連線。
  • 如果您看到類似下列的錯誤訊息： [ERROR] System.ComponentModel.Win32Exception (299): A 32 bit processes cannot access modules of a 64 bit process. ，您嘗試使用與目標進程不相符的 版本 dotnet-trace 。 請務必在 安裝 連結中下載工具的正確位。
  • 如果您在執行 dotnet-trace collect 時遇到未處理的例外狀況，這會導致追蹤不完整。 如果發現例外狀況的根本原因是您的優先順序，請流覽至 [收集當機時傾印]。 由於未處理的例外狀況，當執行時間關閉時會截斷追蹤，以防止其他非預期的行為，例如停止回應或資料損毀。 即使追蹤不完整，您仍然可以開啟它，以查看導致失敗的原因。 不過，在追蹤) 結尾發生此情況時，它將會遺失 Rundown (資訊，因此根據開啟) 的提供者而定，堆疊可能會無法解析 (。 使用命令列上的 旗標執行 PerfView /ContinueOnError 來開啟追蹤。 記錄也會包含引發例外狀況的位置。

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>

    輸出檔名。 將會新增目標格式的擴充功能。

注意

將 nettrace 檔案 chromium 轉換成 或 speedscope 檔案無法復原。 speedscope 和 chromium 檔案沒有重建 nettrace 檔案所需的所有資訊。 不過， convert 此命令會保留原始檔案 nettrace ，因此如果您打算在未來開啟此檔案，請勿刪除此檔案。

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 報表 topN

尋找在呼叫堆疊上最久的前 N 個方法。

概要
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
選項
  • -n|--number <n>

在 callstack 上提供前 N 個方法。

  • --inclusive

根據 內含 時間輸出前 N 個方法。 如果未指定，預設會使用獨佔時間。

  • -v|--verbose

完整輸出每個方法的參數。 如果未指定，則會截斷參數。

使用 dotnet-trace 收集追蹤

若要使用 dotnet-trace 收集追蹤：

  • 取得 .NET Core 應用程式 (PID) 的進程識別碼，以從中收集追蹤。

    • 在 Windows 上，您可以使用 Task Manager 或 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 或更新版本的應用程式。

有時候，從其啟動收集進程的追蹤可能很有用。 對於執行 .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 。

注意

透過 dotnet-trace 啟動 hello.exe 會重新導向其輸入/輸出，而且您預設無法在主控台上與其互動。 --show-child-io使用 參數與其 stdin/stdout 互動。 透過 CTRL+C 或 SIGTERM 結束工具，將會安全地結束工具和子進程。 如果子進程在工具之前結束，工具也會結束，而且追蹤應該可以安全地檢視。

使用診斷埠從應用程式啟動收集追蹤

重要

這僅適用于執行 .NET 5 或更新版本的應用程式。

診斷埠 是 .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_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 來啟動應用程式。

檢視從 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 中檢視。

注意

.NET Core 執行時間會以 nettrace 格式產生追蹤。 如果追蹤完成之後指定) ，追蹤就會轉換成速度範圍 (。 由於某些轉換可能會導致資料遺失，因此在轉換的檔案旁邊會保留原始檔案 nettrace 。

使用 dotnet-trace 收集一段時間的計數器值

dotnet-trace 可以：

  • 用於 EventCounter 效能敏感環境中的基本健康情況監視。 例如，在生產環境中。
  • 收集追蹤，使其不需要即時檢視。

例如，若要收集執行時間效能計數器值，請使用下列命令：

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

上述命令會告訴執行時間計數器每秒報告一次，以進行輕量型健全狀況監視。 EventCounterIntervalSec=1例如，以較高的值取代 (，60) 允許在計數器資料中以較少的細微性收集較小的追蹤。

下列命令可減少超過上述額外負荷和追蹤大小：

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

上述命令會停用運行時間事件和受控堆疊分析工具。

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

另請參閱