使用適用於 .NET 的 Azure SDK 進行日誌記錄

適用於 .NET 的 Azure SDK 用戶端庫具備記錄用戶端庫作業的能力。 此記錄可讓您監視用戶端連結庫對 Azure 服務進行 I/O 要求和回應。 一般而言，記錄是用來偵錯或診斷通訊問題。 本文說明使用適用於 .NET 的 Azure SDK 來啟用記錄的下列方法：

• 使用內建方法啟用日誌記錄
• 設定自訂記錄
• 映射到 ASP.NET Core 記錄

這很重要

本文適用於使用最新版 Azure SDK for .NET 的用戶端連結庫。 若要查看連結庫是否受到支援，請參閱 Azure SDK 最新版本的清單。 如果您的應用程式使用舊版的 Azure SDK 用戶端連結庫，請參閱適用的服務檔中的特定指示。

記錄資訊

SDK 會記錄每個 HTTP 要求和回應、清理參數查詢和標頭值，以移除個人資料。

HTTP 要求記錄條目：

• 唯一識別碼
• HTTP 方法
• URI
• 傳出請求標頭欄

HTTP 回應日誌條目：

• I/O 作業的持續時間（經過時間）
• 請求編號
• HTTP 狀態代碼
• HTTP 原因片語
• 回應標頭
• 適用時的錯誤資訊

HTTP 要求和回應內容：

• 根據標頭 Content-Type，內容數據流可以是文字或位元組。

  備註

  預設會停用內容記錄。 若要啟用，請參閱 記錄 HTTP 要求和響應主體。 此功能僅適用於使用 HTTP 透過與 Azure 服務進行通訊的程式庫。 使用替代通訊協議的函式庫，例如AMQP，不支援內容日誌記錄。 不支援的範例包括 Azure 服務的程式庫，例如事件中樞、服務匯流排和 Web PubSub。

事件記錄檔通常是在下列三個層級的其中一個輸出：

• 有關請求和回應事件的資訊
• 錯誤警告
• 冗長模式可記錄詳細訊息和內容資料

使用內建方法啟用記錄

Azure SDK for .NET 的用戶端庫會透過 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

對應至 ASP.NET Core 日誌

服務 AzureEventSourceLogForwarder 可讓您使用標準 ASP.NET 核心記錄組態進行記錄。 服務會將記錄訊息從 Azure SDK 事件來源轉送至 ILoggerFactory。

下表顯示適用於 .NET 的 Azure SDK 如何對應到 ASP.NET Core。

Azure SDK EventLevel	ASP.NET 核心 LogLevel
Critical	Critical
Error	Error
Informational	Information
Warning	Warning
Verbose	Debug
LogAlways	Information

使用客戶端註冊進行日誌記錄

使用 Azure 服務總線連結庫作為範例，完成下列步驟：

1. 安裝 Microsoft.Extensions.Azure NuGet 套件：

   dotnet add package Microsoft.Extensions.Azure
   

2. 在 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"));
   });
   

   在上述範例中，方法 AddAzureClients：

   • 使用相依性插入 （DI） 容器註冊下列物件：
     • 記錄轉發服務
     • Azure 服務總線用戶端
   • 除非明確設定不同的憑證，否則驗證會自動使用 DefaultAzureCredential。

3. 在 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 軟體開發套件庫不包含 IServiceCollection 擴充方法，無法利用 DI 容器註冊客戶端。
• 您的應用程式會使用相依於其他 Azure SDK 連結庫的 Azure 擴充功能連結庫。 這類 Azure 擴充連結庫的範例包括：
  • DataProtection 的 Azure Key Vault 密鑰加密器
  • Azure Key Vault 秘密設定提供者
  • DataProtection 的 Azure Blob 記憶體密鑰存放區

在這些案例中，請完成下列步驟：

1. 安裝 Microsoft.Extensions.Azure NuGet 套件：

   dotnet add package Microsoft.Extensions.Azure
   

2. 在 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());
   

3. 從 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();
   

4. 在 appsettings.json中，變更 Azure Core 連結庫的默認記錄層級。 例如，藉由設定Debug機碼，將它切換為 Logging:LogLevel:Azure.Core ，如下所示：

   {
     "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.Monitor.OpenTelemetry.AspNetCore 進行記錄

從版本開始，1.2.0支援擷取來自 Azure 客戶端函式庫的日誌。 您可以使用 .NET Core 和 ASP.NET Core 中記錄中所討論的任何組態選項來控制記錄。

使用 Azure 服務總線連結庫作為範例，完成下列步驟：

1. 安裝 Azure.Monitor.OpenTelemetry.AspNetCore NuGet 套件：

   dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
   

2. 建立或註冊圖書館的客戶端。 發行版支援這兩種情況。

   await using var client = new ServiceBusClient("<connection_string>");
   

3. 在 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 要求和響應主體

備註

此功能僅適用於使用 HTTP 透過與 Azure 服務進行通訊的程式庫。 使用替代通訊協議的函式庫，例如AMQP，不支援內容日誌記錄。 不支援的範例包括 Azure 服務的程式庫，例如事件中樞、服務匯流排和 Web PubSub。

使用用戶端程式庫針對非預期的行為進行疑難解答時，檢查下列項目是有幫助的：

• 傳送至基礎 Azure 服務 REST API 的 HTTP 請求正文。
• 從 Azure 服務的 REST API 接收的 HTTP 回應主體。

預設情況下，上述內容的記錄是停用的。 若要啟用 HTTP 要求和響應主體的記錄，請完成下列步驟：

1. 將用戶端 options 物件的 IsLoggingContentEnabled 屬性設定為 true，並將 options 對象傳遞至用戶端的建構函式。 例如，若要記錄 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);
   

2. 使用您偏好的記錄方法，並選擇詳細資訊/偵錯或更高層級的記錄/事件層級。 如需特定指示，請在下表中找到您的方法。

   方法	操作說明
   使用內建方法啟用日誌記錄	將 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 記錄和追蹤