Registro de logs com o SDK do Azure para .NET

O SDK do Azure para .NET inclui bibliotecas de clientes com a capacidade de registrar operações das bibliotecas de cliente. Esse log permite que você monitore solicitações de E/S e respostas que as bibliotecas de clientes estão fazendo aos serviços do Azure. Normalmente, os logs são usados para depurar ou diagnosticar problemas de comunicação. Este artigo descreve as seguintes abordagens para habilitar o registro em log com o SDK do Azure para .NET:

• Habilitar o registro em log com métodos internos
• Configurar o log personalizado
• Mapeamento para o registro em log no ASP.NET Core

Informações do log

O SDK registra cada solicitação e resposta HTTP, higienizando valores de consulta e cabeçalho de parâmetro para remover dados pessoais.

Entrada de log de solicitação HTTP:

• Identificação Única
• método HTTP
• URI
• Cabeçalhos de solicitação de saída

Entrada do log de resposta HTTP:

• Duração da operação de E/S (tempo decorrido)
• ID da Solicitação
• Código de status de HTTP
• Frase de motivo HTTP
• Cabeçalhos de resposta
• Informações de erro, quando aplicável

Conteúdo de solicitação e resposta HTTP:

• Fluxo de conteúdo como texto ou bytes dependendo do cabeçalho Content-Type.

  Observação

  O log de conteúdo está desabilitado por padrão. Para habilitar isso, consulte Registrar corpos de solicitações e respostas HTTP. Essa funcionalidade se aplica apenas a bibliotecas que usam HTTP para se comunicar com um serviço do Azure. Bibliotecas baseadas em protocolos alternativos, como AMQP, não dão suporte ao log de conteúdo. Exemplos sem suporte incluem bibliotecas para serviços do Azure, como Hub de Eventos, Barramento de Serviços e Web PubSub.

Os logs de eventos geralmente são gerados em um destes três níveis:

• Informações para eventos de solicitação e resposta
• Aviso para erros
• Verboso para mensagens detalhadas e registro em log de conteúdo

Habilitar o registro em log com métodos internos

O SDK do Azure para .NET usa as bibliotecas de clientes do .NET para registrar eventos no Rastreamento de Eventos para Windows (ETW) por meio da classe System.Diagnostics.Tracing.EventSource, o que é típico para .NET. As fontes de eventos permitem que você use o log estruturado em seu aplicativo com sobrecarga de desempenho mínima. Para obter acesso aos logs de eventos, você precisa registrar ouvintes de eventos.

O SDK inclui a Azure.Core.Diagnostics.AzureEventSourceListener classe, que contém dois métodos estáticos que simplificam o registro em log abrangente para seu aplicativo .NET: CreateConsoleLogger e CreateTraceLogger. Cada um desses métodos aceita um parâmetro opcional que especifica um nível de log. Se o parâmetro não for fornecido, o nível de Informational log padrão será usado.

Fazer logon na janela do console

Um princípio principal do SDK do Azure para bibliotecas de clientes .NET é simplificar a capacidade de exibir logs abrangentes em tempo real. O CreateConsoleLogger método permite que você envie logs para a janela do console com uma única linha de código:

using AzureEventSourceListener listener =
    AzureEventSourceListener.CreateConsoleLogger();

Registrar rastreamentos de diagnóstico

Se você implementar ouvintes de rastreamento, poderá usar o CreateTraceLogger método para fazer logon no mecanismo de rastreamento de eventos .NET padrão (System.Diagnostics.Tracing). Para obter mais informações sobre o rastreamento de eventos no .NET, consulte Ouvintes de Rastreamento.

Este exemplo especifica um nível de log detalhado:

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

Configurar o log personalizado

Conforme mencionado acima, você precisa registrar ouvintes de eventos para receber mensagens de log do SDK do Azure para .NET. Se você não quiser implementar o log abrangente usando um dos métodos simplificados acima, poderá construir uma instância da AzureEventSourceListener classe. Passe para essa instância um método de retorno de chamada que você escreve. Esse método receberá mensagens de log que você pode processar como precisar. Além disso, ao construir a instância, você pode especificar os níveis de log a serem incluídos.

