Registro con Azure SDK para .NET

Las bibliotecas cliente de Azure SDK para .NET incluyen la posibilidad de registrar operaciones de la biblioteca cliente. Esto le permite supervisar las solicitudes de E/S y las respuestas que las bibliotecas cliente realizan en los servicios de Azure. Normalmente, los registros se usan para depurar o diagnosticar problemas de comunicación. En este artículo se describen tres métodos para habilitar el registro con Azure SDK para .NET:

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

Información de registro

El SDK registra la siguiente información, depurando los valores de encabezado y consulta de los parámetros para quitar datos personales.

Entrada del registro de solicitudes HTTP:

• Id. único
• HTTP method
• Identificador URI
• Encabezados de solicitudes salientes

Entrada del registro de respuestas HTTP:

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

Para el contenido de la solicitud y la respuesta:

• Flujo de contenido como texto o bytes, según el encabezado Content-Type.

  Nota

  El registro de contenido está deshabilitado de manera predeterminada. Para habilitarlo, cambie Diagnostics.IsLoggingContentEnabled a true en ClientOptions.

Los registros de eventos se generan normalmente en uno de estos tres niveles:

• Información para eventos de solicitud y respuesta
• Advertencia para errores
• Detallado para mensajes detallados y registro de contenido

Habilitación del registro con métodos integrados

El SDK de Azure para las bibliotecas cliente de .NET registra eventos en Seguimiento de eventos para Windows (ETW) mediante la clase EventSource, que es habitual para .NET. Los orígenes de eventos permiten usar el registro estructurado en el código de aplicación con una sobrecarga de rendimiento mínima. Para obtener acceso a estos registros de eventos, debe registrar agentes de escucha de eventos.

El SDK incluye la clase Azure.Core.Diagnostics.AzureEventSourceListener (definida en el paquete Azure.Core NuGet), que contiene dos métodos estáticos que simplifican el registro completo de la aplicación .NET: CreateConsoleLogger y CreateTraceLogger. Estos métodos adoptan un parámetro opcional que especifica un nivel de registro.

Inicio de sesión en la ventana de consola

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

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Registro para el seguimiento de diagnósticos

Si implementa agentes de escucha de seguimiento, puede usar el método CreateTraceLogger para registrarse en el mecanismo de seguimiento de eventos estándar de .NET (System.Diagnostics.Tracing). Para obtener más información sobre el seguimiento de eventos en .NET, vea Agentes de escucha de seguimiento. En este ejemplo se especifica un nivel de registro detallado:

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

Configuración del registro personalizado

Como se mencionó anteriormente, debe registrar los agentes de escucha de eventos para recibir mensajes de registro de Azure SDK para .NET. Si no quiere implementar un registro completo con uno de los métodos simplificados anteriores, puede construir una instancia de la clase AzureEventSourceListener y pasarle una función de devolución de llamada que usted mismo escriba. Este método recibirá mensajes de registro que se pueden procesar en caso que sea necesario. Además, cuando se crea la instancia, se pueden especificar los niveles de registro que se van a incluir.

En el ejemplo siguiente, se crea un agente de escucha de eventos que se registra en la consola con un mensaje personalizado y se filtra a los eventos principales de Azure del nivel detallado.

using AzureEventSourceListener 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);

Asignación al registro de ASP.NET Core

Cuando se llama al método de extensión AddAzureClients, el servicio AzureEventSourceLogForwarder se registra. El servicio AzureEventSourceLogForwarder permite usar la configuración de registro de ASP.NET Core estándar para el registro.

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

Considere la siguiente llamada a AddAzureClients en el método Startup.ConfigureServices de un proyecto de ASP.NET Core. El método AddAzureClients registra el cliente de Azure Service Bus y establece las credenciales predeterminadas que se usarán para todos los clientes.

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddServiceBusClient(Configuration.GetConnectionString("ServiceBus"));
        builder.UseCredential(new DefaultAzureCredential());
    });
  
    // code omitted for brevity
}

En el archivo appsettings.json del proyecto de ASP.NET Core, se puede cambiar el nivel de registro predeterminado para la biblioteca cliente de Azure Service Bus. Por ejemplo, alterne a Debug estableciendo la clave Logging:LogLevel:Azure.Messaging.ServiceBus, tal como se muestra a continuación:

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

Puesto que la clave Logging:LogLevel:Azure.Messaging.ServiceBus está establecida en Debug, los eventos de cliente de Service Bus hasta EventLevel.Verbose se registrarán. Para obtener más información, vea Registro en .NET Core y ASP.NET Core.

Pasos siguientes

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