共用方式為


使用適用於 .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 應用程式的完整記錄:CreateConsoleLoggerCreateTraceLogger。 每個方法都接受以選擇性參數來指定記錄層級。 如果未提供參數,則會使用 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);

對應至 ASP.NET Core 記錄

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 服務匯流排程式庫作為範例,完成下列步驟:

  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"));
        azureBuilder.UseCredential(new DefaultAzureCredential());
    });
    

    在上述範例中,AddAzureClients 方法可進行下列操作:

    • 使用相依性插入 (DI) 容器註冊下列物件:
      • 記錄轉寄站服務
      • Azure 服務匯流排用戶端
    • 設定要用於所有已註冊用戶端的預設權杖認證。
  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 程式庫的用戶端

在這些案例中,請完成下列步驟:

  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 程式庫的預設記錄層級。 例如,藉由設定 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.Monitor.OpenTelemetry.AspNetCore 進行記錄

Azure 監視器 OpenTelemetry 散發版本 (從 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. 將用戶端選項物件的 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);
    
  2. 使用慣用的記錄方法,搭配詳細資訊/偵錯或更新版本的事件/記錄層級。 如需特定指示,請在下表中找到您的方法。

    方法 指示
    使用內建方法啟用記錄 傳遞 EventLevel.VerboseEventLevel.LogAlwaysAzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger
    設定自訂記錄 AzureEventSourceListener 類別的 level 建構函式參數設定為 EventLevel.VerboseEventLevel.LogAlways
    對應至 ASP.NET Core 記錄 "Azure.Core": "Debug" 新增至 appsettings.json

下一步