事件
使用適用於 .NET 的 Azure SDK 進行記錄
適用於 .NET 的 Azure SDK 用戶端程式庫具有記錄用戶端程式庫作業的能力。 此記錄可讓您監視用戶端程式庫對 Azure 服務提出的 I/O 要求和回應。 一般而言,記錄用於偵錯或診斷通訊問題。 本文將說明如何以下列方法,使用適用於 .NET 的 Azure SDK 啟用記錄:
重要
本文適用於使用最新版本適用於 .NET 的 Azure SDK 用戶端程式庫。 若要查看程式庫是否受到支援,請參閱 Azure SDK 最新版本的清單。 如果您的應用程式使用較舊版本的 Azure SDK 用戶端程式庫,請參閱適用的服務文件中的特定指示。
SDK 會記錄每個 HTTP 要求和回應、清理參數查詢和標頭值,以移除個人資料。
HTTP 要求記錄的輸入內容:
- 唯一識別碼
- HTTP 方法
- URI
- 傳出要求標頭
HTTP 回應記錄的輸入內容:
- I/O 作業的持續時間 (經過時間)
- 要求識別碼
- HTTP 狀態碼
- HTTP 原因說明
- 回應標頭
- 適用時亦提供錯誤資訊
HTTP 要求和回應內容:
視
Content-Type
標頭而定,內容資料流為文字或位元組。注意
預設會停用內容記錄。 若要啟用,請參閱記錄 HTTP 要求和回應主體。 此功能僅適用於使用 HTTP 與 Azure 服務通訊的程式庫。 基於替代通訊協定 (例如 AMQP) 的程式庫不支援內容記錄。 不受支援的範例包括 Azure 服務的程式庫,例如事件中樞、服務匯流排和 Web PubSub。
事件記錄檔通常是在下列三個層級的其中一個輸出:
- 要求和回應事件的資訊
- 錯誤警告
- 詳細訊息和內容記錄的詳細資訊
適用於 .NET 的 Azure SDK 用戶端程式庫,會透過 System.Diagnostics.Tracing.EventSource 類別將事件記錄到 Windows 事件追蹤 (ETW),通常為 .NET 類別。 事件來源可讓您在應用程式中使用結構化記錄,使效能負擔降至最低。 若要取得事件記錄檔的存取權,您必須註冊事件接聽程式。
SDK 包含 Azure.Core.Diagnostics.AzureEventSourceListener 類別,其中包含兩個靜態方法,可簡化 .NET 應用程式的完整記錄:CreateConsoleLogger
和 CreateTraceLogger
。 每個方法都接受以選擇性參數來指定記錄層級。 如果未提供參數,則會使用 Informational
的預設記錄層級。
適用 .NET 的 Azure SDK 用戶端程式庫有一核心原則,即追求即時簡化檢視完整記錄的能力。 CreateConsoleLogger
方法可讓您使用單行程式碼將記錄傳送至主控台視窗:
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateConsoleLogger();
如果您實作追蹤接聽程式,即可使用 CreateTraceLogger
方法來記錄至標準 .NET 事件追蹤機制 (System.Diagnostics.Tracing)。 如需 .NET 中事件追蹤的詳細資訊,請參閱追蹤接聽程式。
此範例會指定詳細資訊的記錄層級:
using AzureEventSourceListener listener =
AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);
如上所述,您必須註冊事件接聽程式,以接收來自適用於 .NET 的 Azure SDK 記錄訊息。 如果您不希望使用以上任一簡化方法來實作完整記錄,那麼您可以建構 AzureEventSourceListener
類別的執行個體。 傳遞您撰寫的回呼方法執行個體。 不論為何必須處理記錄訊息,此方法都可收到您可處理的記錄訊息。 此外,在您建構執行個體時,可以指定要包含的記錄層級。
下列範例會建立事件接聽程式,並可使用自訂訊息記錄到主控台。 系統會依據詳細資料的等級,將記錄篩選至 Azure Core 用戶端程式庫發出的事件。 Azure Core 程式庫使用的事件來源名稱 Azure-Core
。
using Azure.Core.Diagnostics;
using System.Diagnostics.Tracing;
// code omitted for brevity
using var listener = new AzureEventSourceListener((e, message) =>
{
// Only log messages from "Azure-Core" event source
if (e.EventSource.Name == "Azure-Core")
{
Console.WriteLine($"{DateTime.Now} {message}");
}
},
level: EventLevel.Verbose);
AzureEventSourceLogForwarder 服務可讓您使用標準 ASP.NET Core 記錄設定來進行記錄。 服務會將記錄訊息從 Azure SDK 事件來源轉送到 ILoggerFactory。
下表描述適用於 .NET 的 Azure SDK 如何描述 EventLevel
對應至 ASP.NET CoreLogLevel
。
Azure SDK EventLevel |
ASP.NET Core LogLevel |
---|---|
Critical |
Critical |
Error |
Error |
Informational |
Information |
Warning |
Warning |
Verbose |
Debug |
LogAlways |
Information |
使用 Azure 服務匯流排程式庫作為範例,完成下列步驟:
安裝 Microsoft.Extensions.Azure NuGet 套件:
dotnet add package Microsoft.Extensions.Azure
在 Program.cs 中,透過呼叫 AddAzureClients 擴充方法來註冊 Azure SDK 程式庫的用戶端:
using Azure.Identity; using Microsoft.Extensions.Azure; // code omitted for brevity builder.Services.AddAzureClients(azureBuilder => { azureBuilder.AddServiceBusClient( builder.Configuration.GetConnectionString("ServiceBus")); azureBuilder.UseCredential(new DefaultAzureCredential()); });
在上述範例中,
AddAzureClients
方法可進行下列操作:- 使用相依性插入 (DI) 容器註冊下列物件:
- 記錄轉寄站服務
- Azure 服務匯流排用戶端
- 設定要用於所有已註冊用戶端的預設權杖認證。
- 使用相依性插入 (DI) 容器註冊下列物件:
在 appsettings.json 中,變更服務匯流排程式庫的預設記錄層級。 例如,藉由設定
Debug
金鑰,將其切換為Logging:LogLevel:Azure.Messaging.ServiceBus
,如下所示:{ "ConnectionStrings": { "ServiceBus": "<connection_string>" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AllowedHosts": "*" }
由於
Logging:LogLevel:Azure.Messaging.ServiceBus
金鑰已設定為Debug
,因此會記錄到EventLevel.Verbose
的服務匯流排用戶端事件。
在某些情況下,無法且不必使用 DI 容器註冊 Azure SDK 程式庫的用戶端:
- Azure SDK 程式庫不包含可在 DI 容器中註冊用戶端的
IServiceCollection
擴充方法。 - 您的應用程式會使用依賴其他 Azure SDK 程式庫的 Azure 延伸模組程式庫。 這類 Azure 延伸模組程式庫的範例如下:
在這些案例中,請完成下列步驟:
安裝 Microsoft.Extensions.Azure NuGet 套件:
dotnet add package Microsoft.Extensions.Azure
在 Program.cs 中,將記錄轉寄站服務註冊為 DI 容器中的單一服務:
using Azure.Identity; using Microsoft.AspNetCore.DataProtection; using Microsoft.Extensions.Azure; using Microsoft.Extensions.DependencyInjection.Extensions; var builder = WebApplication.CreateBuilder(args); builder.Services.AddRazorPages(); builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>(); builder.Services.AddDataProtection() .PersistKeysToAzureBlobStorage("<connection_string>", "<container_name>", "keys.xml") .ProtectKeysWithAzureKeyVault(new Uri("<uri>"), new DefaultAzureCredential());
從 DI 容器擷取記錄轉寄站服務,並叫用其 Start 方法。 例如,在 ASP.NET Core Razor Pages 頁面模型類別中,使用建構函式插入:
using Microsoft.AspNetCore.Mvc.RazorPages; using Microsoft.Extensions.Azure; public class IndexModel : PageModel { public IndexModel(AzureEventSourceLogForwarder logForwarder) => logForwarder.Start();
在 appsettings.json 中,變更 Azure Core 程式庫的預設記錄層級。 例如,藉由設定
Logging:LogLevel:Azure.Core
金鑰,將其切換為Debug
,如下所示:{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Core": "Debug" } }, "AllowedHosts": "*" }
由於
Logging:LogLevel:Azure.Core
金鑰設定為Debug
,因此將記錄到達EventLevel.Verbose
的 Azure Core 程式庫事件。
如需詳細資料,請參閱 .NET Core 與 ASP.NET Core 中的記錄。
Azure 監視器 OpenTelemetry 散發版本 (從 1.2.0
版開始) 支援擷取來自 Azure 用戶端程式庫的記錄。 您可以使用「.NET Core 和 ASP.NET Core 中的記錄」中所討論的任何設定選項來控制記錄。
使用 Azure 服務匯流排程式庫作為範例,完成下列步驟:
安裝 Azure.Monitor.OpenTelemetry.AspNetCore NuGet 套件:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
建立或註冊程式庫的用戶端。 此散發版本支援這兩種情況。
await using var client = new ServiceBusClient("<connection_string>");
在 appsettings.json 中,變更服務匯流排程式庫的預設記錄層級。 例如,藉由設定
Debug
金鑰,將其切換為Logging:LogLevel:Azure.Messaging.ServiceBus
,如下所示:{ "ConnectionStrings": { "ServiceBus": "<connection_string>" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning", "Azure.Messaging.ServiceBus": "Debug" } }, "AllowedHosts": "*" }
由於
Logging:LogLevel:Azure.Messaging.ServiceBus
金鑰已設定為Debug
,因此會記錄到EventLevel.Verbose
的服務匯流排用戶端事件。
注意
此功能僅適用於使用 HTTP 與 Azure 服務通訊的程式庫。 基於替代通訊協定 (例如 AMQP) 的程式庫不支援內容記錄。 不受支援的範例包括 Azure 服務的程式庫,例如事件中樞、服務匯流排和 Web PubSub。
疑難排解用戶端程式庫內的非預期行為時,檢查下列項目很有幫助:
- 傳送至基礎 Azure 服務 REST API 的 HTTP 要求本文。
- 從 Azure 服務的 REST API 收到的 HTTP 回應本文。
預設會停用上述內容的記錄。 若要啟用 HTTP 要求和回應主體的記錄,請完成下列步驟:
將用戶端選項物件的 IsLoggingContentEnabled 屬性設為
true
,並將選項物件傳遞給用戶端的建構函式。 例如,若要記錄 Azure Key Vault 秘密庫的 HTTP 要求和回應:var clientOptions = new SecretClientOptions { Diagnostics = { IsLoggingContentEnabled = true, } }; var client = new SecretClient( new Uri("https://<keyvaultname>.vault.azure.net/"), new DefaultAzureCredential(), clientOptions);
使用慣用的記錄方法,搭配詳細資訊/偵錯或更新版本的事件/記錄層級。 如需特定指示,請在下表中找到您的方法。
方法 指示 使用內建方法啟用記錄 傳遞 EventLevel.Verbose
或EventLevel.LogAlways
至AzureEventSourceListener.CreateConsoleLogger
或AzureEventSourceListener.CreateTraceLogger
設定自訂記錄 將 AzureEventSourceListener
類別的level
建構函式參數設定為EventLevel.Verbose
或EventLevel.LogAlways
對應至 ASP.NET Core 記錄 將 "Azure.Core": "Debug"
新增至 appsettings.json
- 在 Azure App Service 中針對應用程式啟用診斷記錄
- 請檢閱Azure 安全性記錄和稽核選項
- 了解如何使用 Azure 平台記錄
- 深入了解 .NET 記錄和追蹤
其他資源
訓練