O exemplo a seguir cria um ouvinte de eventos que faz logon no console com uma mensagem personalizada. Os logs são filtrados para incluir apenas os eventos emitidos da biblioteca de clientes do Azure Core com um nível de verbosidade. A biblioteca do Azure Core usa um nome de origem do evento 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);

Mapeamento para o log em ASP.NET Core

O serviço AzureEventSourceLogForwarder permite que você use a configuração padrão de registro de logs do ASP.NET Core. O serviço encaminha mensagens de log de fontes de eventos do SDK do Azure para ILoggerFactory.

A tabela a seguir descreve como o SDK do Azure para .NET EventLevel é mapeado para o ASP.NET Core LogLevel.

Registro de log com registro do cliente

Como exemplo, use a biblioteca do Barramento de Serviço do Azure e conclua as seguintes etapas:

1. Instale o pacote NuGet Microsoft.Extensions.Azure

   dotnet add package Microsoft.Extensions.Azure
   

2. Em Program.cs, registre o cliente da biblioteca do SDK do Azure por meio de uma chamada para o AddAzureClients método de extensão:

   using Azure.Identity;
   using Microsoft.Extensions.Azure;
   
   // code omitted for brevity
   
   builder.Services.AddAzureClients(azureBuilder =>
   {
       azureBuilder.AddServiceBusClient(
           builder.Configuration.GetConnectionString("ServiceBus"));
   });
   

   No exemplo anterior, o método AddAzureClients:

   • Registra os seguintes objetos com o contêiner de injeção de dependência (DI):
     • Serviço de encaminhamento de logs
     • Cliente do Barramento de Serviço do Azure
   • DefaultAzureCredential Aplica-se automaticamente à autenticação, a menos que uma credencial diferente seja configurada explicitamente.

3. Em appsettings.json, altere o nível de log padrão da biblioteca do Barramento de Serviço. Por exemplo, mude-o para Debug definindo a chave Logging:LogLevel:Azure.Messaging.ServiceBus da seguinte maneira:

   {
       "ConnectionStrings": {
           "ServiceBus": "<connection_string>"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning",
               "Azure.Messaging.ServiceBus": "Debug"
           }
       },
       "AllowedHosts": "*"
   }
   

   Como a Logging:LogLevel:Azure.Messaging.ServiceBus chave está definida como Debug, os eventos de cliente do Barramento de Serviço até EventLevel.Verbose serão registrados em log.

Registro em log sem cadastramento do cliente

Há cenários em que o registro do cliente de uma biblioteca do SDK do Azure com o contêiner de DI é impossível ou desnecessário:

• A biblioteca do SDK do Azure não inclui um IServiceCollection método de extensão para registrar um cliente no contêiner de DI.
• Seu aplicativo usa bibliotecas de extensão do Azure que dependem de outras bibliotecas do SDK do Azure. Exemplos dessas bibliotecas de extensão do Azure incluem:
  • Criptografador de chaves do Azure Key Vault para DataProtection
  • Provedor de configuração de segredos do Azure Key Vault
  • Repositório de chaves do Armazenamento de Blobs do Azure para DataProtection

Nestes cenários, conclua as seguintes etapas:

1. Instale o pacote NuGet Microsoft.Extensions.Azure:

   dotnet add package Microsoft.Extensions.Azure
   

2. Em Program.cs, registre o serviço de repassador de log como um singleton no contêiner de 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. Busque o serviço de encaminhamento de logs do contêiner de DI e invoque seu método Start. Por exemplo, usando a injeção de construtor em uma classe de modelo de página do Razor Pages do ASP.NET Core:

   using Microsoft.AspNetCore.Mvc.RazorPages;
   using Microsoft.Extensions.Azure;
   
   public class IndexModel : PageModel
   {
       public IndexModel(AzureEventSourceLogForwarder logForwarder) =>
           logForwarder.Start();
   

4. Em appsettings.json, altere o nível de log padrão da biblioteca do Azure Core. Por exemplo, alterne para Debug configurando a chave Logging:LogLevel:Azure.Core da seguinte maneira:

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning",
         "Azure.Core": "Debug"
       }
     },
     "AllowedHosts": "*"
   }
   

   Como a Logging:LogLevel:Azure.Core chave está definida como Debug, os eventos da biblioteca do Azure Core até EventLevel.Verbose serão registrados em log.

