dotnet-trace 效能分析公用程式

本文適用於： ✔️ dotnet-trace 9.0.661903 及之後版本

安裝

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

dotnet 全域工具：

若要安裝最新發行版本的 dotnet-traceNuGet 套件，請使用 dotnet 工具安裝命令：
```
dotnet tool install --global dotnet-trace
```
直接下載：

下載適用於您平台的工具可執行檔：

作業系統平台

窗戶 x86 | x64 | 手臂 | Arm-x64

Linux x64 | 手臂 | Arm64 | musl-x64 | musl-Arm64

作業系統	平台
窗戶	x86 \| x64 \| 手臂 \| Arm-x64
Linux	x64 \| 手臂 \| Arm64 \| musl-x64 \| musl-Arm64

概要

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

描述

dotnet-trace 工具：

是跨平台的 .NET Core 工具。
可以在沒有原生分析工具的情況下，收集執行中處理序的 .NET Core 追蹤。
在 .NET Core 執行階段的 EventPipe 上建置。

支援兩種不同的追蹤收集方式：

這個 collect 動詞在任何作業系統上都能提供一致的功能。
此 collect-linux 動詞利用 Linux 專屬作業系統功能來提供額外功能。

特徵	`collect`	`collect-linux`
支援的OS	任意	僅限 Linux，kernel 版本 >= 6.4
需要管理員/根權限	否	Yes
同時追蹤所有程序	否	支持
擷取原生函式庫與核心事件	否	支持
事件呼叫堆疊包含原生框架	否	Yes

選項

-h|--help

顯示命令列說明。
--version

顯示 dotnet-trace 公用程式的版本。

命令

指令
dotnet-trace 收集
dotnet-trace collect-linux
dotnet-trace 轉換器
dotnet-trace ps
dotnet-trace 列表設定檔
dotnet-trace 報表

dotnet-trace 收集

從執行中的處理序收集診斷追蹤，或啟動子處理序並加以追蹤 (.NET 5 或更新版本)。如要讓工具執行子處理序並從其啟動加以追蹤，請附加 -- 至收集命令。

概要

