Registro em log com o SDK do Azure para .NET

  • Artigo

O SDK do Azure para . As bibliotecas de cliente do NET incluem a capacidade de registrar em log operações de biblioteca de cliente. Esse registro em log permite monitorar solicitações de E/S e respostas que as bibliotecas de cliente 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:

Importante

Este artigo se aplica às bibliotecas de clientes que usam as versões mais recentes do SDK do Azure para .NET. Para ver se há suporte para uma biblioteca, consulte a lista de versões mais recentes do SDK doAzure. Se o aplicativo estiver usando uma versão mais antiga das biblioteca de clientes do SDK do Azure, veja as instruções específicas na documentação do serviço aplicável.

Informações do log

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

Entrada de log de solicitação HTTP:

  • ID Exclusiva
  • Método HTTP
  • URI
  • Cabeçalhos de solicitação de saída

Entrada de log de resposta HTTP:

  • Duração da operação de E/S (tempo decorrido)
  • ID de solicitação
  • Código de status 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 registro em log de conteúdo é desabilitado por padrão. Para habilitar, confira Registrar solicitação HTTP e 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

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

O SDK inclui a classe Azure.Core.Diagnostics.AzureEventSourceListener, 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 registro padrão de Informational será usado.

Fazer logon na janela do console

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

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Log para rastreamentos de diagnóstico

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

Este exemplo especifica um nível de log detalhado:

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

Configurar registro em 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 registro em log abrangente usando um dos métodos simplificados acima, poderá construir uma instância da classe AzureEventSourceListener. 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 esses 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 de 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);

Mapear para registro em log do ASP.NET Core

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

A tabela a seguir descreve como o SDK do Azure para .NET EventLevel mapeia para o ASP.NET CoreLogLevel.

SDK do Azure EventLevel ASP.NET Core LogLevel
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Registro em log com registro do cliente

Usando a biblioteca 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 método de extensãoAddAzureClients:

    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());
});

    Na amostra anterior,o método AddAzureClients:

    • Registra os seguintes objetos com o contêiner de DI (injeção de dependência):
      • Serviço de encaminhador de log
      • Cliente de Barramento de Serviço do Azure
    • Define a credencial de token padrão a ser usada para todos os clientes registrados.

  3. Em appsettings.json, altere o nível de log padrão da biblioteca de Barramento de Serviço do Azure. 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 chave Logging:LogLevel:Azure.Messaging.ServiceBus é definida como Debug, os eventos de cliente do Barramento de Serviço até EventLevel.Verbose serão registrados.

Registro em log sem registro de cliente

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

Nesses 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 encaminhamento de log como um singleton no contêiner 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 DI e invoque o método Start dele. Por exemplo, usando a injeção de construtor em uma classe de modelo de página ASP.NET Core Razor Pages:

    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 de Barramento de Serviço do Azure. Por exemplo, alterne para Debug definindo a chave Logging:LogLevel:Azure.Core da seguinte maneira:

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

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

Para obter mais informações, confira Registro em log no .NET Core e no ASP.NET Core.

Registro em log usando Azure.Monitor.OpenTelemetry.AspNetCore

O Azure Monitor OpenTelemetry Distro, começando com a versão 1.2.0, dá suporte à captura de logs provenientes de bibliotecas de clientes do Azure. Você pode controlar o log usando qualquer uma das opções de configuração discutidas em Logging in .NET Core e ASP.NET Core.

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

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

    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 de Barramento de Serviço do Azure. 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 chave Logging:LogLevel:Azure.Messaging.ServiceBus é definida como Debug, os eventos de cliente do Barramento de Serviço até EventLevel.Verbose serão registrados.

Registrar solicitação HTTP e corpos de resposta

Observação

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.

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

  • O corpo da solicitação HTTP enviado à 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 da solicitação HTTP e dos corpos de resposta, 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 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 evento/nível de log de depuração/depuração detalhada 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 Passe EventLevel.Verbose ou EventLevel.LogAlways para AzureEventSourceListener.CreateConsoleLogger ou AzureEventSourceListener.CreateTraceLogger
    Configurar registro em log personalizada Defina o parâmetro de construtor level da classe AzureEventSourceListener para EventLevel.Verbose ou EventLevel.LogAlways
    Mapear para registro em log do ASP.NET Core Adicione "Azure.Core": "Debug" to appsettings.json

Próximas etapas