.NET 記錄和追蹤

  • 發行項

檢測程式碼可產生記錄，以記錄下程式執行時所發生的有趣事件。 若要了解應用程式的行為，您可檢閱記錄。 記錄和追蹤都會封裝這項技術。 .NET 在其過往中累積了數個不同的記錄 API，本文會協助您了解可用的選項。

「記錄」和「追蹤」這兩個詞通常同義。 差別在於預計會一直收集記錄輸出，因此額外負荷應該較低。 追蹤通常更具侵入性，並從應用程式和 .NET 執行階段的更深層部分收集更多資訊。 其在診斷特定問題時使用，或在更深入的效能分析系統當中短時間自動使用。

追蹤一詞的另一個樞紐是分散式追蹤。 分散式追蹤會收集要求型系統的高階活動和計時資料，並跨服務相互關聯要求，以供檢視整個系統處理每個要求的方式。

記錄 API 的主要差別

結構化記錄

記錄 API 可以是結構化或非結構化形式：

  • 非結構化：記錄項目具有自由格式的文字內容，以供人類檢視。
  • 結構化：記錄項目具有妥善定義的結構描述，而且能以不同的二進位檔和文字格式進行編碼。 這些記錄會設計為可供機器轉譯和查詢，因此人類和自動化系統都能輕鬆地使用。

支援結構化記錄的 API 較適合用於非一般用途。 其提供更多功能、彈性和效能，但可用性有點不同。

組態

針對簡單的使用案例，您可以使用會直接將訊息寫入到主控台或檔案的 API。 但大部分的軟體專案都會發現，設定要記錄哪些記錄事件及其保存方式會很實用。 例如，在本機開發環境中執行時，您可以將純文字輸出至主控台，以方便閱讀。 然後，當應用程式部署至生產環境時，您可以改為將記錄儲存在專用資料庫或一組輪替檔案中。 具有優異設定選項的 API 會讓轉換過程變得簡單，設定選項較差的 API 則需要到處更新檢測程式碼才能進行變更。

接收

大部分的記錄 API 都允許將記錄訊息傳送至稱為接收的不同目的地。 某些 API 有大量預先建立的接收，某些 API 則只有一些接收。 如果沒有預先建立的接收，通常會有擴充性 API 可讓您撰寫自訂接收，不過這需要撰寫更多程式碼。

.NET 記錄 API

ILogger

在大部分情況下，無論是將記錄新增至現有專案還是建立新專案，ILogger 基礎結構都是理想的預設選擇。 ILogger 支援快速結構化記錄、彈性設定，以及一組常見的接收器，包括主控台 (這是您在執行 ASP.NET 應用程式時所看到的項目)。 此外，ILogger 介面也可以作為許多第三方記錄實作的外觀，以提供豐富的功能和擴充性。

ILogger 提供適用於 .NET 的 OpenTelemetry 實作記錄案例，可讓您將應用程式中的記錄輸出到各種 APM 系統，以進行進一步分析。

EventSource

EventSource 是使用結構化記錄功能的早期高效能追蹤 API。 其原本是設計來與 Windows 事件追蹤 (ETW) 整合的，但後來擴充為可支援 EventPipe 跨平台追蹤和 EventListener 以便自訂接收。 相較於 ILogger，EventSource 預先建立的記錄接收相對較少，而且沒有可透過不同設定檔來進行設定的內建支援。 如果您想要更嚴格地控制 ETW 或 EventPipe 整合，EventSource 非常適合，但如果只要進行一般用途的記錄，ILogger 會更有彈性且更容易使用。

追蹤

System.Diagnostics.Trace 和 System.Diagnostics.Debug 是 .NET 最早期的記錄 API。 這些類別有彈性的設定 API 和龐大的接收生態系統，但只支援非結構化記錄。 在 .NET Framework 上，您可以透過 app.config 檔案設定這些類別，但在 .NET Core 中，則沒有內建的檔案型設定機制。 在偵錯工具之下執行時，其通常用於為開發人員產生診斷輸出。 為了提供回溯相容性，.NET 小組會繼續支援這些 API，但不會增加任何新功能。 對於已經使用這些 API 的應用程式來說，這些 API 是不錯的選擇。 但對於尚未決定使用哪個記錄 API 的較新應用程式來說，ILogger 可以提供更好的功能。

特製化記錄 API

主控台

System.Console 類別有 Write 和 WriteLine 方法可用於簡單的記錄案例。 這些 API 很容易就能開始使用，但其解決方案的彈性不會像一般用途記錄 API 那麼好。 主控台只允許非結構化記錄，而且不支援組態設定，因此無法選取要啟用哪些記錄訊息，也無法將目標重定為不同的接收。 搭配主控台接收使用 ILogger 或追蹤 API 不需要另外花費太多心力，並且可以讓記錄保持可供設定的狀態。

DiagnosticSource

System.Diagnostics.DiagnosticSource 適用於會在處理序內同步分析記錄訊息，而不是將記錄訊息序列化至任何儲存體的記錄功能。 這可讓來源和接聽程式以訊息形式交換任意 .NET 物件，然而大部分的記錄 API 都需要可序列化的記錄事件。 如果能有效率地實作接聽程式，這項技術也會非常快速，能在數十奈秒內處理記錄事件。 使用這些 API 的工具往往更像是內含式分析工具，不過 API 在這裡不會施加任何條件約束。

EventLog

System.Diagnostics.EventLog 是僅限 Windows 的 API，會將訊息寫入到 Windows EventLog。 在許多情況下，當您在 Windows 上執行時，使用 ILogger 搭配選擇性的 EventLog 接收，可能會提供類似的功能，卻不需要將應用程式緊密結合到 Windows OS。