Compartir a través de

Enriquecidor de registros de aplicaciones

El enriquecidor de registros de aplicaciones aumenta los registros de telemetría con información específica de la aplicación, como los detalles del host de servicio y los metadatos de la aplicación. Este enriquecidor proporciona un contexto esencial sobre el entorno de implementación de la aplicación, la información de versión y la identidad de servicio que ayuda con la supervisión, depuración y visibilidad operativa.

Puede registrar los enriquecedores en un contenedor de IoC y todos los enriquecedores registrados son detectados automáticamente por los registros de telemetría respectivos, donde enriquecen la información de telemetría.

Prerrequisitos

Para funcionar correctamente, este enriquecidor requiere que los metadatos de la aplicación estén configurados y disponibles. Los metadatos de la aplicación proporcionan la información fundamental que usa el enriquecidor para rellenar las dimensiones de telemetría.

Instalar el paquete

Para empezar, instale el 📦 paquete NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

O bien, si usa el SDK de .NET 10+:

dotnet package add Microsoft.Extensions.Telemetry

Configuración paso a paso

Siga estos pasos para configurar el enriquecidor de registros de aplicaciones en la aplicación:

1. Configurar metadatos de la aplicación

En primer lugar, configure los metadatos de la aplicación llamando a los UseApplicationMetadata métodos:

var builder = Host.CreateApplicationBuilder(args);
builder.UseApplicationMetadata()

Este método recoge automáticamente los valores de IHostEnvironment y los guarda en la sección ambientmetadata:applicationde configuración predeterminada .

Como alternativa, puede usar el método AddApplicationMetadata(IConfigurationBuilder, IHostEnvironment, String), que registra un proveedor de configuración para los metadatos de la aplicación tomando los valores de IHostEnvironment y agregándolos al nombre de la sección de configuración dada. A continuación, use el AddApplicationMetadata(IServiceCollection, IConfigurationSection) método para registrar los metadatos en el contenedor de inserción de dependencias, lo que le permite pasar IConfigurationSection por separado:

var builder = Host.CreateApplicationBuilder(args)
    .ConfigureAppConfiguration(static (context, builder) =>
        builder.AddApplicationMetadata(context.HostingEnvironment));

builder.Services.AddApplicationMetadata(
    builder.Configuration.GetSection("ambientmetadata:application")));

2. Proporcionar configuración adicional (opcional)

Puede proporcionar una configuración adicional a través de appsettings.json. Hay dos propiedades en los metadatos de la aplicación que no obtienen valores automáticamente: BuildVersion y DeploymentRing. Si quiere usarlos, proporcione los valores manualmente:

"AmbientMetadata": {
    "Application": {
        "DeploymentRing": "testring",
        "BuildVersion": "1.2.3"
    }
},

3. Registrar el enriquecidor del registro de aplicaciones

Registre el enriquecedor de registros en el contenedor de inserción de dependencias llamando al método AddApplicationLogEnricher(IServiceCollection).

serviceCollection.AddApplicationLogEnricher();

Puede habilitar o deshabilitar opciones individuales del enriquecidor:

serviceCollection.AddApplicationLogEnricher(options =>
{
    options.BuildVersion = true;
    options.DeploymentRing = true;
});

Nota:

Si usa .NET 9 o una versión anterior, llame al AddServiceLogEnricher(IServiceCollection) método en su lugar.

Como alternativa, configure las opciones mediante appsettings.json:

"ApplicationLogEnricherOptions": {
    "BuildVersion": true,
    "DeploymentRing": true
}

A continuación, aplique la configuración.

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddApplicationLogEnricher(builder.Configuration.GetSection("ApplicationLogEnricherOptions"));

Opciones de configuración de ApplicationLogEnricherOptions

El enriquecidor de registros de aplicaciones admite varias opciones de configuración a través de la ApplicationLogEnricherOptions clase :

Propiedad Valor predeterminado Nombre de dimensión Description
EnvironmentName true deployment.environment Nombre del entorno proveniente del entorno de hospedaje o de la configuración
ApplicationName true service.name Nombre de la aplicación del entorno de hospedaje o configuración
BuildVersion false service.version Versión de compilación a partir de la configuración
DeploymentRing false DeploymentRing Anillo de implementación desde la configuración

De forma predeterminada, el enriquecidor incluye EnvironmentName y ApplicationName en entradas de registro. Las BuildVersion propiedades y DeploymentRing están deshabilitadas de forma predeterminada y deben habilitarse explícitamente si es necesario.

Ejemplo completo

Este es un ejemplo completo que muestra cómo configurar el enriquecidor de registros de aplicaciones:

appsettings.json:

{
    "AmbientMetadata": {
        "Application": {
            "DeploymentRing": "testring",
            "BuildVersion": "1.2.3"
        }
    },
    "ApplicationLogEnricherOptions": {
        "BuildVersion": true,
        "DeploymentRing": true
    }
}

Program.cs:

using System.Text.Json;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);
builder.UseApplicationMetadata();
builder.Logging.EnableEnrichment();
builder.Logging.AddJsonConsole(op =>
{
    op.JsonWriterOptions = new JsonWriterOptions
    {
        Indented = true
    };
});
builder.Services.AddApplicationLogEnricher(builder.Configuration.GetSection("ApplicationLogEnricherOptions"));

var host = builder.Build();
var logger = host.Services.GetRequiredService<ILogger<Program>>();

logger.LogInformation("This is a sample log message");

await host.RunAsync();

Salida de registro enriquecida

Con el enriquecidor de registros de aplicaciones configurado, la salida del registro incluye dimensiones específicas del servicio:

{
  "EventId": 0,
  "LogLevel": "Information",
  "Category": "Program",
  "Message": "This is a sample log message",
  "State": {
    "Message": "This is a sample log message",
    "service.name": "servicelogenricher",
    "deployment.environment": "Production",
    "DeploymentRing": "testring",
    "service.version": "1.2.3",
    "{OriginalFormat}": "This is a sample log message"
  }
}

Pasos siguientes

  • Last updated on