Ведение логирования с использованием Azure SDK для .NET

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

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

Это важно

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

Информация о логах

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

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

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

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

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

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

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

  Замечание

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

Журналы событий обычно выводятся на одном из трех уровней:

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

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

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

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

Вход в окно консоли

Главный принцип клиентских библиотек SDK Azure для .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, с уровнем verbose. Библиотека 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 Core для ведения журнала. Служба перенаправляет сообщения журнала из источников событий пакета SDK Azure в ILoggerFactory.

В следующей таблице показано, как пакет 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 в качестве примера, выполните следующие действия.

1. Установите пакет NuGet Microsoft.Extensions.Azure.

   dotnet add package Microsoft.Extensions.Azure
   

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

   В предыдущем примере метод 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, события клиента Service Bus до EventLevel.Verbose будут регистрироваться.

Логирование без регистрации клиента

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

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

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

1. Установите пакет NuGet Microsoft.Extensions.Azure :

   dotnet add package Microsoft.Extensions.Azure
   

2. В Program.cs зарегистрируйте службу пересылки журналов как одиночный объект в контейнере зависимостей:

   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. Например, использование внедрения конструктора в класс модели страницы Razor Pages ASP.NET Core:

   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, события библиотеки Azure Core будут регистрироваться до EventLevel.Verbose.

Дополнительные сведения см. в разделе Ведение журнала в .NET Core и ASP.NET Core.

Ведение журнала с помощью Azure.Monitor.OpenTelemetry.AspNetCore

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

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

1. Установите пакет NuGet Azure.Monitor.OpenTelemetry.AspNetCore:

   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.

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

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

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

1. Задайте для свойства IsLoggingContentEnabledобъекта параметров клиента значение и передайте объект true параметров конструктору клиента. Например, чтобы регистрировать 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);
   

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

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

Дальнейшие шаги

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