dotnet-trace collect
    [--buffersize <size>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--dsrouter <ios|ios-sim|android|android-emu>]
    [--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 <list-of-comma-separated-profile-names>]
    [--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>

設定記憶體內部緩衝區的大小 (MB)。預設為 256 MB。

注意

如果目標處理序發出事件的速度比寫入磁碟的速度還快，那麼此緩衝區可能會溢位，使部分事件受到卸除。您可以藉由增加緩衝區大小或減少所記錄的事件數目，來減輕此問題。
--clreventlevel <clreventlevel>

要發出之 CLR 事件的詳細程度。此選項僅在 --clrevents 指定且未被 --profile--providers或覆蓋時適用。下表顯示可用的事件等級。

[字串值] 數值

logalways 0

critical 1

error 2

warning 3

informational 4

verbose 5

[字串值]	數值
`logalways`	`0`
`critical`	`1`
`error`	`2`
`warning`	`3`
`informational`	`4`
`verbose`	`5`

--clrevents <clrevents>

要以 + 符號分隔的 CLR 執行階段提供者關鍵字清單。這是簡單的對應，可讓您透過字串別名指定事件關鍵字，而不是其十六進位值。舉例來說，dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 會要求與 dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational 相同的一組事件。若 CLR 執行時提供者Microsoft-Windows-DotNETRuntime也透過或 --profile啟用--providers，則忽略此選項。下表顯示可用關鍵字列表：

關鍵字字串別名	關鍵字十六進位值
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`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`
`managedheapcollect`	`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`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

你可以在 .NET 執行時提供者參考文件中更詳細地閱讀 CLR 提供者。

'--dsrouter {ios|ios-sim|android|android-emu}

啟動 dotnet-dsrouter 並連線到它。需要安裝 dotnet-dsrouter 。如需詳細資訊，請執行 dotnet-dsrouter -h 。
--format {Chromium|NetTrace|Speedscope}

設定追蹤檔案轉換的輸出格式。預設值為 NetTrace。
-n, --name <name>

要從中收集追蹤的處理序名稱。

注意

在 Linux 和 macOS 上，使用此選項需要目標應用程式並 dotnet-trace 共用相同的 TMPDIR 環境變數。否則，命令將會逾時。
--diagnostic-port <port-address[,(listen|connect)]>

設定用來與要追蹤的進程通訊的診斷埠。目標進程內的 dotnet-trace 和 .NET 運行時間必須在埠地址上達成一致，其中一個接聽，另一個連接。 dotnet-trace 會在使用 --process-id 或 --name 選項附加時，或使用選項啟動進程 -- <command> 時，自動判斷正確的埠。通常只有在等候未來啟動的進程或與不在目前進程命名空間的容器內執行的進程通訊時，才需要明確指定埠。

與 port-address OS 不同：
- Linux 和 macOS - Unix 網域套接字的路徑，例如 /foo/tool1.socket。
- Windows - 具名管道的路徑，例如 \\.\pipe\my_diag_port1。
- Android、iOS 和 tvOS - IP：port，例如 127.0.0.1:9000。
根據預設， dotnet-trace 會在指定的位址接聽。您可以藉由在位址後面附加dotnet-trace來要求,connect連線。例如， --diagnostic-port /foo/tool1.socket,connect 會連線到接聽 Unix 網域套接字的 /foo/tool1.socket .NET 運行時間進程。

若要瞭解如何使用此選項從應用程式啟動收集追蹤，請參閱使用診斷埠從應用程式啟動收集追蹤。
--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>

要從中收集追蹤的處理序識別碼。

注意

在 Linux 和 macOS 上，使用此選項需要目標應用程式並 dotnet-trace 共用相同的 TMPDIR 環境變數。否則，命令將會逾時。

--profile <list-of-comma-separated-profile-names>

設定檔是一組預先定義的提供者配置，用於常見追蹤情境。可同時指定多個設定檔，並以逗號區分。提供者透過 --providers 覆寫該設定檔的設定來設定。同樣地，若任何設定檔配置 CLR 執行時提供者，將覆寫透過 --clrevents所規定的任何配置。

當、、全部省略時，預設值會dotnet-trace collect啟用設定檔dotnet-common。dotnet-sampled-thread-time--clrevents--providers--profile

可用資料：

設定檔	描述
`dotnet-common`	輕量級的 .NET 執行時診斷，旨在保持低開銷。包含 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap 以及編譯事件相當於 `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`。
`dotnet-sampled-thread-time`	範例 .NET 執行緒堆疊（~100 Hz），用以辨識隨時間變化的熱點。使用執行時範例分析器搭配受管理堆疊。
`gc-verbose`	追蹤 GC 集合和範例物件配置。
`gc-collect`	僅在額外負荷非常低的條件下追蹤 GC 集合。
`database`	擷取 ADO.NET 及 Entity Framework 資料庫指令。

注意

在過去版本的 dotnet-trace 工具中，collect 動詞支援一個名為 cpu-sampling的設定檔。這個帳號因為名稱具有誤導性而被移除。它會取樣所有執行緒，不論 CPU 使用率如何。你現在 --profile dotnet-sampled-thread-time,dotnet-common可以用來達到類似的結果。如果你需要完全匹配前者的 cpu-sampling 行為，可以使用 --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4"。

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

要啟用的 EventPipe 提供者逗號分隔清單。這些提供者會補足由 --profile <list-of-comma-separated-profile-names> 隱含的任何提供者。若某個提供者存在不一致，此配置優先於隱--profile--clrevents含配置與。

以下提供者名單格式為 Provider[,Provider]：
- Provider 形式為： KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs 形式為： [key1=value1][;key2=value2]
如果要深入了解 .NET 中的某些已知提供者，請參閱已知的事件提供者 (部分機器翻譯)。
-- <command> (適用於執行 .NET 5 或更新版本的目標應用程式)

使用者可以在收集設定參數之後附加 --，緊接著一個用於啟動最少具有 5.0 執行階段之 .NET 應用程式的命令。在診斷於處理序中早期發生的問題時 (例如啟動效能問題或組件載入器和繫結器錯誤)，這可能很有幫助。

注意

使用此選項會監視第一個 .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若要在達到事件提供者發出的Method/JittingStarted第一個Microsoft-Windows-DotNETRuntime事件時停止追蹤。
--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若要在事件提供者所發出Method/JittingStarted之命名空間中OnButtonClick方法Program的第一個Microsoft-Windows-DotNETRuntime事件上停止追蹤。

注意

停止大型應用程式的追蹤可能需要很長的時間 (最多數分鐘)。執行階段必須針對在追蹤中擷取的所有受控程式碼，透過類型快取傳送。

若要使用 dotnet-trace 收集追蹤，其執行身分必須與執行目標處理序的使用者或根使用者相同。否則，此工具將無法與目標處理序建立連線。

如果您在執行 dotnet-trace collect 時遇到未處理的例外狀況，這會導致追蹤不完整。如果發現例外狀況的根本原因是您的優先順序，請巡覽至在損毀時收集傾印。因為未處理的例外狀況，使得追蹤會在執行階段關閉時受到截斷，以避免發生其他非預期的行為，例如停止回應或資料損毀。即使追蹤不完整，您仍然可以開啟它，查看導致失敗的原因。不過，其將會缺少取消資訊 (這會發生在追蹤的結尾)，因此可能無法解析堆疊 (取決於開啟的提供者)。在命令列使用 /ContinueOnError 旗標執行 PerfView 來開啟追蹤。記錄也會包含引發例外狀況的位置。

透過 --stopping-event-* 選項指定停止事件時，由於正在以非同步方式剖析 EventStream，因此有些事件會在剖析與指定停止事件選項相符的追蹤事件到 EventPipeSession 停止的這段時間通過。

dotnet-trace collect-linux

注意

這個 collect-linux 動詞是新的預覽功能，並依賴更新版的 .nettrace 檔案格式。最新的 PerfView 版本支援這些追蹤檔案，但其他使用追蹤檔案的方式，如 convertreport和，可能尚未可用。

利用 Linux 作業系統技術 perf_events 收集診斷痕跡。 collect-linux使得以下附加功能得以實現。collect

	收集	collect-linux
支援的OS	任意	僅限 Linux，kernel 版本 >= 6.4
需要管理員/根權限	否	Yes
同時追蹤所有程序	否	支持
擷取原生函式庫與核心事件	否	支持
事件呼叫堆疊包含原生框架	否	Yes

先決條件

支援 CONFIG_USER_EVENTS=y Linux 核心（核心 6.4+）
根權限
.NET 10+

注意

這個 collect-linux 動詞只能在擁有 glibc 2.35 或以上版本的 Linux x64 和 linux arm64 環境中執行。所有官方支援的 Linux 發行版都支援此項需求，唯獨 Alpine 3.22、CentOS Stream 9 及基於 Red Hat Enterprise Linux 9 的發行版例外。快速檢查系統 libc 版本的方法是使用指令 ldd --version 或直接執行 libc 函式庫。

概要

dotnet-trace collect-linux
    [-h|--help]

    # Provider/Event Specification
    [--providers <list-of-comma-separated-providers>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--perf-events <list-of-perf-events>]
    [--profile <list-of-comma-separated-profile-names>]

    # Trace Collection
    [-o|--output <trace-file-path>]
    [--duration dd:hh:mm:ss]

    # .NET Process Target (Optional)
    [-n, --name <name>]
    [-p|--process-id <pid>]

    # Probe mode
    [--probe]

預設收集行為

當 --providers、 --profile、 --clrevents和 --perf-events 未指定時，預設 collect-linux 啟用這些設定檔：

dotnet-common — 輕量級.NET執行時診斷。
cpu-sampling — 核心 CPU 取樣。

預設情況下，機器上的所有程序都會被追蹤。若要只追蹤一個程序，請使用 -n, --name <name> 或 -p|--process-id <PID>。

選項

提供者/事件規範選項

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

要啟用的 EventPipe 提供者逗號分隔清單。這些提供者會補足由 --profile <list-of-comma-separated-profile-names> 隱含的任何提供者。若某個提供者存在不一致，此配置優先於隱--profile--clrevents含配置與。

以下提供者名單格式為 Provider[,Provider]：
- Provider 形式為： KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
- KeyValueArgs 形式為： [key1=value1][;key2=value2]
想了解更多關於 .NET 中一些知名的服務提供者，請參閱「知名活動提供者」。
--clreventlevel <clreventlevel>

要發出之 CLR 事件的詳細程度。此選項僅在 --clrevents 指定且未被 --profile--providers或覆蓋時適用。下表顯示可用的事件等級。

[字串值] 數值

logalways 0

critical 1

error 2

warning 3

informational 4

verbose 5

[字串值]	數值
`logalways`	`0`
`critical`	`1`
`error`	`2`
`warning`	`3`
`informational`	`4`
`verbose`	`5`

--clrevents <clrevents>

要以 + 符號分隔的 CLR 執行階段提供者關鍵字清單。這是簡單的對應，可讓您透過字串別名指定事件關鍵字，而不是其十六進位值。舉例來說，dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 會要求與 dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational 相同的一組事件。若 CLR 執行時提供者Microsoft-Windows-DotNETRuntime也透過或 --profile啟用--providers，則忽略此選項。下表顯示可用關鍵字列表：

關鍵字字串別名	關鍵字十六進位值
`gc`	`0x1`
`gchandle`	`0x2`
`assemblyloader`	`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`
`managedheapcollect`	`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`
`jitinstrumentationdata`	`0x10000000000`
`profiler`	`0x20000000000`
`waithandle`	`0x40000000000`
`allocationsampling`	`0x80000000000`

你可以在 .NET 執行時提供者參考文件中更詳細地閱讀 CLR 提供者。

--perf-events <list-of-perf-events>

一個逗號分隔的穿透事件清單，包含在追蹤中。可用事件可在 tracefs 下找到，通常掛載於 /sys/kernel/tracing，所有可用事件則掛載於， available_events 或透過 events/ 子目錄（分類事件）找到。

範例：--perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

--profile <list-of-comma-separated-profile-names>

當、、、全部省略時，預設會dotnet-trace collect-linux啟用設定檔 dotnet-common 和 cpu-sampling 。--perf-events--clrevents--providers--profile

可用資料：

設定檔	描述
`dotnet-common`	輕量級的 .NET 執行時診斷，旨在保持低開銷。包含 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap 以及編譯事件相當於 `--providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"`。
`cpu-sampling`	核心 CPU 取樣（基於 perf），以形式輸出 `Universal.Events/cpu`，以精確的 CPU 上歸屬。
`thread-time`	核心執行緒上下文切換，以 `Universal.Events/cswitch`表示，用於 CPU 開關及排程器分析。
`gc-verbose`	追蹤 GC 集合和範例物件配置。
`gc-collect`	僅在額外負荷非常低的條件下追蹤 GC 集合。
`database`	擷取 ADO.NET 及 Entity Framework 資料庫指令。

痕跡收集選項

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

所收集追蹤資料的輸出路徑。若未指定，預設為全機追蹤，程序特定追蹤--name則預設為 trace_<yyyyMMdd>_<HHmmss>.nettrace （<appname>_<yyyyMMdd>_<HHmmss>.nettrace或--process-id）
--duration <time-to-run>

追蹤執行的時間。使用 dd:hh:mm:ss 格式。假如為 00:00:00:05，其執行時間將為 5 秒。

.NET 程序目標選項

參見預設收集行為

-n, --name <name>

要從中收集追蹤的處理序名稱。
-p|--process-id <PID>

要從中收集追蹤的處理序識別碼。

探測模式選項

--probe [-n|--name] [-p|--process-id] [-o|--output <stdout|output-filename>]

探測 .NET 程序，支援 collect-linux 使用的 EventPipe UserEvents IPC 指令，且不收集追蹤。結果會先列出支援的流程。用 '-o stdout' 列印 CSV（pid、processName、supportsCollectLinux）到主控台，或用「-o output-filename' 寫入 CSV。探測一個單一程序，名稱為 -n|--name 或 -p|--process-id。

由於以探測模式執行 collect-linux 不會收集追蹤，因此執行時不需要根權限。它不提供前置條件的驗證，且在 .NET 執行時 '10.0.0' 預覽版上運行的 .NET 程序被視為不被支援。

注意

要使用，必須以根權限CAP_PERFMON/CAP_SYS_ADMIN（）執行dotnet-trace collect-linux追蹤。否則，工具將無法收集事件。

dotnet-trace 轉換器

將 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 和更新版本也會顯示啟動每個處理序時所用的命令列引數 (如果有的話)。

注意

若要取得列舉 64 位進程的完整資訊，您必須使用 64 位版本的 dotnet-trace 工具。

概要

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 列表設定檔

列出預先建置的追蹤設定檔，其中有每個設定檔中所包含提供者和篩選的描述。

概要

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>

提供呼叫堆疊上的前 N 個方法。

--inclusive

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

-v|--verbose

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

使用 dotnet-trace 收集追蹤

如要使用 dotnet-trace collect 收集追蹤：

取得要從中收集追蹤之 .NET Core 應用程式的處理序識別碼 (PID)。
- 在 Windows 上，可以使用工作管理員或像是 tasklist 這樣的命令。
- 例如，在 Linux 上，可以使用 ps 命令。
- dotnet-trace ps

執行以下命令：

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

上述命令產生的輸出，類似如下：

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : <full-path-to-process-being-trace>
Output File    : <process>_20251007_154557.nettrace
[00:00:00:02]   Recording trace 178.172  (KB)
Press <Enter> or <Ctrl+C> to exit...
Stopping the trace. This may take several minutes depending on the application being traced.

Trace completed.

按下 Enter 鍵停止收集。 dotnet-trace 會完成將事件記錄到檔案中 .nettrace 。

啟動子應用程式，並使用 dotnet-trace 從其啟動收集追蹤

有時候從啟動收集處理序追蹤很有用。對於執行 .NET 5 或更新版本的應用程式，可以使用 dotnet-trace 來執行此動作。

這會啟動具有命令列引數 hello.exe 和 arg1 的 arg2，並從其執行階段啟動收集追蹤：

dotnet-trace collect -- hello.exe arg1 arg2

上述命令產生的輸出，類似如下：

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  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 中新增的執行階段功能，可讓您從應用程式啟動開始追蹤。如要使用 dotnet-trace 這麼做，您可以使用如上述範例中所述的 dotnet-trace collect -- <command>，或是使用 --diagnostic-port 選項。

如要快速地從應用程式啟動加以追蹤，那麼使用 dotnet-trace <collect|monitor> -- <command> 將應用程式作為子處理序啟動是最簡單的方法。

不過，當您想更精細地控制受追蹤的應用程式存留期 (例如只監控應用程式前 10 分鐘並繼續執行)，或是需要使用 CLI 與應用程式互動時，使用 --diagnostic-port 選項可讓您同時控制監控的目標應用程式與 dotnet-trace。

下列命令會讓 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

在另一個主控台中，使用環境變數 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 來啟動應用程式。

（僅限 Linux 平台）使用 dotnet-trace 收集全機器追蹤

此範例捕捉了機器上所有程序的 CPU 樣本。任何執行 .NET 10+ 的程序也會包含一些描述 GC、JIT 和組合語言載入行為的輕量級事件。

$ sudo dotnet-trace collect-linux
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile

Linux Perf Events                                                               Enabled By
cpu-sampling                                                                    --profile

Output File    : <path-to-nettrace>trace_20251008_181939.nettrace

[00:00:00:03]   Recording trace.
Press <Enter> or <Ctrl-C> to exit...

Recording stopped.
Resolving symbols.
Finished recording trace.
Trace written to <path-to-nettrace>trace_20251008_181939.nettrace

對於安裝多個 .NET 版本的環境，以探測模式執行collect-linux有助於判斷 .NET 程序是否能被 collect-linux 追蹤。

$ dotnet-trace collect-linux --probe
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

檢視從 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 格式產生追蹤。如有指定，則追蹤會在完成後轉換為 speedscope 格式。由於某些轉換可能會導致資料遺失，因此會保留已轉換檔案旁的原始檔案 nettrace。

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

另請參閱

.NET 中已知的事件提供者

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-08