EventPipe

EventPipe 是執行階段元件，可用於收集追蹤資料，類似於 ETW 或 perf_events。 EventPipe 的目標是允許 .NET 開發人員輕鬆追蹤其 .NET 應用程式，而不必依賴平台特定的高權限元件，例如 ETW 或 perf_events。

EventPipe 是許多診斷工具背後的機制，可用於取用執行階段所發出的事件，以及以 EventSource 撰寫的自訂事件。

本文是 EventPipe 的大略概觀。 其描述使用 EventPipe 的時機和方式，以及如何將其設定為最符合您的需求。

EventPipe 基本概念

EventPipe 會彙總執行階段元件所發出的事件，例如 Just-In-Time 編譯器或記憶體回收行程，以及從程式庫和使用者程式碼中 EventSource 執行個體所撰寫的事件。

事件接著會以 .nettrace 檔案格式序列化，並可直接寫入檔案，或透過診斷連接埠串流處理，以供在處理序外部取用。

若要深入了解 EventPipe 序列化格式，請參閱 EventPipe 格式文件 (英文)。

EventPipe 與 ETW/perf_events

EventPipe 是 .NET 執行階段的一部分，設計目的是在 .NET Core 支援的所有平台上以相同的方式運作。 這可讓以 EventPipe 為基礎的追蹤工具，例如 dotnet-counters、dotnet-gcdump 和 dotnet-trace，在平台之間順暢地運作。

但因為 EventPipe 是執行階段內建元件，因此其範圍僅限於 Managed 程式碼和執行階段本身。 EventPipe 事件僅包含具有受管理程式碼框架資訊的堆疊追蹤。 如果您想要從其他未受管理使用者模式程式庫產生的事件、原生程式碼的 CPU 取樣或核心事件，您應該使用 OS 特定的追蹤工具，例如 ETW 或 perf_events。 在 Linux 上，PerfCollect 工具可協助自動使用 perf_events 和 LTTng。

EventPipe 和 ETW/perf_events 之間的另一個主要差異是管理員/根權限需求。 如果要使用 ETW 或 perf_events 追蹤應用程式，您必須是管理員/根。 只要追蹤程式 (例如 dotnet-trace) 在執行中，您就能以啟動應用程式的相同使用者身分，利用 EventPipe 來追蹤應用程式。

下表是 EventPipe 和 ETW/perf_events 之間差異的摘要。

功能	EventPipe	ETW	perf_events
跨平台	Yes	否 (僅限 Windows 上)	否 (僅限受支援的 Linux 散發版本上)
需要系統管理員/根權限	No	.是	Yes
可以取得 OS/核心事件	No	.是	Yes
可以解析原生呼叫堆疊	No	.是	Yes

使用 EventPipe 追蹤您的 .NET 應用程式

您可以使用 EventPipe，以多種方式追蹤您的 .NET 應用程式：

• 使用其中一個以 EventPipe 為基礎所建置的診斷工具。

• 使用 Microsoft.Diagnostics.NETCore.Client 程式庫，撰寫您自己的工具，設定及啟動 EventPipe 工作階段。

• 使用環境變數啟動 EventPipe。

產生包含您 EventPipe 事件的 nettrace 檔案之後，可以在 PerfView 或 Visual Studio 中，檢視該檔案。 在非 Windows 平台上，可以使用 dotnet-trace convert 命令，將檔案 nettrace 轉換為 speedscope 或 Chromium 追蹤格式，並使用 speedscope 或 Chrome DevTools 加以檢視。

您也可以使用 TraceEvent，以程式設計方式分析 EventPipe 追蹤。

使用 EventPipe 的工具

這是使用 EventPipe 追蹤應用程式最簡單的方式。 若要深入了解如何使用這些工具，請參閱每項工具的文件。

• dotnet-counters，您可用於監視和收集 .NET 執行階段和核心程式庫所發出的各種計量，以及您可以撰寫的自訂計量。

• dotnet-gcdump，您可用於收集即時處理序的 GC 堆積傾印，以分析應用程式的受控堆積。

• dotnet-trace，您可用於收集應用程式的追蹤，以分析效能。

使用環境變數的追蹤

使用 EventPipe 的慣用機制，是使用 dotnet-trace 或 Microsoft.Diagnostics.NETCore.Client 程式庫。

但您可以使用下列環境變數，在應用程式上設定 EventPipe 工作階段，並讓它將追蹤直接寫入檔案。 若要停止追蹤，請結束該應用程式。

• DOTNET_EnableEventPipe：將此設定為 1，會啟動直接寫入檔案的 EventPipe 工作階段。 預設值是 0。

• DOTNET_EventPipeOutputPath：當輸出 EventPipe 追蹤檔設定為透過 DOTNET_EnableEventPipe 執行時，進入該追蹤檔的路徑。 預設值為 trace.nettrace，其建立位置和應用程式執行所在的目錄相同。

  注意

  從 .NET 6 開始，DOTNET_EventPipeOutputPath 中字串 {pid} 的執行個體，會取代為所追蹤之處理序的處理序識別碼。

• DOTNET_EventPipeCircularMB：十六進位值，代表 EventPipe 內部緩衝區大小 (以 MB 為單位)。 只有當 EventPipe 設定為透過 DOTNET_EnableEventPipe 執行時，才會使用此組態值。 預設緩衝區大小為 1024MB，也就是轉譯為此環境變數會設定為 400，因為 0x400 == 1024。

  注意

  如果目標處理序太頻繁地寫入事件，可能會溢位此緩衝區，而且可能會卸載某些事件。 如果卸載了太多事件，請加大緩衝區大小，以查看卸載的事件數目是否減少。 如果卸載的事件數目沒有隨著較大的緩衝區大小而減少，可能是因為讀取器緩慢，而無法清除目標處理序的緩衝區。

• DOTNET_EventPipeProcNumbers：將此設定為 1，啟用擷取 EventPipe 事件標頭中的處理器編號。 預設值是 0。

• DOTNET_EventPipeConfig：設定在利用 DOTNET_EnableEventPipe 啟動 EventPipe 工作階段時，EventPipe 工作階段的組態。 語法如下所示：

  <provider>:<keyword>:<level>

  您也可用逗號串連多個提供者，來指定這些提供者：

  <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

  如果未設定此環境變數，但已用 DOTNET_EnableEventPipe 啟用了 EventPipe，則會藉由使用下列關鍵字和層級來啟用下列提供者，開始追蹤：

  • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
  • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
  • Microsoft-DotNETCore-SampleProfiler:0:5

  如果要深入了解 .NET 中的某些已知提供者，請參閱已知的事件提供者 (部分機器翻譯)。

注意

.NET 6 會針對設定 .NET Runtime 行為的環境變數，透過前置詞 DOTNET_ (而非 COMPlus_) 進行標準化。 不過，COMPlus_ 前置詞將繼續運作。 如果使用舊版的 .NET 執行階段，則您仍應對環境變數使用 COMPlus_ 前置詞。