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

發行項
04/15/2024

適用於 .NET 的 Azure SDK 用戶端程式庫具有記錄用戶端程式庫作業的能力。此記錄可讓您監視用戶端程式庫對 Azure 服務提出的 I/O 要求和回應。一般而言，記錄用於偵錯或診斷通訊問題。本文將說明如何以下列方法，使用適用於 .NET 的 Azure SDK 啟用記錄：

使用內建方法啟用記錄
設定自訂記錄
對應至 ASP.NET Core 記錄

重要

本文適用於使用最新版本適用於 .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);

對應至 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 服務匯流排程式庫作為範例，完成下列步驟：

安裝 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 服務匯流排用戶端
- 設定要用於所有已註冊用戶端的預設權杖認證。
在 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.Monitor.OpenTelemetry.AspNetCore 進行記錄

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 要求和回應主體

注意

此功能僅適用於使用 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