Freigeben über

Protokollanreicherer für Anwendungen

Der Protokollanreicherer ergänzt Telemetrieprotokolle mit anwendungsspezifischen Informationen wie Diensthostdetails und Anwendungsmetadaten. Dieser Anreicherer bietet einen wesentlichen Kontext zur Bereitstellungsumgebung, Versionsinformationen und Dienstidentität Ihrer Anwendung, die bei der Überwachung, Dembugging und der betrieblichen Sichtbarkeit hilft.

Sie können die Anreicherer in einem IoC-Container registrieren, und alle registrierten Anreicherer werden automatisch von den jeweiligen Telemetrieprotokollen aufgenommen, wo sie die Telemetrieinformationen bereichern.

Voraussetzungen

Um ordnungsgemäß zu funktionieren, erfordert dieser Anreicherer, dass Anwendungsmetadaten konfiguriert und verfügbar sind. Die Anwendungsmetadaten stellen die grundlegenden Informationen bereit, die vom Anreicherer zum Auffüllen von Telemetriedimensionen verwendet werden.

Installiere das Paket

Installieren Sie zunächst das 📦 NuGet-Paket "Microsoft.Extensions.Telemetry ":

dotnet add package Microsoft.Extensions.Telemetry

Oder, wenn Sie .NET 10+ SDK verwenden:

dotnet package add Microsoft.Extensions.Telemetry

Schrittweise Konfiguration

Führen Sie die folgenden Schritte aus, um den Protokoll-Anreicherer in Ihrer Anwendung zu konfigurieren:

1. Konfigurieren von Anwendungsmetadaten

Konfigurieren Sie zunächst die Anwendungsmetadaten , indem Sie die UseApplicationMetadata Methoden aufrufen:

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

Mit dieser Methode werden automatisch Werte aus dem IHostEnvironment Standardkonfigurationsbereich ambientmetadata:applicationabgerufen und gespeichert.

Alternativ können Sie die AddApplicationMetadata(IConfigurationBuilder, IHostEnvironment, String) Methode verwenden, die einen Konfigurationsanbieter für Anwendungsmetadaten registriert, indem Sie die Werte aus dem IHostEnvironment Angegebenen Konfigurationsabschnittsnamen abrufen und hinzufügen. Anschließend verwenden Sie die AddApplicationMetadata(IServiceCollection, IConfigurationSection) Methode, um die Metadaten im Abhängigkeitseinfügungscontainer zu registrieren, wodurch Sie separat übergeben IConfigurationSection können:

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

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

2. Bereitstellen zusätzlicher Konfiguration (optional)

Sie können eine zusätzliche Konfiguration über appsettings.json bereitstellen. Es gibt zwei Eigenschaften in den Anwendungsmetadaten , die keine Werte automatisch abrufen: BuildVersion und DeploymentRing. Wenn Sie sie verwenden möchten, geben Sie Werte manuell ein:

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

3. Registrieren des Anwendungsprotokoll-Anreicherers

Registrieren Sie den Protokollanreicherer im Container zum Einfügen von Abhängigkeiten, indem Sie die AddApplicationLogEnricher(IServiceCollection) Methode aufrufen:

serviceCollection.AddApplicationLogEnricher();

Sie können einzelne Optionen des Anreicherers aktivieren oder deaktivieren:

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

Hinweis

Wenn Sie .NET 9 oder eine frühere Version verwenden, rufen Sie stattdessen die AddServiceLogEnricher(IServiceCollection) Methode auf.

Alternativ können Sie Optionen mithilfe von appsettings.json:

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

Wenden Sie als Nächstes die Konfiguration an.

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

ApplicationLogEnricherOptions-Konfigurationsoptionen

Der Anwendungsprotokoll-Anreicherer unterstützt mehrere Konfigurationsoptionen über die ApplicationLogEnricherOptions Klasse:

Eigentum Standardwert Name der Dimension Description
EnvironmentName Wahr deployment.environment Umgebungsname aus Hostingumgebung oder Konfiguration
ApplicationName Wahr service.name Anwendungsname aus Hostingumgebung oder Konfiguration
BuildVersion Falsch service.version Build-Version basierend auf Konfiguration
DeploymentRing Falsch DeploymentRing Bereitstellungsring aus Konfiguration

Standardmäßig enthält der Enricher EnvironmentName und ApplicationName in Protokolleinträgen. Die BuildVersion- und DeploymentRing-Eigenschaften sind standardmäßig deaktiviert und müssen, falls erforderlich, explizit aktiviert werden.

Vollständiges Beispiel

Hier ist ein vollständiges Beispiel, in dem gezeigt wird, wie das Anwendungsprotokoll-Anreicherungsprogramm eingerichtet wird:

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

Erweiterte Protokollausgabe

Nachdem das Anwendungsprotokoll anreichert wurde, umfasst Ihre Protokollausgabe dienstspezifische Dimensionen:

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

Nächste Schritte

  • Last updated on