Log com o SDK do Azure para .NET

O SDK do Azure para . As bibliotecas de clientes do NET incluem a capacidade de registrar em log operações de biblioteca de clientes. Esse registro em log permite monitorar 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
• Mapear para o registro em log do 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 Content-Type cabeçalho.

  Observação

  O log de conteúdo está desabilitado por padrão. Para habilitá-lo, consulte a solicitação HTTP de log e os corpos de resposta. 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 Hubs de Eventos, Barramento de Serviço e Web PubSub.

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

• Informativo para eventos de solicitação e resposta
• Aviso para erros
• Detalhado para mensagens detalhadas e registro em log de conteúdo

Habilitar o registro em log com métodos internos

O SDK do Azure para . As bibliotecas de clientes do NET registram eventos no ETW (Rastreamento de Eventos para Windows) por meio da System.Diagnostics.Tracing.EventSource classe, que é típica 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();

Fazer logon em 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 os eventos emitidos da biblioteca de clientes do Azure Core com um nível detalhado. 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);

Mapear para o registro em log do ASP.NET Core

O AzureEventSourceLogForwarder serviço permite que você use a configuração de log padrão do ASP.NET Core para registro em log. 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 em log com o registro do cliente

Usando a biblioteca do Barramento de Serviço do Azure como exemplo, 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 AddAzureClients método:

   • Registra os seguintes objetos com o contêiner de DI (injeção de dependência):
     • Serviço de encaminhador de log
     • 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, alterne-a definindo Debug a chave da Logging:LogLevel:Azure.Messaging.ServiceBus 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 registro 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 encaminhador 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 encaminhador de log do contêiner de DI e invoque seu Start método. 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-a definindo Debug a chave da Logging:LogLevel:Azure.Core 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 em log usando 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 do Barramento de Serviço. Por exemplo, alterne-a definindo Debug a chave da Logging:LogLevel:Azure.Messaging.ServiceBus 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 de solicitação e resposta HTTP de log

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

• O corpo da solicitação HTTP enviado para a API REST do serviço do Azure subjacente.
• 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 do objeto de opções do IsLoggingContentEnabled cliente como true, e passe o objeto de opções para o construtor do cliente. Por exemplo, para registrar em log solicitações HTTP e respostas para a biblioteca de segredos do 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. Use sua abordagem de registro em log preferencial 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
   Mapear para o registro em log do 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 do .NET