Para obter mais informações, consulte Log no .NET Core e no ASP.NET Core.

Registro de log com Azure.Monitor.OpenTelemetry.AspNetCore

A distribuição OpenTelemetry do Azure Monitor, começando pela versão 1.2.0, dá suporte à captura de logs provenientes de bibliotecas de clientes do Azure. Você pode controlar o registro em log usando qualquer uma das opções de configuração discutidas no registro em log no .NET Core e no ASP.NET Core.

Usando a biblioteca do Barramento de Serviço do Azure como exemplo, conclua as seguintes etapas:

1. Instale o pacote NuGet Azure.Monitor.OpenTelemetry.AspNetCore :

   dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
   

2. Crie ou registre o cliente da biblioteca. A distribuição dá suporte a ambos os casos.

   await using var client = new ServiceBusClient("<connection_string>");
   

3. Em appsettings.json, altere o nível de log padrão da biblioteca Service Bus. Por exemplo, alterne para Debug definindo a chave Logging:LogLevel:Azure.Messaging.ServiceBus da seguinte maneira:

   {
       "ConnectionStrings": {
           "ServiceBus": "<connection_string>"
       },
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning",
               "Azure.Messaging.ServiceBus": "Debug"
           }
       },
       "AllowedHosts": "*"
   }
   

   Como a Logging:LogLevel:Azure.Messaging.ServiceBus chave está definida como Debug, os eventos de cliente do Barramento de Serviço até EventLevel.Verbose serão registrados em log.

Registrar os corpos das solicitações e respostas HTTP

Ao solucionar problemas de comportamento inesperado com uma biblioteca de clientes, é útil inspecionar os seguintes itens:

• O corpo da requisição HTTP enviado para a API REST do serviço subjacente do Azure.
• O corpo da resposta HTTP recebido da API REST do serviço do Azure.

Por padrão, o registro em log do conteúdo mencionado acima está desabilitado. Para habilitar o registro em log dos corpos de solicitação e resposta HTTP, conclua as seguintes etapas:

1. Defina a propriedade IsLoggingContentEnabled do objeto de opções do cliente como true, e passe o objeto de opções para o construtor do cliente. Por exemplo, para registrar solicitações e respostas HTTP para a biblioteca Azure Key Vault Secrets:

   var clientOptions = new SecretClientOptions
   {
       Diagnostics =
       {
           IsLoggingContentEnabled = true
       }
   };
   var client = new SecretClient(
       new Uri("https://<keyvaultname>.vault.azure.net/"),
       new DefaultAzureCredential(),
       clientOptions);
   

2. Utilize sua abordagem de logging preferida com um nível de evento/log de detalhado/depuração ou superior. Encontre sua abordagem na tabela a seguir para obter instruções específicas.

   Abordagem	Instruções
   Habilitar o registro em log com métodos internos	Passar EventLevel.Verbose ou EventLevel.LogAlways para AzureEventSourceListener.CreateConsoleLogger ou AzureEventSourceListener.CreateTraceLogger
   Configurar o log personalizado	Definir o AzureEventSourceListener parâmetro do construtor da level classe como EventLevel.Verbose ou EventLevel.LogAlways
   Mapeamento para o registro em log no ASP.NET Core	Adicionar "Azure.Core": "Debug" ao appsettings.json

Próximas etapas

• Habilitar log de diagnósticos para aplicativos no Serviço de Aplicativo do Azure
• Examinar as opções de log e auditoria de segurança do Azure
• Saiba como trabalhar com logs de plataforma do Azure
• Leia mais sobre registro em log e rastreamento no .NET