Logování pomocí Serilogu a Seq

24.02.2021

Logování je nedílnou součástí každé aplikace nebo systému. V tomto článku si ukážeme, jak nakonfigurovat Seq server, který umožňuje agregaci všech aplikačních logů. Díky tomu můžeme logy snadno procházet a rychle identifikovat například chyby nebo pomalé požadavky.

Slovníček

ASP.NET Core Open-source webový framework od Microsoftu (první release 2016).
Serilog Populární knihovna pro logování v .NET aplikacích, podporující strukturované logy.
Seq Komerční profesionální nástroj pro monitorování logů od společnosti Datalust.

Obsah

Úvod

Nejprve nainstalujeme Seq server, který bude naslouchat na localhostu. Následně vygenerujeme aplikační klíč sloužící k autorizaci. Nakonec vytvoříme jednoduchou ASP.NET Core aplikaci, ve které nakonfigurujeme Serilog a nastavíme odesílání logů na Seq server. Konfiguraci Serilogu budeme načítat ze souboru appsettings.json, což nám umožní za běhu měnit úroveň logování (log level). Autorizační klíč načteme z environment proměnných (v našem případě na IIS serveru), aby se nedostal do verzovacího systému.

Nastavení Seq

Proces instalace je jednoduchý. Stačí stáhnout instalační balíček, spustit instalaci a zvolit, zda chcete konfiguraci služby provést pomocí průvodce (wizardu). Pokud ne, můžete konfiguraci kdykoliv provést nebo později upravit pomocí příkazu seq, který umožňuje také přeinstalaci služby. Během konfigurace lze nastavit

  • URL adresu, na které bude služba naslouchat.
  • Cestu k úložišti logů.
  • SSL thumbprint.
  • Administrátorské jméno s heslem.
Ve výchozím nastavení je konfigurační soubor Seq.json uložen ve složce C:\ProgramData\Seq, kde se nacházejí i uložená data.

Vygenerování aplikačního klíče

Otevřeme Seq ve webovém prohlížeči a přejdeme do záložky settings > API Keys, kterou najdeme na adrese http://localhost:5341/#/settings/api-keys. Zde zaškrtneme možnost vyžadovat autorizaci před přijetím jakýchkoliv logů serverem.

V opačném případě můžeme alternativně nastavit výchozí Unauthenticated API key v záložce Data > Ingestion. K tomuto klíči lze přidat Applied properties, například s hodnotou Application:Unauthenticated. Tato hodnota má přednost před informacemi odesílanými Serilogem a umožňuje podle ní filtrovat logy. Díky tomu lze snadno rozlišit jednotlivé aplikace (například autorizované od neautorizovaných).
Vygenerujeme klíč pomocí tlačítka-formuláře Add API Key. Zadáme název aplikace, například „WebApp“, a přidáme proměnnou Application:WebApp, která bude automaticky připojena ke všem logům. Po dokončení se nám vygenerovaný klíč zobrazí v modálním okně.

Nastavení IIS

Aby si aplikace mohla načíst autorizační klíč z environment proměnných, můžeme klíč nastavit přímo v IIS. Jak nastavit proměnnou popisuji v předchozím článku. Naše proměnná musí být v souladu se Serilog nastavením, které budeme mít v appsettings.json configu. Info jak nastavit proměnnou, aby se načetla v rámci správné sekce appsettings souboru, najdeme v dokumentaci. V našem případě je to Serilog__WriteTo__0__Args_apiKey.

Nastavení Serilogu

V ASP.NET Core aplikaci nainstalujeme knihovnu Serilog s podporou Seq pomocí balíčkovacího nástroje NuGet. 

Install-Package Serilog.AspNetCore
Install-Package Serilog.Sinks.Seq -DependencyVersion Highest
V souboru Program.cs upravíme metodu IHostBuilder, ve které nastavíme Serilog jako poskytovatele logů. 
public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .UseSerilog(
                    (context, services, configuration) =>
                    {
                        configuration
                        // Load serilog section from appsettings.json
                        // https://github.com/serilog/serilog-settings-configuration
                        .ReadFrom.Configuration(context.Configuration)
                        // Enable pushing properties
                        // https://github.com/serilog/serilog-aspnetcore#pushing-properties-to-the-iloggert
                        .Enrich.FromLogContext();
                    })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });

Hlavní nastavení se nachází v již zmíněném konfiguračním souboru appsettings.json. V tomto souboru nahradíme sekci Logging sekcí Serilog. Konfigurace Seq musí být uvedena na první pozici v sekci WriteTo, protože jsme environment proměnnou nastavili jako Serilog__WriteTo__0__Args_apiKey. 

"Serilog": {
  "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.Seq" ],
  "MinimumLevel": "Information",
  "WriteTo": [
    {
      "Name": "Seq",
      "Args": {
        "serverUrl": "http://localhost:5341",
        // We can change log level in runtime when needed.
        "restrictedToMinimumLevel": "Information",
        // Api key is loaded from IIS environment variables storage.
        // For local development, key should be in secrets.json.
        // https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-5.0&tabs=windows
        // "apiKey": "iBR56916yONxYlN4dAIr"
      }
    },
    {
      "Name": "Console",
      "args": {
        "restrictedToMinimumLevel": "Error"
      }
    }
  ],
  "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
  // We set application name property already in Seq API key settings.
  //"Properties": {
  //  "Application": "WebApp"
  //}
}

V souboru Starup.cs v metodě Configure si můžeme donastavit Serilog konfiguraci a můžeme si například do všech logů přidat proměnné Environment a User. 

// Customizing what to log
// https://github.com/serilog/serilog-aspnetcore#request-logging
app.UseSerilogRequestLogging(options =>
{
    // Attach additional properties to the request completion event
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("Environment", Environment.EnvironmentName);
        diagnosticContext.Set("User", httpContext.User.Identity.Name);
    };
});

Závěr

Nyní máme již vše připravené. Po vypublikování aplikace na IIS server by se měly logy začít zobrazovat na Seq serveru, kde si je můžeme jednoduše filtrovat podle potřeby. Případný alerting si můžeme nastavit podle dokumentace.

Odkazy