.NET 的可觀察性與 OpenTelemetry

執行應用程式時，您想要知道應用程式執行程度，並在潛在問題變得更大之前偵測到這些問題。 若要這樣做，您可以發出遙測資料 (例如來自應用程式的記錄或計量)，然後監視並分析該資料。

何謂可檢視性？

分散式系統內容中的可檢視性是監視並分析每個元件狀態相關遙測資料的能力，以便能夠觀察效能中的變更，以及診斷這些變更為何發生的原因。 不同於偵錯，這是侵入性的動作，而且可能會影響應用程式的作業，因此可檢視性旨在主要作業執行時呈現透明狀態，而且對效能的影響小到足以持續使用。

可檢視性通常是使用下列項目的組合來完成：

• 記錄，記錄個別作業，例如傳入要求、特定元件中的失敗，或下訂單。
• 指標，這是用來測量的計數器和指標，例如已完成的請求數量、活動請求、已售出的小工具，或請求延遲的直方圖。
• 分散式追蹤，可追蹤分散式系統中元件之間的要求和活動，以便查看花費時間並追蹤特定失敗的位置。

一起，記錄、計量和分散式追蹤有時稱為 可觀察性的三大要素。

每個支柱可能包含來自下列項目的遙測資料：

• .NET 執行階段，例如垃圾回收器或 JIT 編譯器。
• 程式庫，例如來自 Kestrel (ASP.NET Ｗeb 伺服器) 和 HttpClient 的程式庫。
• 您的程式碼發出的特定於應用程式的遙測。

.NET 中的可檢視性方法

有幾種不同的方式可在 .NET 應用程式中實現可檢視性：

• 在程式碼中明確參考並使用 OpenTelemetry 之類的程式庫。 如果您有權存取原始程式碼，而且可以重建應用程式，則這是最強大且可設定的機制。
• 使用 EventPipe 的跨進程方式。 dotnet-monitor 之類的工具可以接聽記錄和計量，然後處理它們，而不會影響任何程式碼。
• 使用啟動勾點，組件可以插入至流程，然後從中收集檢測資料。 此方法的範例是 OpenTelemetry .NET Automatic Instrumentation。

什麼是 OpenTelemetry？

OpenTelemetry (OTel) 是一種跨平台開放式標準，用於收集和發出遙測資料。 OpenTelemetry 包括：

• 程式庫在程式碼執行時用來記錄遙測資料的 API。
• API 是應用程式開發人員用來設定的工具，可決定所記錄資料中將被跨網路傳送的部分，傳送的目的地，並設定如何進行篩選、緩衝、擴展和轉換。
• 語意慣例提供遙測資料的命名和內容指引。 對於產生遙測資料的應用程式和接收資料的工具而言，就不同種類資料的含義以及哪些類型的資料有用達成一致，這很重要，如此工具才能提供有效的分析。
• 匯出器的介面。 匯出工具是外掛程式，可讓遙測資料以特定格式傳輸至不同的遙測後端。
• OTLP 有線通訊協定是廠商中性網路通訊協定選項，用於傳輸遙測資料。 有些工具和廠商除了其可能具有的預存專屬通訊協定之外，還支援此通訊協定。

使用 OTel 可讓您使用廣泛不同的 APM 系統，包括開放原始碼系統，例如 Prometheus 和 Grafana、Azure 監視器 - Azure 中的 Microsoft APM 產品，或與 OpenTelemetry 合作的許多 APM 廠商所提供的 APM 產品。

大部分語言和平台都有 OpenTelemetry 實作，包括 .NET。

OpenTelemetry 的 .NET 實作

.NET OpenTelemetry 實作與其他平台稍有不同，因為 .NET 會在架構中提供記錄、計量和活動 API。 這表示 OTel 不需要提供 API 供程式庫作者使用。 .NET OTel 實作會使用這些平台 API 進行檢測：

• Microsoft.Extensions.Logging.ILogger<TCategoryName> 用於記錄
• System.Diagnostics.Metrics.Meter 用於計量
• System.Diagnostics.ActivitySource 和 System.Diagnostics.Activity 用於分散式追蹤

