Wzbogacacz dzienników aplikacji

Wzbogacacz dzienników aplikacji rozszerza dzienniki telemetryczne o informacje specyficzne dla aplikacji, takie jak szczegóły hosta usługi i metadane aplikacji. Ten wzbogacacz udostępnia podstawowy kontekst środowiska wdrażania aplikacji, informacji o wersji i tożsamości usługi, który ułatwia monitorowanie, debugowanie i widoczność operacyjną.

Można zarejestrować wzbogacacze w kontenerze IoC, a wszystkie zarejestrowane wzbogacacze są automatycznie pobierane przez odpowiednie dzienniki telemetrii, gdzie wzbogacają informacje telemetryczne.

Wymagania wstępne

Aby prawidłowo działać, ten wzbogacacz wymaga skonfigurowania i udostępnienia metadanych aplikacji . Metadane aplikacji zawierają podstawowe informacje, których moduł wzbogacający używa do uzupełniania wymiarów telemetrii.

Instalowanie pakietu

Aby rozpocząć, zainstaluj 📦 pakiet NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

dotnet package add Microsoft.Extensions.Telemetry

<PackageReference Include="Microsoft.Extensions.Telemetry"
                  Version="*" /> <!-- Adjust version -->

Konfiguracja krok po kroku

Wykonaj następujące kroki, aby skonfigurować wzbogacacz dziennika aplikacji w aplikacji:

1. Konfigurowanie metadanych aplikacji

Najpierw skonfiguruj metadane aplikacji , wywołując UseApplicationMetadata metody:

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

Ta metoda automatycznie pobiera wartości z elementu IHostEnvironment i zapisuje je w domyślnej sekcji ambientmetadata:applicationkonfiguracji .

Alternatywnie możesz użyć AddApplicationMetadata(IConfigurationBuilder, IHostEnvironment, String) metody , która rejestruje dostawcę konfiguracji dla metadanych aplikacji, zbierając wartości z IHostEnvironment elementu i dodając je do podanej nazwy sekcji konfiguracji. Następnie używasz metody AddApplicationMetadata(IServiceCollection, IConfigurationSection) do zarejestrowania metadanych w kontenerze wstrzykiwania zależności, co umożliwia przekazanie IConfigurationSection oddzielnie.

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

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

2. Podaj dodatkową konfigurację (opcjonalnie)

Możesz podać dodatkową konfigurację za pomocą polecenia appsettings.json. W metadanych aplikacji istnieją dwie właściwości, które nie pobierają wartości automatycznie: BuildVersion i DeploymentRing. Jeśli chcesz ich używać, podaj wartości ręcznie:

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

3. Rejestrowanie wzbogacacza dziennika aplikacji

Zarejestruj wzbogacacz dziennika w kontenerze wstrzykiwania zależności, wywołując metodę AddApplicationLogEnricher(IServiceCollection) :

serviceCollection.AddApplicationLogEnricher();

Można włączyć lub wyłączyć poszczególne opcje wzbogacacza:

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

Alternatywnie skonfiguruj opcje przy użyciu polecenia appsettings.json:

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

Następnie zastosuj konfigurację.

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

ApplicationLogEnricherOptions opcje konfiguracji

Wzbogacacz dziennika aplikacji obsługuje kilka opcji konfiguracji za pomocą ApplicationLogEnricherOptions klasy :

Domyślnie wzbogacacz dodaje EnvironmentName i ApplicationName do wpisów dziennika. Właściwości BuildVersion i DeploymentRing są domyślnie wyłączone i w razie potrzeby muszą być jawnie włączone.

Kompletny przykład

Oto kompletny przykład przedstawiający sposób konfigurowania wzbogacania dziennika aplikacji:

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

Wzbogacony wynik logów

Po skonfigurowaniu wzbogacacza dziennika aplikacji dane wyjściowe dziennika obejmują wymiary specyficzne dla usługi:

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

Dalsze kroki

• Dowiedz się więcej o konfiguracji metadanych aplikacji