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

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"));
       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 клиента служебной шины будут регистрироваться.

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

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

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.CreateConsoleLoggerAzureEventSourceListener.CreateTraceLogger
   Настройка пользовательского ведения журнала	AzureEventSourceListener Задайте для параметра конструктора класса level значение EventLevel.Verbose илиEventLevel.LogAlways
   Сопоставление с ведением журнала ASP.NET Core	Добавление "Azure.Core": "Debug" в appsettings.json

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

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