Condividi tramite

Arricchitore del log delle applicazioni

L'arricchitore di log delle applicazioni arricchisce i log di telemetria con informazioni specifiche dell'applicazione, ad esempio dettagli dell'host del servizio e metadati dell'applicazione. Questo strumento di arricchimento fornisce un contesto essenziale sull'ambiente di distribuzione dell'applicazione, sulle informazioni sulla versione e sull'identità del servizio che consente di monitorare, eseguire debug e visibilità operativa.

È possibile registrare gli enricher in un contenitore IoC e tutti gli enricher registrati vengono prelevati automaticamente dai rispettivi log di telemetria, in cui arricchiscono le informazioni di telemetria.

Prerequisiti

Per funzionare correttamente, questo enricher richiede che i metadati dell'applicazione siano configurati e disponibili. I metadati dell'applicazione forniscono le informazioni di base usate dall'arricchitore per popolare le dimensioni di telemetria.

Installare il pacchetto

Per iniziare, installare il 📦 pacchetto NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

Oppure, se stai utilizzando il SDK di .NET 10+

dotnet package add Microsoft.Extensions.Telemetry

Configurazione dettagliata

Seguire questi passaggi per configurare l'arricchitore di log delle applicazioni nella tua applicazione:

1. Configurare i metadati dell'applicazione

Prima di tutto, configurare i metadati dell'applicazione chiamando i UseApplicationMetadata metodi :

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

Questo metodo preleva automaticamente i valori da IHostEnvironment e li salva nella sezione ambientmetadata:applicationdi configurazione predefinita .

In alternativa, è possibile usare il AddApplicationMetadata(IConfigurationBuilder, IHostEnvironment, String) metodo , che registra un provider di configurazione per i metadati dell'applicazione raccogliendo i valori da IHostEnvironment e aggiungendoli al nome della sezione di configurazione specificato. Quindi, usa il metodo AddApplicationMetadata(IServiceCollection, IConfigurationSection) per registrare i metadati nel contenitore di iniezione delle dipendenze, il che consente di passare IConfigurationSection separatamente.

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

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

2. Specificare una configurazione aggiuntiva (facoltativa)

È possibile fornire una configurazione aggiuntiva tramite appsettings.json. Esistono due proprietà nei metadati dell'applicazione che non ottengono automaticamente i valori: BuildVersion e DeploymentRing. Se si desidera usarli, specificare manualmente i valori:

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

Registrare l'arricchitore del registro applicazione

Registrare l'arricchimento del log nel contenitore di inserimento delle dipendenze chiamando il AddApplicationLogEnricher(IServiceCollection) metodo :

serviceCollection.AddApplicationLogEnricher();

È possibile abilitare o disabilitare singole opzioni dell'enricher:

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

Annotazioni

Se si usa .NET 9 o una versione precedente, chiamare invece il AddServiceLogEnricher(IServiceCollection) metodo .

In alternativa, configurare le opzioni usando appsettings.json:

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

Applicare quindi la configurazione.

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

Opzioni di configurazione ApplicationLogEnricherOptions

L'arricchitore di log dell'applicazione supporta diverse opzioni di configurazione tramite la classe ApplicationLogEnricherOptions.

Proprietà Valore predefinito Nome della dimensione Description
EnvironmentName true deployment.environment Nome dell'ambiente dall'ambiente di hosting o dalla configurazione
ApplicationName true service.name Nome dell'applicazione dall'ambiente di hosting o dalla configurazione
BuildVersion false service.version Versione di compilazione dalla configurazione
DeploymentRing false DeploymentRing Anello di distribuzione dalla configurazione

Per impostazione predefinita, l'arricchitore include EnvironmentName e ApplicationName nei record di log. Le BuildVersion proprietà e DeploymentRing sono disabilitate per impostazione predefinita e devono essere abilitate in modo esplicito, se necessario.

Esempio completo

Di seguito è riportato un esempio completo che illustra come configurare l'arricchimento del log applicazioni:

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();

Output del log arricchito

Con l'arricchitore di log dell'applicazione configurato, l'output del log include dimensioni specifiche del servizio:

{
  "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"
  }
}

Passaggi successivi

  • Last updated on