Registo com o SDK do Azure para .NET

  • Artigo

O SDK do Azure para . As bibliotecas de cliente da NET incluem a capacidade de registrar operações de biblioteca de cliente. Esse 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 aplica-se a bibliotecas de cliente 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 do Azure. Se seu aplicativo estiver usando uma versão mais antiga de uma biblioteca de cliente do SDK do Azure, consulte instruções específicas na documentação de serviço aplicável.

Informações de registo

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

Entrada de log de solicitação HTTP:

  • ID Único
  • 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 do Pedido
  • Código de estado HTTP
  • Frase de razão HTTP
  • Cabeçalhos de resposta
  • Informações de erro, quando aplicável

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

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

    Nota

    O registo de conteúdos está desativado por predefinição. Para habilitá-lo, consulte Registrar corpos de solicitação e resposta HTTP. Esse recurso se aplica somente a bibliotecas que usam HTTP para se comunicar com um serviço do Azure. Bibliotecas baseadas em protocolos alternativos, como AMQP, não suportam registro de conteúdo. Exemplos sem suporte incluem bibliotecas para serviços do Azure, como Hubs de Eventos, Service Bus e Web PubSub.

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

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

Habilite o registro em log com métodos internos

O SDK do Azure para . As bibliotecas de cliente da NET registram eventos no Rastreamento de Eventos para Windows (ETW) por meio da classe, que é típica do System.Diagnostics.Tracing.EventSource .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 classe, que contém dois métodos estáticos que simplificam o Azure.Core.Diagnostics.AzureEventSourceListener 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 log padrão de Informational será usado.

Fazer login na janela do console

Um princípio básico do SDK do Azure para bibliotecas de cliente .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 registrar 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 Rastrear ouvintes.

Este exemplo especifica um nível de log detalhado:

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

Configurar log personalizado

Como 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, você pode construir uma instância da AzureEventSourceListener classe. Passe a 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 registra no console com uma mensagem personalizada. Os logs são filtrados para esses eventos emitidos pela biblioteca de cliente do Azure Core com um nível de detalhe. A biblioteca do Azure Core usa um nome de fonte de 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 ASP.NET registro em log do núcleo

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

A tabela a seguir mostra como o SDK do Azure para .NET EventLevel mapeia para o ASP.NET Core LogLevel.

Azure SDK EventLevel ASP.NET Núcleo LogLevel
Critical Critical
Error Error
Informational Information
Warning Warning
Verbose Debug
LogAlways Information

Registo com registo de 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. No 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"));
    azureBuilder.UseCredential(new DefaultAzureCredential());
});

    Na amostra anterior, o AddAzureClients método:

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

  3. No appsettings.json, altere o nível de log padrão da biblioteca do Service Bus. Por exemplo, alterne-o definindo Debug a Logging:LogLevel:Azure.Messaging.ServiceBus chave 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 do cliente do Service Bus serão EventLevel.Verbose registrados.

Registo sem registo de cliente

Há cenários em que registrar o cliente de uma 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 encaminhador 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. Buscar o serviço de encaminhador de log do contêiner DI e invocar seu Start método. Por exemplo, usando a injeção do construtor em uma classe de modelo de página do 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. No appsettings.json, altere o nível de log padrão da biblioteca do Azure Core. Por exemplo, alterne-o definindo Debug a Logging:LogLevel:Azure.Core chave 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 serão EventLevel.Verbose registrados.

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

Registro em log usando Azure.Monitor.OpenTelemetry.AspNetCore

A distro OpenTelemetry do Azure Monitor, começando com a versão 1.2.0, dá suporte à captura de logs provenientes de bibliotecas de cliente do Azure. Você pode controlar o log usando qualquer uma das opções de configuração discutidas em 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 distro suporta ambos os casos.

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

  3. No appsettings.json, altere o nível de log padrão da biblioteca do Service Bus. Por exemplo, alterne-o definindo Debug a Logging:LogLevel:Azure.Messaging.ServiceBus chave 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 do cliente do Service Bus serão EventLevel.Verbose registrados.

Registrar corpos de solicitação e resposta HTTP

Nota

Esse recurso se aplica somente a bibliotecas que usam HTTP para se comunicar com um serviço do Azure. Bibliotecas baseadas em protocolos alternativos, como AMQP, não suportam registro de conteúdo. Exemplos sem suporte incluem bibliotecas para serviços do Azure, como Hubs de Eventos, Service Bus e Web PubSub.

Ao solucionar problemas de comportamento inesperado com uma biblioteca de cliente, é ú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 do conteúdo acima mencionado é desativado. 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 IsLoggingContentEnabled opções do cliente como true, e passe o objeto options para o construtor do cliente. Por exemplo, para registrar solicitações HTTP e respostas 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. Use sua abordagem de log 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
    Habilite o registro em log com métodos internos Passe EventLevel.Verbose ou EventLevel.LogAlways para AzureEventSourceListener.CreateConsoleLogger ou AzureEventSourceListener.CreateTraceLogger
    Configurar log personalizado Defina o parâmetro do construtor da AzureEventSourceListenerlevel classe como EventLevel.Verbose ou EventLevel.LogAlways
    Mapear para ASP.NET registro em log do núcleo Adicionar "Azure.Core": "Debug" a appsettings.json

Próximos passos