Ведение журнала с помощью пакета Azure SDK для .NET

Статья
04/05/2024

Пакет SDK Azure для . Клиентские библиотеки NET включают возможность регистрировать операции клиентской библиотеки. Это ведение журнала позволяет отслеживать запросы и ответы ввода-вывода, выполняемые клиентскими библиотеками в службах Azure. Как правило, журналы используются для отладки или диагностики проблем связи. В этой статье описаны следующие подходы к включению ведения журнала с помощью пакета SDK Azure для .NET:

Включение ведения журнала с помощью встроенных методов
Настройка пользовательского ведения журнала
Сопоставление с ведением журналов ASP.NET Core

Внимание

Эта статья применяется к клиентским библиотекам, использующим последние версии пакета Azure SDK для .NET. Чтобы узнать, поддерживается ли библиотека, ознакомьтесь со списком последних выпусков пакета SDK Для Azure. Если приложение использует более раннюю версию клиентской библиотеки пакета SDK Azure, ознакомьтесь с конкретными инструкциями в соответствующей документации по службе.

Сведения о журнале

Пакет SDK регистрирует каждый HTTP-запрос и ответ, очищая значения запросов параметров и заголовков для удаления персональных данных.

Запись HTTP-запроса в журнале:

Уникальный идентификатор
Метод HTTP
URI-адрес
Заголовки исходящего запроса

Запись HTTP-ответа в журнале:

Длительность операции ввода-вывода (прошедшее время)
Идентификатор запроса
Код состояния HTTP
Описание причины HTTP
Заголовки ответа
Сведения об ошибке, если применимо

Содержимое HTTP-запроса и ответа:

Поток содержимого в виде текста или байтов в зависимости от заголовка Content-Type .

Примечание.

Ведение журнала для содержимого по умолчанию отключено. Сведения о том, как включить его, см. в разделе "Http-запрос журнала" и "Тела ответа". Эта возможность применяется только к библиотекам, использующим HTTP для взаимодействия со службой Azure. Библиотеки на основе альтернативных протоколов, таких как AMQP, не поддерживают ведение журнала содержимого. Неподдерживаемые примеры включают библиотеки для служб Azure, таких как Центры событий, служебная шина и Web PubSub.

Обычно используется один из трех следующих уровней ведения журнала:

"Информационный" — для событий запроса и ответа
"Предупреждение" — для ошибок
"Подробный" — для записи подробных сообщений и содержимого

Включение ведения журнала с помощью встроенных методов

Пакет SDK Azure для . Клиентские библиотеки NET регистрируют события трассировки событий для Windows (ETW) через System.Diagnostics.Tracing.EventSource класс, который является типичным для .NET. Источники событий позволяют использовать структурированное ведение журнала в приложении с минимальными затратами на производительность. Чтобы получить доступ к журналам событий, необходимо зарегистрировать прослушиватели событий.

Пакет SDK включает Azure.Core.Diagnostics.AzureEventSourceListener класс, содержащий два статических метода, которые упрощают комплексное ведение журнала для приложения .NET: CreateConsoleLogger и CreateTraceLogger. Каждый из этих методов принимает необязательный параметр, указывающий уровень журнала. Если параметр не указан, используется уровень Informational журнала по умолчанию.

Ведение журнала в окне консоли

Основным принципом клиентских библиотек пакета Azure SDK для .NET является упрощение просмотра подробных журналов в режиме реального времени. Метод CreateConsoleLogger позволяет отправлять журналы в окно консоли с помощью одной строки кода:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Ведение журнала с помощью трассировки диагностики

При реализации прослушивателей трассировки можно использовать метод CreateTraceLogger для входа в стандартный механизм трассировки событий .NET (System.Diagnostics.Tracing). Дополнительные сведения о трассировке событий в .NET см. в разделе Прослушиватели трассировки.

В этом примере задается уровень детализации журнала:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose);

Настраиваемое ведение журнала

Как упоминалось выше, для получения сообщений журнала из пакета SDK Azure для .NET необходимо зарегистрировать прослушиватели событий. Если вы не хотите реализовать комплексное ведение журнала с помощью одного из описанных выше упрощенных методов, можно создать экземпляр 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. Служба перенаправит сообщения журнала из источников ILoggerFactoryсобытий пакета SDK Azure в .

