Registro con el SDK de Azure para .NET

El SDK de Azure para .NET y sus bibliotecas cliente incluye la capacidad de registrar las operaciones de las bibliotecas cliente. Este registro le permite supervisar las solicitudes de E/S y las respuestas que realizan las bibliotecas cliente en los servicios de Azure. Normalmente, los registros se usan para depurar o diagnosticar problemas de comunicación. En este artículo se describen los siguientes enfoques para habilitar el registro con el SDK de Azure para .NET:

• Habilitación del registro con métodos integrados
• Configuración del registro personalizado
• Mapeo al registro de ASP.NET Core

Información de registro

El SDK registra cada solicitud y respuesta HTTP, saneando los valores de consulta de parámetros y encabezado para quitar datos personales.

Entrada del registro de solicitudes HTTP:

• Id. único
• Método HTTP
• URI
• Encabezados de solicitud salientes

Entrada del registro de respuesta HTTP:

• Duración de la operación de E/S (tiempo transcurrido)
• Id. de solicitud
• Código de estado HTTP
• Frase de motivo HTTP
• Encabezados de respuesta
• Información de error, cuando corresponda

Contenido de solicitud y respuesta HTTP:

• El flujo de contenido se muestra como texto o bytes dependiendo de la cabecera Content-Type.

  Nota:

  El registro de contenido está deshabilitado de forma predeterminada. Para habilitarlo, consulte Registro de cuerpos de solicitud y respuesta HTTP. Esta funcionalidad solo se aplica a las bibliotecas que usan HTTP para comunicarse con un servicio de Azure. Las bibliotecas basadas en protocolos alternativos, como AMQP, no admiten el registro de contenido. Entre los ejemplos no admitidos se incluyen bibliotecas para servicios de Azure, como Event Hubs, Service Bus y Web PubSub.

Los registros de eventos suelen generarse en uno de estos tres niveles:

• Informativo para eventos de solicitud y respuesta
• Advertencia para errores
• Verbosidad para mensajes detallados y registro de contenido

Habilitación del registro con métodos integrados

El SDK de Azure para .NET. Las bibliotecas cliente de .NET registran eventos en el seguimiento de eventos para Windows (ETW) a través de la clase System.Diagnostics.Tracing.EventSource, que es habitual para .NET. Los orígenes de eventos permiten usar el registro estructurado en la aplicación con una sobrecarga de rendimiento mínima. Para obtener acceso a los registros de eventos, debe registrar escuchadores de eventos.

El SDK incluye la Azure.Core.Diagnostics.AzureEventSourceListener clase , que contiene dos métodos estáticos que simplifican el registro completo de la aplicación .NET: CreateConsoleLogger y CreateTraceLogger. Cada uno de estos métodos acepta un parámetro opcional que especifica un nivel de registro. Si no se proporciona el parámetro , se usa el nivel de registro predeterminado de Informational .

Iniciar sesión en la ventana de la consola

Un principio básico de las bibliotecas cliente del Azure SDK para .NET es simplificar la capacidad de ver registros completos en tiempo real. El CreateConsoleLogger método permite enviar registros a la ventana de consola con una sola línea de código:

using AzureEventSourceListener listener = 
    AzureEventSourceListener.CreateConsoleLogger();

Registrar trazas de diagnóstico

Si implementa escuchadores de traza, puede usar el método CreateTraceLogger para registrar en el mecanismo estándar de seguimiento de eventos de .NET (System.Diagnostics.Tracing). Para obtener más información sobre el seguimiento de eventos en .NET, consulte Agentes de escucha de seguimiento.

En este ejemplo se especifica un nivel de registro de verbosidad:

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

Configuración del registro personalizado

Como se mencionó anteriormente, debe registrar agentes de escucha de eventos para recibir mensajes de registro del SDK de Azure para .NET. Si no desea implementar un registro completo mediante uno de los métodos simplificados anteriores, puede construir una instancia de la AzureEventSourceListener clase . Pase a esa instancia un método de devolución de llamada que haya escrito. Este método recibirá mensajes de registro que puede procesar como necesite. Además, al construir la instancia, puede especificar los niveles de registro que se van a incluir.

En el ejemplo siguiente se crea un escuchador de eventos que registra un mensaje personalizado en la consola. Los registros se filtran para aquellos eventos emitidos desde la biblioteca cliente Azure Core con un nivel de detalle. La biblioteca de Azure Core usa un nombre de origen de eventos 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 (string.Equals(e.EventSource.Name, "Azure-Core", StringComparison.Ordinal))
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Mapeo del registro en ASP.NET Core

El AzureEventSourceLogForwarder servicio le permite usar la configuración de registro estándar ASP.NET Core para el registro. El servicio reenvía los mensajes de registro de los orígenes de eventos del SDK de Azure a ILoggerFactory.

En la tabla siguiente se muestra cómo el SDK de Azure para .NET EventLevel se asigna a ASP.NET Core LogLevel.

Registro con registro de cliente

Con la biblioteca de Azure Service Bus como ejemplo, complete los pasos siguientes:

1. Instale el paquete NuGet Microsoft.Extensions.Azure :

   dotnet add package Microsoft.Extensions.Azure
   

