Registro con Azure SDK para .NET

Artículo
04/11/2024

Las bibliotecas cliente de Azure SDK para .NET incluyen la posibilidad de registrar operaciones de la biblioteca cliente. Este inicio de sesión te 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 los siguientes 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

Importante

Este artículo se aplica a las bibliotecas cliente que usan las versiones más recientes de Azure SDK para .NET. Para ver si se admite una biblioteca, consulte la lista de versiones más recientes del SDK de Azure. Si la aplicación usa una versión anterior de una biblioteca cliente de Azure SDK, consulte instrucciones específicas en la documentación del servicio aplicable.

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

Contenido de solicitud y respuesta HTTP:

Flujo de contenido como texto o bytes dependiendo de la cabecera Content-Type.

Nota

El registro de contenido está deshabilitado de manera 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 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

Las bibliotecas cliente de Azure SDK para .NET registran eventos en Seguimiento de eventos para Windows (ETW) mediante 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, debes registrar agentes de escucha de eventos.

El SDK incluye la clase Azure.Core.Diagnostics.AzureEventSourceListener, 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.

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. Pase a esa instancia un método de devolución de llamada que tú mismo escribas. 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. Los registros se filtran por esos eventos emitidos desde la biblioteca cliente de 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 (e.EventSource.Name == "Azure-Core")
        {
            Console.WriteLine($"{DateTime.Now} {message}");
        }
    },
    level: EventLevel.Verbose);

Asignación al registro de ASP.NET Core

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

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.

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

Inicio de sesión con registro de cliente

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

Instale el paquete NuGet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```
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 reenviador de registros
  - Cliente de Azure Service Bus
- Establece la credencial de token predeterminada que se usará para todos los clientes registrados.
En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de 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.AspNetCore": "Warning",
            "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.

Inicio de sesión sin registro de cliente

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

La biblioteca del SDK de Azure no incluye un método de extensión IServiceCollection para registrar un cliente en el contenedor de inserción de dependencias.
La aplicación usa las bibliotecas de extensiones de Azure que dependen de otras bibliotecas del SDK de Azure. Entre los ejemplos de estas bibliotecas de extensiones de Azure se incluyen:

En estos escenarios, complete los pasos siguientes:

Instale el paquete NuGet Microsoft.Extensions.Azure:
```
dotnet add package Microsoft.Extensions.Azure
```

En Program.cs, registre el servicio de reenvío 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());

Capture el servicio de reenviador de registros del contenedor de inserción de dependencias e invoque 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();
```
En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de Azure Core. Por ejemplo, alterne a Debug estableciendo la clave Logging:LogLevel:Azure.Core, tal como se muestra a continuación:
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Azure.Core": "Debug"
    }
  },
  "AllowedHosts": "*"
}
```
Puesto que la clave Logging:LogLevel:Azure.Core está establecida en Debug, los eventos de la biblioteca de Azure Core hasta EventLevel.Verbose se registrarán.

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

Registros con Azure.Monitor.OpenTelemetry.AspNetCore

La Distribución de 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:

Instale el paquete NuGet Azure.Monitor.OpenTelemetry.AspNetCore:
```
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
```
Cree o registre el cliente de la biblioteca. La distribución admite ambos casos.
```
await using var client = new ServiceBusClient("<connection_string>");
```
En appsettings.json, cambie el nivel de registro predeterminado de la biblioteca de 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.AspNetCore": "Warning",
            "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.

Registro de cuerpos de solicitud y respuesta HTTP

Nota:

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.

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

El cuerpo de la solicitud HTTP enviado a la API de REST del servicio de Azure subyacente.
El cuerpo de la respuesta HTTP recibido de la API de REST del servicio de Azure.

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

Establezca la propiedad IsLoggingContentEnabled del objeto de opciones de cliente en true y pase el objeto options 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);

Use su estrategia de registro preferida con un nivel de evento o registro detallado o de depuración o superior. Busque su estrategia en la tabla siguiente para obtener instrucciones específicas.

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

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