使用 PerfCollect 追蹤 .NET 應用程式

2025-04-22

本文適用於：✔️ .NET Core 2.1 SDK 和更新版本

在 Linux 上遇到效能問題時，可以使用 perfcollect 工具來收集有關效能問題發生時機器上發生的詳細資訊。

perfcollect 是一個 Bash 腳本，使用 Linux 追蹤工具組：新一代（LTTng）來收集從執行階段或任何 EventSource 寫入的事件，以及使用 perf 來收集目標進程的 CPU 樣本。

準備您的電腦

請遵循下列步驟來準備您的計算機，以使用 perfcollect收集效能追蹤。

備註

如果您要從容器內部擷取，您的容器必須具備適當的功能。最少的必要功能是 PERFMON 與 SYS_PTRACE。如果擷取失敗且設定最少，請將 SYS_ADMIN 功能新增至容器。如需使用 PerfCollect 追蹤容器內應用程式的詳細資訊，請參閱收集容器中的診斷。

下載 perfcollect。
```
curl -OL https://aka.ms/perfcollect
```
讓腳本成為可執行檔。
```
chmod +x perfcollect
```
安裝追蹤必要條件 - 這些是實際的追蹤連結庫。
```
sudo ./perfcollect install
```
這會在您的電腦上安裝下列必要條件：
1. perf：Linux 效能事件子系統和隨附的使用者模式集合/查看器應用程式。 perf 是 Linux 核心來源的一部分，但預設不會安裝。
2. LTTng：用來擷取 CoreCLR 在運行時間發出的事件數據。接著，此數據可用來分析各種運行時間元件的行為，例如 GC、JIT 和線程集區。

最新版的 .NET Core 和 Linux perf 工具支援自動解析架構程式代碼的方法名稱。

若要解析原生運行時間 DLL 的方法名稱（例如 libcoreclr.so）， perfcollect 會在轉換數據時解析它們的符號，但前提是這些二進位檔的符號存在。如需詳細資訊，請參閱取得原生運行時間的符號一節。

收集追蹤資料

有兩個殼層可供使用 - 一個用於控制追蹤，稱為 [追蹤]，另一個用於執行應用程式，稱為 [應用]。
[追蹤] 開始集合。
```
sudo ./perfcollect collect sampleTrace
```
預期輸出：
```
Collection started.  Press CTRL+C to stop.
```
備註

LTTng 在 2.12 版和 2.13 版之間發生了重大變更。 .NET 運行時間目前支援 2.12 版。如果您的 Linux 發行版已採用 2.13 或更新版本，建議您停用 perfcollect 功能的 LTTng 部分。若要這樣做，請將選項 '-nolttng' 新增至 perfcollect 命令行，並在步驟 3 中不會設定DOTNET_EnableEventLog環境變數。
[應用程式] 使用下列環境變數設定應用程式殼層 - 這會啟用 CoreCLR 的追蹤設定。
[應用程式] 使用下列環境變數設定應用程式殼層 - 這會啟用 CoreCLR 的追蹤設定。
```
export DOTNET_PerfMapEnabled=1
export DOTNET_EnableEventLog=1
```
備註

使用 .NET 7 執行應用程式時，除了上述環境變數之外，您也必須設定 DOTNET_EnableWriteXorExecute=0。例如：
```
export DOTNET_EnableWriteXorExecute=0
```
備註

.NET 6 會針對設定 .NET Runtime 行為的環境變數，透過前置詞 DOTNET_ (而非 COMPlus_) 進行標準化。不過，COMPlus_ 前綴會繼續運作。如果使用舊版的 .NET 執行階段，則您仍應對環境變數使用 COMPlus_ 前置詞。
[應用程式] 執行應用程式 - 只要您需要執行，即可擷取效能問題。只要確切的長度足以擷取您想要調查的效能問題發生時間範圍，確切長度就可能很短。
```
dotnet run
```

[追蹤] 停止收集 - 按 Ctrl+C。

^C
...STOPPED.
    Starting post-processing. This may take some time.
    Generating native image symbol files
...SKIPPED
Saving native symbols
...FINISHED
Exporting perf.data file
...FINISHED
Compressing trace files
...FINISHED
Cleaning up artifacts
...FINISHED
    Trace saved to sampleTrace.trace.zip

壓縮的追蹤檔案現在會儲存在目前的工作目錄中。

查看跟蹤紀錄

有數個選項可用來查看已收集的跟踪記錄。追蹤最適合在 Windows 上使用 PerfView 來檢視，但也可以直接在 Linux 上使用 PerfCollect 或 TraceCompass 來檢視。

使用 PerfCollect 檢視追蹤檔案

您可以直接使用perfcollect來查看所收集的追蹤。若要這樣做，請使用下列命令：

./perfcollect view sampleTrace.trace.zip

根據預設，這會使用 perf顯示應用程式的CPU追蹤。

若要查看透過 LTTng收集的事件，您可以傳入旗標 -viewer lttng 來查看個別事件：

./perfcollect view sampleTrace.trace.zip -viewer lttng

這會使用 babeltrace 檢視器來列印事件承載：

# [01:02:18.189217659] (+0.020132603) ubuntu-xenial DotNETRuntime:ExceptionThrown_V1: { cpu_id = 0 }, { ExceptionType = "System.Exception", ExceptionMessage = "An exception happened", ExceptionEIP = 139875671834775, ExceptionHRESULT = 2148734208, ExceptionFlags = 16, ClrInstanceID = 0 }
# [01:02:18.189250227] (+0.020165171) ubuntu-xenial DotNETRuntime:ExceptionCatchStart: { cpu_id = 0 }, { EntryEIP = 139873639728404, MethodID = 139873626968120, MethodName = "void [helloworld] helloworld.Program::Main(string[])", ClrInstanceID = 0 }

