OpenTelemetry 的 .NET 可檢視性
執行應用程式時，您想要知道應用程式執行程度，並在潛在問題變得更大之前偵測到這些問題。 若要這樣做，您可以發出遙測資料 (例如來自應用程式的記錄或計量)，然後監視並分析該資料。
何謂可檢視性？
分散式系統內容中的可檢視性是監視並分析每個元件狀態相關遙測資料的能力，以便能夠觀察效能中的變更，以及診斷這些變更為何發生的原因。 不同於偵錯，這是侵入性的動作，而且可能會影響應用程式的作業，因此可檢視性旨在主要作業執行時呈現透明狀態，而且對效能的影響小到足以持續使用。
可檢視性通常是使用下列項目的組合來完成：
- 記錄，記錄個別作業，例如傳入要求、特定元件中的失敗，或下訂單。
- 計量，這是測量計數器和量測計，例如已完成的要求數目、作用中要求、已售出的小工具，或要求延遲的直方圖。
- 分散式追蹤，可追蹤分散式系統中元件之間的要求和活動，以便查看花費時間並追蹤特定失敗的位置。
一起，記錄、計量和分散式追蹤有時稱為 可觀察性的三大要素。
每個支柱可能包含來自下列項目的遙測資料：
- .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 套件，形成數個類別：
- Core API
- 檢測 - 這些套件會從執行階段和通用程式庫收集檢測資料。
- 匯出工具 - 這些工具會與 APM 系統互動，例如 Prometheus、Jaeger 和 OTLP。
下表描述主要套件。
| 封裝名稱 | 描述 |
|---|---|
| OpenTelemetry | 提供核心 OTEL 功能的主要程式庫 |
| OpenTelemetry.Instrumentation.AspNetCore | 針對 ASP.NET Core 和 Kestrel 的檢測 |
| OpenTelemetry.Instrumentation.GrpcNetClient | 供 gRPC 用戶端用於追蹤輸出 gRPC 呼叫的檢測 |
| OpenTelemetry.Instrumentation.Http | 供 HttpClient 和 HttpWebRequest 追蹤輸出 HTTP 呼叫的檢測 |
| OpenTelemetry.Instrumentation.SqlClient | SqlClient 用來追蹤資料庫作業的檢測 |
| OpenTelemetry.Exporter.Console | 主控台的匯出工具，通常用來診斷正在匯出的遙測資料 |
| OpenTelemetry.Exporter.OpenTelemetryProtocol | 使用 OTLP 通訊協定的匯出工具 |
| OpenTelemetry.Exporter.Prometheus.AspNetCore | 使用 ASP.NET Core 端點實作 Prometheus 的匯出工具 |
| OpenTelemetry.Exporter.Zipkin | 用於 Zipkin 追蹤的匯出工具 |
範例
本主題會繼續進行幾個在 .NET 中使用 OpenTelemetry 的範例逐步解說：
- 範例：使用 OTLP 和獨立 Aspire 儀錶板
- 範例：搭配 Azure 監視器和 Application Insights 使用 OpenTelemetry
- 範例：搭配 Prometheus、Grafana 和 Jaeger 使用 OpenTelemetry
.NET Aspire 中的 OpenTelemetry
.NET Aspire 是 .NET 的一組延伸模組，可讓您輕鬆地建立及使用分散式應用程式。 使用 .NET Aspire 的優點之一，就是使用適用於 .NET 的 OpenTelemetry 連結庫來內建遙測。 .NET Aspire 的預設專案範本包含專案，其中一 ServiceDefaults 部分是安裝和設定 OTel。 服務預設專案是由 .NET Aspire 解決方案中的每個服務所參考和初始化。
服務預設值專案範本包含 OTel SDK、ASP.NET、HttpClient 和 Runtime Instrumentation 套件，以及檔案中設定的專案 Extensions.cs 。 若要匯出遙測 .NET Aspire，預設會包含OTLP匯出工具，以便使用Aspire儀錶板提供遙測視覺效果。
Aspire 儀錶板的設計目的是將遙測觀察帶入本機偵錯週期，這可讓開發人員不僅確保應用程式正在產生遙測，而且使用該遙測在本機診斷這些應用程式。 能夠觀察服務之間的呼叫，在偵錯階段與生產環境一樣有用。 當您從 Visual Studio 或dotnet runAppHost專案 F5 AppHost 專案時，會自動啟動 .NET Aspire 儀錶板。
如需 .NET Aspire 的詳細資訊，請參閱：
不使用 .NET Aspire 協調流程重複使用服務預設值專案
設定 ASP.NET 專案的 OTel 最簡單的方式可能是使用 Aspire Service Defaults 專案，即使不使用其他 .NET Aspire 專案，例如 AppHost 來進行協調流程。 服務預設值專案可透過Visual Studio或 dotnet new作為專案範本。 它會設定 OTel 並設定 OTLP 匯出工具。 然後 ，您可以使用 OTel 環境變數 來設定 OTLP 端點以傳送遙測至 ，並提供應用程式的資源屬性。
在 .NET Aspire 外部使用 ServiceDefault 的步驟 如下：
- 使用 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端點進行健康情況檢查 - 服務探索，如果沒有 .NET Aspire 的其餘部分，服務探索將會是無作業
- 設定 HttpClient 的復原能力，以在失敗時重試要求