OTel 開始發揮作用之處在於其會從這些 API 和其他來源收集遙測資料 (透過檢測程式庫)，然後將這些資料們匯出至應用程式效能監視 (APM) 系統以進行儲存和分析。 OTel 做為業界標準帶來的好處是通用的收集機制、遙測資料的通用結構描述和語意，以及 APM 如何與 OTel 整合的 API。 使用 OTel 表示應用程式不需要使用 APM 特定的 API 或資料結構；其會針對 OTel 標準運作。 APM 可以實作 APM 特定的匯出工具元件或使用 OTLP，這是新的有線標準，用於將遙測資料匯出至 APM 系統。

OpenTelemetry 套件

.NET 中的 OpenTelemetry 會實作為一系列的 NuGet 套件，形成數個類別：

• 核心 API
• 檢測 - 這些套件會從執行階段和通用程式庫收集檢測資料。
• 匯出工具 - 這些工具會與 APM 系統互動，例如 Prometheus、Jaeger 和 OTLP。

下表描述主要套件。

範例

本主題將繼續提供幾個使用 OpenTelemetry 的 .NET 範例逐步解說：

• 使用 OTLP 和 Aspire 儀表板
• 範例：使用 OpenTelemetry 搭配 Azure 監視器和 Application Insights
• 範例：搭配 Prometheus、Grafana 和 Jaeger 使用 OpenTelemetry

OpenTelemetry 中的 Aspire

Aspire 是一組擴充 .NET，方便建立與使用分散式應用程式。 使用 Aspire 的好處之一是遙測功能內置，使用 OpenTelemetry 函式庫支援 .NET。 預設專案範本 Aspire 包含一個 ServiceDefaults 專案，其中一部分是用來設定和設定 OTel。 服務預設專案由解決方案中的 Aspire 每個服務引用並初始化。

服務預設值專案範本包含 OTel SDK、ASP.NET、HttpClient 和 Runtime Instrumentation 套件，這些都在 Extensions.cs 檔案中設定。 匯出遙測時，預設 Aspire 包含 OTLP 匯出器，使其能透過 Aspire 儀表板提供遙測視覺化。

儀表板 Aspire 設計用來將遙測觀察帶入本地除錯週期，讓開發者不僅能確保應用程式產生遙測數據，還能利用這些遙測數據在本地診斷這些應用程式。 能夠觀察服務之間的呼叫，在除錯階段與在生產環境中同樣有助益。 當您從Visual Studio中按Aspire啟動專案，或是啟動AppHostdotnet run專案時，儀表板會自動啟動。

如需更多有關 Aspire 的詳情，請參閱：

• Aspire 概述
• 遙測 Aspire
• Aspire 儀表板

重用服務預設專案，無需 Aspire Orchestration 協調

設定 OTel 給 ASP.NET 專案最簡單的方法可能是使用 Aspire Service Defaults 專案，即使不使用 Aspire 的其他部分，例如 AppHost 來做編排。 服務預設值專案可透過Visual Studio或 dotnet new作為專案範本。 它會配置 OTel 並設置 OTLP 匯出器。 然後 ，您可以使用 OTel 環境變數 來設定 OTLP 端點以傳送遙測至 ，並提供應用程式的資源屬性。

在外部使用 Aspire 的步驟如下：

• 使用 Visual Studio 中的新增專案，將 ServiceDefaults 專案新增至解決方案，或使用 dotnet new aspire-servicedefaults --output ServiceDefaults。
• 從 ASP.NET 應用程式參考 ServiceDefaults 專案。 在 Visual Studio 中，使用 [新增>專案參考] ，然後選取 ServiceDefaults 專案。
• 呼叫其 OpenTelemetry 安裝程式函式，作為應用程式建立器初始化的一部分。

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

如果需要，服務預設值可以透過AddServiceDefaults()或特定功能來設定以下附加功能：

• 健康檢查與 /health 和 /alive 端點。
• 服務發現，如果缺少其他的 Aspire，將不會運作。
• 為 HttpClient 設定復原能力，當發生失敗時會重試請求。