使用 PerfView 開啟追蹤檔案

若要查看 CPU 範例和事件的匯總檢視，您可以在 Windows 計算機上使用 PerfView 。

將 trace.zip 檔案從 Linux 複製到 Windows 電腦。
從 https://aka.ms/perfview下載 PerfView。
執行 PerfView.exe
```
PerfView.exe <path to trace.zip file>
```

PerfView 會根據追蹤檔案中包含的數據顯示支援的檢視清單。

針對 CPU 調查，請選擇 [CPU 堆疊]。
如需詳細的 GC 資訊，請選擇 GCStats。
針對每個進程/模組/方法 JIT 資訊，請選擇 [JITStats]。
如果沒有所需資訊的檢視，您可以嘗試在原始事件檢視中尋找事件。選擇 [事件]。

如需如何在 PerfView 中解譯檢視的詳細資訊，請參閱檢視本身的說明連結，或從 PerfView 的主視窗選擇 [說明使用者>指南]。

備註

透過 System.Diagnostics.Tracing.EventSource API 撰寫的事件（包括來自 Framework 的事件）將不會顯示在提供者名稱下。相反地，它們會被寫入為 EventSourceEvent 提供者下的 Microsoft-Windows-DotNETRuntime 事件，而且其負載會序列化為 JSON。

備註

如果您在方法名稱和呼叫堆疊中觀察到 [unknown] /memfd:doublemapper 框架，請在執行使用 perfcollect 進行追蹤的應用程式之前先設定 DOTNET_EnableWriteXorExecute=0。

使用 TraceCompass 開啟追蹤檔案

Eclipse TraceCompass 是另一個選項，可用來檢視追蹤。 TraceCompass 也適用於Linux機器，因此您不需要將追蹤移至 Windows 電腦。若要用來 TraceCompass 開啟追蹤檔案，您必須將檔案解壓縮。

unzip myTrace.trace.zip

perfcollect 會將其收集到的 LTTng 追蹤資料儲存為 CTF 檔案格式，並放置在 lttngTrace 的一個子目錄中。具體而言，CTF 檔案會位於看起來像 lttngTrace/auto-20201025-101230\ust\uid\1000\64-bit\的目錄中。

您可以在TraceCompass中開啟 CTF 追蹤檔案，選取File -> Open Trace並選取metadata檔案。

如需詳細資訊，請參閱 TraceCompass 檔。

取得原生運行時間的符號

您大部分時間都對自己的程式碼感興趣，依預設會 perfcollect 解析該程序代碼。有時候查看 .NET 動態鏈接庫內的活動（即最後一節的內容）是有用的，而有時候原生執行環境的動態鏈接庫中，例如 libcoreclr.so，所發生的事也同樣值得關注。 perfcollect 會在轉換其數據時解析這些符號，但前提是這些原生 DLL 的符號存在（且位於連結庫旁邊）。

有一個稱為 dotnet-symbol 的全域命令會執行這項作業。若要使用 dotnet-symbol 來取得原生運行時間符號：

安裝 dotnet-symbol：
```
dotnet tool install -g dotnet-symbol
```

下載符號。如果您安裝的 .NET Core 執行時間版本是 2.1.0，則執行這項作的命令如下：

mkdir mySymbols
dotnet symbol --symbols --output mySymbols  /usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0/lib*.so

將符號複製到正確的位置。
```
sudo cp mySymbols/* /usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0
```
如果無法這麼做，因為您沒有適當目錄的寫入許可權，您可以使用 perf buildid-cache 來新增符號。

在此之後，您應該在執行時 perfcollect取得原生 dll 的符號名稱。

在 Docker 容器中收集

如需如何在容器環境中使用 perfcollect 的詳細資訊，請參閱收集容器中的診斷。

深入瞭解集合選項

您可以使用指定下列選擇性旗標 perfcollect ，以更符合診斷需求。

收集特定時間內的資料

當您想要收集特定持續時間的追蹤時，您可以使用 -collectsec 選項，後面接著指定要收集的追蹤的總秒數。

收集 threadtime 記錄

使用 -threadtimeperfcollect 指定可讓您收集每個線程的CPU使用量數據。這可讓您分析每個線程花費CPU時間的位置。

收集管理記憶體和垃圾收集器效能的追蹤

下列選項可讓您特別從運行時間收集 GC 事件。

perfcollect collect -gccollectonly

僅收集最低限度的 GC 集合事件。這是最不詳細的 GC 事件收集配置檔，對目標應用程式的效能影響最低。此命令類似於 PerfView.exe /GCCollectOnly collect PerfView 中的命令。

perfcollect collect -gconly

使用 JIT、Loader 和 Exception 事件來收集更多詳細的 GC 收集事件。這會要求更詳細的事件（例如配置資訊和 GC 聯結資訊），而且會對目標應用程式的效能產生 -gccollectonly 比選項更大的影響。此命令類似於 PerfView.exe /GCOnly collect PerfView 中的命令。

perfcollect collect -gcwithheap

收集最詳細的 GC 收集事件，其也會追蹤堆積生存和移動。這會深入分析 GC 行為，但會產生高效能成本，因為每個 GC 可能需要兩倍以上的時間。建議您了解在生產環境中追蹤時使用此追蹤選項的效能影響。