2. En Program.cs, registre el cliente de la biblioteca del SDK de Azure mediante una llamada al método de extensión 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());
   });
   

   En el ejemplo anterior, el método AddAzureClients:

   • Registra los siguientes objetos con el contenedor de inserción de dependencias (DI):
     • Servicio de reenvío de logs
     • Cliente de Azure Service Bus
   • Establece la credencial de token predeterminada que se usará para todos los clientes registrados.

3. En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de Service Bus. Por ejemplo, cambie a Debug estableciendo la clave de la Logging:LogLevel:Azure.Messaging.ServiceBus siguiente manera:

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

   Dado que la clave Logging:LogLevel:Azure.Messaging.ServiceBus está configurada en Debug, los eventos del cliente de Service Bus se registrarán hasta EventLevel.Verbose.

Registro sin inscripción del cliente

Hay escenarios en los que el registro del cliente de una biblioteca de Azure SDK con el contenedor de inyección de dependencias es imposible o innecesario:

• La biblioteca SDK de Azure no incluye un método de extensión IServiceCollection para registrar un cliente en el contenedor de inyección de dependencias.
• La aplicación usa bibliotecas de extensiones de Azure que dependen de otras bibliotecas de Azure SDK. Entre los ejemplos de estas bibliotecas de extensiones de Azure se incluyen:
  • Cifrado de claves de Azure Key Vault para DataProtection
  • Proveedor de configuración de secretos de Azure Key Vault
  • Almacén de claves de Azure Blob Storage para DataProtection

En estos escenarios, complete los pasos siguientes:

1. Instale el paquete NuGet Microsoft.Extensions.Azure :

   dotnet add package Microsoft.Extensions.Azure
   

2. En Program.cs, registre el servicio de reenviador de registros como singleton en el contenedor de inserción de dependencias:

   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. Obtener el servicio de reenviador de registros del contenedor de inyección de dependencias e invocar su método Start. Por ejemplo, mediante la inserción de constructores en una clase de modelo de página de Razor Pages de ASP.NET Core:

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

4. En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de Azure Core. Por ejemplo, cambie a Debug estableciendo la clave de la Logging:LogLevel:Azure.Core siguiente manera:

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

   Dado que la Logging:LogLevel:Azure.Core clave está establecida en Debug, se registrarán los eventos de la biblioteca de Azure Core hasta EventLevel.Verbose.

Para obtener más información, consulte Registro en .NET Core y ASP.NET Core.

Registro mediante Azure.Monitor.OpenTelemetry.AspNetCore

La distribución OpenTelemetry de Azure Monitor, a partir de la versión 1.2.0, admite la captura de registros procedentes de bibliotecas cliente de Azure. Puede controlar el registro mediante cualquiera de las opciones de configuración descritas en Registro en .NET Core y ASP.NET Core.

Con la biblioteca de Azure Service Bus como ejemplo, complete los pasos siguientes:

1. Instale el paquete NuGet Azure.Monitor.OpenTelemetry.AspNetCore :

   dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
   

2. Cree o registre el cliente de la biblioteca. La distribución de software admite ambos casos.

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

3. En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de Service Bus. Por ejemplo, cambie a Debug estableciendo la clave de la Logging:LogLevel:Azure.Messaging.ServiceBus siguiente manera:

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

   Dado que la clave Logging:LogLevel:Azure.Messaging.ServiceBus está configurada en Debug, los eventos del cliente de Service Bus se registrarán hasta EventLevel.Verbose.

Registrar los cuerpos de solicitud y respuesta HTTP

Al solucionar problemas de comportamiento inesperado con una biblioteca cliente, resulta útil inspeccionar los siguientes elementos:

• Cuerpo de la solicitud HTTP enviado a la API REST del servicio de Azure subyacente.
• Cuerpo de respuesta HTTP recibido de la API REST del servicio de Azure.

De forma predeterminada, el registro del contenido mencionado anteriormente está deshabilitado. Para habilitar el registro de los cuerpos de solicitud y respuesta HTTP, complete los pasos siguientes:

1. Establezca la propiedad IsLoggingContentEnabled del objeto de opciones de cliente en true, y pase el objeto de opciones al constructor del cliente. Por ejemplo, para registrar solicitudes HTTP y respuestas para la biblioteca de secretos de 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 su enfoque de registro preferido con un nivel de evento o registro de verbose/debug o superior. Busque su enfoque en la tabla siguiente para obtener instrucciones específicas.

   Enfoque	Instrucciones
   Habilitación del registro con métodos integrados	Pasar EventLevel.Verbose o EventLevel.LogAlways a AzureEventSourceListener.CreateConsoleLogger o AzureEventSourceListener.CreateTraceLogger
   Configuración del registro personalizado	Establezca el parámetro del constructor AzureEventSourceListener de la clase level a EventLevel.Verbose o EventLevel.LogAlways
   Mapeo al registro de ASP.NET Core	Agregar "Azure.Core": "Debug" a appsettings.json

Pasos siguientes

• Habilitar el registro de diagnósticos para las aplicaciones en Azure App Service
• Revisión de las opciones de registro y auditoría de seguridad de Azure
• Aprenda a trabajar con los registros de la plataforma Azure.
• Más información sobre el registro y el seguimiento de .NET