В следующей таблице показано, как пакет Azure SDK для .NET EventLevel сопоставляется с ASP.NET Core LogLevel.

Пакет SDK Azure `EventLevel`	ASP.NET Core `LogLevel`
`Critical`	`Critical`
`Error`	`Error`
`Informational`	`Information`
`Warning`	`Warning`
`Verbose`	`Debug`
`LogAlways`	`Information`

Ведение журнала с помощью регистрации клиента

Используя библиотеку Служебная шина Azure в качестве примера, выполните следующие действия.

Установите пакет NuGet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```
В Program.cs зарегистрируйте клиент библиотеки ПАКЕТА SDK Azure с помощью вызова AddAzureClients метода расширения:
```
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.

Ведение журнала без регистрации клиента

Существуют сценарии, в которых регистрация клиента библиотеки SDK Azure в контейнере DI невозможна или не требуется:

Библиотека ПАКЕТА SDK Azure не включает IServiceCollection метод расширения для регистрации клиента в контейнере DI.
Приложение использует библиотеки расширений Azure, зависящие от других библиотек пакета SDK Azure. Примеры таких библиотек расширений Azure:

В этих сценариях выполните следующие действия.

Установите пакет NuGet Microsoft.Extensions.Azure:
```
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 метод. Например, использование внедрения конструктора в класс модели страницы Razor Pages ASP.NET Core:
```
using Microsoft.AspNetCore.Mvc.RazorPages;
using Microsoft.Extensions.Azure;

public class IndexModel : PageModel
{
    public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
        logForwarder.Start();
```
В 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

Дистрибутив OpenTelemetry Azure Monitor, начиная с версии1.2.0, поддерживает запись журналов, поступающих из клиентских библиотек Azure. Вы можете управлять ведением журнала с помощью любого из параметров конфигурации, рассмотренных в разделе "Ведение журнала в .NET Core" и ASP.NET Core.

Используя библиотеку Служебная шина Azure в качестве примера, выполните следующие действия.

Установите пакет NuGet Для Azure.Monitor.OpenTelemetry.AspNetCore:
```
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.

При устранении неполадок с непредвиденным поведением в клиентской библиотеке полезно проверить следующие элементы:

Текст HTTP-запроса, отправляемый в базовый REST API службы Azure.
Текст ответа HTTP, полученный от REST API службы Azure.

По умолчанию ведение журнала указанного выше упоминание содержимого отключено. Чтобы включить ведение журнала http-запросов и тел ответа, выполните следующие действия.

Задайте для свойства trueобъекта параметров клиента значение и передайте объект IsLoggingContentEnabled параметров конструктору клиента. Например, чтобы регистрировать HTTP-запросы и ответы для библиотеки секретов Azure Key Vault:
```
var clientOptions = new SecretClientOptions
{
    Diagnostics = 
    {
        IsLoggingContentEnabled = true,
    }
};
var client = new SecretClient(
    new Uri("https://<keyvaultname>.vault.azure.net/"),
    new DefaultAzureCredential(),
    clientOptions);
```

Используйте предпочтительный подход к ведению журнала с уровнем события или журнала подробных или отладочных или более поздних версий. Найдите подход в следующей таблице для конкретных инструкций.

Подход	Instructions
Включение ведения журнала с помощью встроенных методов	Передача `EventLevel.Verbose` или `EventLevel.LogAlways` переход в `AzureEventSourceListener.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger`
Настройка пользовательского ведения журнала	`AzureEventSourceListener` Задайте для параметра конструктора класса `level` значение `EventLevel.Verbose` или`EventLevel.LogAlways`
Сопоставление с ведением журналов ASP.NET Core	Добавление `"Azure.Core": "Debug"` в appsettings.json

Следующие шаги

Включение функции ведения журналов диагностики для приложений в Службе приложений Azure
Просмотрите параметры ведения журнала безопасности и аудита в Azure
Узнайте о том, как работать с журналами платформы Azure
Дополнительные сведения о ведении журнала и трассировке .NET

Поделиться через