Protokolování v .NET Core a ASP.NET Core

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Autoři: Kirk Larkin, Juergen Gutsch a Rick Anderson

Tento článek popisuje protokolování v .NET, protože se vztahuje na aplikace ASP.NET Core. Podrobné informace o protokolování v .NET najdete v tématu Protokolování v .NET.

Pokyny Blazor k protokolování, které přidávají nebo nahrazují pokyny v tomto uzlu, najdete v tématu ASP.NET Protokolování jádraBlazor.

Zprostředkovatelé protokolování

Zprostředkovatelé protokolování uchovávají protokoly, kromě zprostředkovatele Console, který protokoly pouze zobrazuje. Například zprostředkovatel Azure Application Insights uchovává protokoly v Azure Application Insights. Je možné povolit více zprostředkovatelů.

Výchozí volání šablon WebApplication.CreateBuilderwebových aplikací ASP.NET Core, které přidává následující zprostředkovatele protokolování:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Výše uvedený kód ukazuje vytvoření souboru Program.cs s využitím šablon webových aplikací ASP.NET Core. V následujících několika částech najdete ukázky založené na šablonách webové aplikace ASP.NET Core.

Následující kód přepíše výchozí sadu zprostředkovatelů protokolování přidanou metodou WebApplication.CreateBuilder:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Výše uvedený kód protokolování je případně možné zapsat následovně:

var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

Informace o dalších zprostředkovatelích najdete tady:

Vytváření protokolů

K vytváření protokolů použijte objekt ILogger<TCategoryName> z injektáže závislostí (DI).

Následující příklad:

  • Vytvoří protokolovací nástroj ILogger<AboutModel>, který jako kategorii protokolu používá plně kvalifikovaný název typu AboutModel. Kategorie protokolu je řetězec přidružený k jednotlivým protokolům.
  • Volá metodu LogInformation, která protokoluje na úrovni Information. Úroveň protokolování označuje závažnost protokolované události.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("About page visited at {DT}", 
            DateTime.UtcNow.ToLongTimeString());
    }
}

Úrovním a kategoriím se podrobněji věnujeme dále v tomto dokumentu.

Informace o architektuře Blazor najdete v tématu Protokolování ASP.NET Core Blazor.

Konfigurace protokolování

Konfigurace protokolování se obvykle zadává v oddílu Logging souborů appsettings.{ENVIRONMENT}.json, kde zástupný symbol {ENVIRONMENT} je název prostředí. Šablony webových aplikací ASP.NET Core generují následující soubor appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

V předchozím fragmentu kódu JSON:

  • Jsou zadané kategorie "Default" a "Microsoft.AspNetCore".
  • Kategorie "Microsoft.AspNetCore" se vztahuje na všechny kategorie, které začínají na "Microsoft.AspNetCore". Toto nastavení se například vztahuje i na kategorii "Microsoft.AspNetCore.Routing.EndpointMiddleware".
  • Kategorie "Microsoft.AspNetCore" zajišťuje protokolování na úrovni protokolování Warning nebo vyšší.
  • Není zadaný žádný konkrétní zprostředkovatel protokolování, takže se vlastnost LogLevel vztahuje na všechny povolené zprostředkovatele protokolování s výjimkou zprostředkovatele Windows EventLog.

Vlastnost Logging může obsahovat vlastnost LogLevel a vlastnosti zprostředkovatele protokolování. Vlastnost LogLevel určuje minimální úroveň protokolování pro vybrané kategorie. V předchozím kódu JSON Information a Warning úrovně protokolu jsou zadané. Vlastnost LogLevel označuje závažnost protokolu v rozsahu od 0 do 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 a None = 6.

Když je zadaná vlastnost LogLevel, protokolování se povolí pro zprávy na zadané úrovni a vyšší. V předchozím kódu JSON Default se kategorie zaprotokoluje a Information je vyšší. Protokolují se například zprávy úrovně Information, Warning, Error a Critical. Pokud není zadaná žádná vlastnost LogLevel, nastaví se výchozí úroveň protokolování Information. Další informace najdete v části Úrovně protokolování.

Vlastnost LogLevel může být zadaná ve vlastnosti zprostředkovatele. Vlastnost LogLevel v rámci zprostředkovatele určuje úrovně protokolování pro daného zprostředkovatele a přepisuje nastavení protokolování pro všechny zprostředkovatele. Vezměme například následující soubor appsettings.json:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Nastavení ve vlastnosti Logging.{PROVIDER NAME}.LogLevel, kde zástupný symbol {PROVIDER NAME} je název zprostředkovatele, přepíše nastavení ve vlastnosti Logging.LogLevel. V předchozím kódu JSON Debug je výchozí úroveň protokolu poskytovatele nastavená na Information:

Logging:Debug:LogLevel:Default:Information

Výše uvedené nastavení určuje úroveň protokolování Information pro všechny kategorie Logging:Debug: s výjimkou kategorie Microsoft.Hosting. Pokud je uvedená konkrétní kategorie, tato konkrétní kategorie přepíše výchozí kategorii. V předchozím kódu JSON Logging:Debug:LogLevel kategorie "Microsoft.Hosting" a "Default" přepsání nastavení v Logging:LogLevelsouboru .

Minimální úroveň protokolování je možné zadat pro:

  • Konkrétní zprostředkovatele: například Logging:EventSource:LogLevel:Default:Information
  • Konkrétní kategorie: například Logging:LogLevel:Microsoft:Warning
  • Všechny zprostředkovatele a všechny kategorie: Logging:LogLevel:Default:Warning

Žádné protokoly pod minimální úrovní se:

  • Nepředávají zprostředkovateli.
  • Neprotokolují ani nezobrazují.

Pokud chcete potlačit všechny protokoly, zadejte LogLevel.None. Vlastnost LogLevel.None má hodnotu 6, která je vyšší než hodnota vlastnosti LogLevel.Critical (5).

Pokud zprostředkovatel podporuje obory protokolování, vlastnost IncludeScopes označuje, jestli jsou povolené. Další informace najdete v části Obory protokolování.

Následující soubor appsettings.json obsahuje ve výchozím nastavení povolené všechny zprostředkovatele:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Ve výše uvedené ukázce:

  • Kategorie a úrovně nejsou navrhované hodnoty. Ukázka je k dispozici, aby se zobrazili všichni výchozí zprostředkovatelé.
  • Nastavení ve vlastnosti Logging.{PROVIDER NAME}.LogLevel, kde zástupný symbol {PROVIDER NAME} je název zprostředkovatele, přepíše nastavení ve vlastnosti Logging.LogLevel. Například úroveň ve vlastnosti Debug.LogLevel.Default přepíše úroveň ve vlastnosti LogLevel.Default.
  • Používá se alias všech výchozích zprostředkovatelů. Každý zprostředkovatel definuje alias, který je možné použít v konfiguraci místo plně kvalifikovaného názvu typu. Předdefinované aliasy poskytovatelů jsou:
    • Console
    • Debug
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Protokolování v souboru Program.cs

Následující příklad v souboru Program.cs volá objekt Builder.WebApplication.Logger a protokoluje informační zprávy:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Logger.LogInformation("Adding Routes");
app.MapGet("/", () => "Hello World!");
app.Logger.LogInformation("Starting the app");
app.Run();

Následující příklad v souboru Program.cs volá metodu AddConsole a protokoluje koncový bod /Test:

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Následující příklad v souboru Program.cs volá metodu AddSimpleConsole, zakazuje barevný výstup a protokoluje koncový bod /Test:

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Nastavení úrovně protokolování pomocí příkazového řádku, proměnných prostředí a další konfigurace

Úroveň protokolování může nastavit jakýkoli zprostředkovatel konfigurace.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Bash například : nepodporuje oddělovač. Dvojité podtržítko je __:

  • Podporuje všemi platformami.
  • Automaticky nahrazen dvojtečka, :.

Následující příkazy:

  • Nastaví klíč prostředí Logging:LogLevel:Microsoft ve Windows na hodnotu Information.
  • Otestují nastavení při použití aplikace vytvořené s využitím šablon webových aplikací ASP.NET Core. Po použití příkazu set se musí v adresáři projektu spustit příkaz dotnet run.
set Logging__LogLevel__Microsoft=Information
dotnet run

Výše uvedené nastavení prostředí se:

  • Nastaví pouze v procesech spuštěných z příkazového okna, ve kterém byly nastavené.
  • Nenačte v prohlížečích spuštěných pomocí sady Visual Studio.

Následující příkaz setx také nastaví klíč prostředí a jeho hodnotu ve Windows. Na rozdíl od příkazu set se nastavení příkazu setx zachovají. Přepínač /M nastaví proměnnou v systémovém prostředí. Pokud se nepoužije přepínač /M, nastaví se proměnná uživatelského prostředí.

setx Logging__LogLevel__Microsoft Information /M

Vezměme například následující soubor appsettings.json:

"Logging": {
  "Console": {
    "LogLevel": {
      "Microsoft.Hosting.Lifetime": "Trace"
    }
  }
}

Následující příkaz nastaví v prostředí výše uvedenou konfiguraci:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Poznámka:

Při konfiguraci proměnných prostředí s názvy, které obsahují . (tečky) v systému macOS a Linux, zvažte možnost "Export proměnné tečkou (.) v ní" otázka na Stack Exchange a odpovídající přijatá odpověď.

V Azure App Service vyberte Nové nastavení aplikace na stránce Nastavení > Konfigurace. Nastavení aplikace Azure App Service se:

  • Zašifrováno a přenášeno rest přes šifrovaný kanál.
  • Vystavují jako proměnné prostředí.

Další informace najdete v tématu Aplikace Azure: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Další informace o nastavení hodnot konfigurace ASP.NET Core pomocí proměnných prostředí najdete v části Proměnné prostředí. Informace o používání dalších zdrojů konfigurace, včetně příkazového řádku, služby Azure Key Vault, služby Azure App Configuration, jiných formátů souborů a dalších, najdete v tématu Konfigurace v ASP.NET Core.

Uplatňování pravidel filtrování

Když se vytvoří objekt ILogger<TCategoryName>, objekt ILoggerFactory vybere pro každého zprostředkovatele jedno pravidlo, které se použije na daný protokolovací nástroj. Všechny zprávy zapsané instancí ILogger se filtrují na základě vybraných pravidel. Pro každou dvojici zprostředkovatele a kategorie se z dostupných pravidel vybere nejkonkrétnější pravidlo.

Při vytvoření objektu ILogger pro danou kategorii se u každého zprostředkovatele použije následující algoritmus:

  • Vyberou se všechna pravidla, která odpovídají zprostředkovateli nebo jeho aliasu. Pokud se nenajde žádná shoda, vyberou se všechna pravidla s neuvedeným zprostředkovatelem.
  • Z výsledku předchozího kroku se vyberou pravidla s nejdelší shodou předpony kategorie. Pokud se nenajde žádná shoda, vyberou se všechna pravidla, která neuvádějí kategorii.
  • Pokud je vybraných více pravidel, vybere se poslední pravidlo.
  • Pokud nejsou vybraná žádná pravidla, použije se pravidlo MinimumLevel.

Protokolování výstupu z příkazu dotnet run a sady Visual Studio

Protokoly vytvořené pomocí výchozích zprostředkovatelů protokolování se zobrazují:

  • V sadě Visual Studio
    • V okně Výstup ladění při ladění
    • V okně Webový server ASP.NET Core
  • V okně konzoly při spuštění aplikace pomocí příkazu dotnet run

Protokoly, které začínají kategoriemi Microsoftu, pocházejí z .NET. Kód rozhraní .NET a aplikace používají stejné rozhraní API a zprostředkovatele protokolování.

Kategorie protokolu

Při vytvoření objektu ILogger se určí kategorie. Tato kategorie je součástí každé zprávy protokolu vytvořené danou instancí ILogger. Řetězec kategorie je libovolný, ale konvence je použít plně kvalifikovaný název třídy. Například v kontroleru může název být "TodoApi.Controllers.TodoController". Webové aplikace ASP.NET Core používají ILogger<T> k automatickému získání instance ILogger, která jako kategorii používá plně kvalifikovaný název typu T:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Pokud je požadovaná další kategorizace, je konvence použít hierarchický název připojením podkategorie k plně kvalifikovanému názvu třídy a explicitně zadat kategorii pomocí ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Volání metody CreateLogger s pevně daným názvem může být užitečné při použití ve více metodách, aby bylo možné události uspořádat podle kategorie.

Výraz ILogger<T> je ekvivalentní volání metody CreateLogger s plně kvalifikovaným názvem typu T.

Úroveň protokolu

Následující tabulka uvádí hodnoty vlastnosti LogLevel, vhodnou rozšiřující metodu Log{LogLevel} a navrhované použití:

ÚroveňProtokolu Hodnota metoda Popis
Trace 0 LogTrace Obsahuje nejpodrobnější zprávy. Tyto zprávy můžou obsahovat citlivá data aplikace. Tyto zprávy jsou ve výchozím nastavení zakázané a neměly by se povolovat v produkčním prostředí.
Debug 0 LogDebug Slouží pro účely ladění a vývoje. Vzhledem k velkému objemu používejte tuto úroveň opatrně v produkčním prostředí.
Information 2 LogInformation Sleduje obecný tok aplikace. Může mít dlouhodobou hodnotu.
Warning 3 LogWarning Slouží k protokolování neobvyklých nebo neočekávaných událostí. Obvykle zahrnuje chyby nebo podmínky, které nezpůsobují selhání aplikace.
Error 4 LogError Slouží k protokolování chyb a výjimek, které není možné zpracovat. Tyto zprávy značí selhání v aktuální operaci nebo požadavku, nikoli selhání na úrovni aplikace.
Critical 5 LogCritical Slouží k protokolování událostí, které vyžadují okamžitou pozornost. Příklady: scénáře ztráty dat, nedostatek místa na disku.
None 6 Určuje, že kategorie protokolování nemá zapisovat zprávy.

Ve výše uvedené tabulce jsou hodnoty vlastnosti LogLevel uvedené v pořadí od nejnižší po nejvyšší závažnost.

První parametr metody Log, LogLevel, označuje závažnost protokolu. Většina vývojářů místo volání metody Log(LogLevel, ...) volá rozšiřující metody Log{LOG LEVEL}, kde zástupný symbol {LOG LEVEL} je úroveň protokolování. Například následující dvě volání protokolování jsou funkčně ekvivalentní a generují stejné protokoly:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem je ID události. MyLogEvents je součástí ukázkové aplikace a zobrazuje se v části ID události protokolu.

Metody MyDisplayRouteInfo a ToCtxString poskytuje balíček NuGet Rick.Docs.Samples.RouteInfo. Tyto metody zobrazují informace o trasách Controller a Razor Page.

Následující kód vytvoří protokoly Information a Warning:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

První parametr metody Log{LOG LEVEL}, MyLogEvents.GetItem, ve výše uvedeném kódu je ID události protokolu. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů, které poskytují zbývající parametry metody. Vysvětlení parametrů metody najdete v části věnované šabloně zprávy dále v tomto dokumentu.

Voláním vhodné metody Log{LOG LEVEL} můžete řídit, jak velký výstup protokolování se bude zapisovat na konkrétní úložné médium. Příklad:

  • V produkčním prostředí:
    • Protokolování na Traceúrovni , Debugnebo Information vytváří velký objem podrobných zpráv protokolu. Řízení nákladů a překročení limitů úložiště dat, protokolů TraceDebugnebo Information zpráv na úrovni do úložiště dat s velkým objemem a nízkými náklady. Zvažte omezení Trace, Debugnebo Information konkrétní kategorie.
    • Protokolování na úrovni Warning až Critical by mělo generovat malé množství zpráv protokolu.
      • Náklady a limity úložiště obvykle nepředstavují problém.
      • Malé množství protokolů znamená větší flexibilitu při výběru úložiště dat.
  • Ve vývoji:
    • Nastavte na Warning.
    • Přidejte Trace, Debugnebo Information zprávy při řešení potíží. Pokud chcete omezit výstup, nastavte Trace, Debugnebo Information pouze pro kategorie, které jsou prošetřené.

ASP.NET Core zapisuje protokoly pro události architektury. Podívejte se například na výstup protokolu s následujícími informacemi:

  • Vytvoření aplikace Razor Pages s využitím šablon ASP.NET Core
  • Nastavení protokolování na úrovni Logging:Console:LogLevel:Microsoft:Information
  • Přechod na stránku Privacy:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Následující sady Logging:Console:LogLevel:Microsoft:InformationJSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID události protokolu

Každý protokol může uvádět ID události. V ukázkové aplikaci se k definování ID událostí používá třída MyLogEvents:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

ID události spojuje sadu událostí. Například všechny protokoly související se zobrazením seznamu položek na stránce můžou mít ID 1001.

Zprostředkovatel protokolování může uchovávat ID události v poli ID, ve zprávě protokolování nebo ho nemusí uchovávat vůbec. Zprostředkovatel Debug nezobrazuje ID událostí. Zprostředkovatel Console zobrazuje ID událostí v závorkách za kategorií:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Někteří zprostředkovatelé protokolování uchovávají ID událostí v poli, což umožňuje filtrování podle ID.

Šablona zprávy protokolu

Každé rozhraní API pro protokoly používá šablony zprávy. Šablona zprávy může obsahovat zástupné symboly, pro které se poskytnou argumenty. Jako zástupné symboly používejte názvy, a ne čísla.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Pořadí parametrů, nikoli názvy zástupných symbolů, určuje, které parametry se použijí k zadání hodnot zástupných symbolů ve zprávách protokolu. V následujícím kódu mají v šabloně zprávy názvy parametrů jiné pořadí než zástupné symboly:

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {Pears}, {Bananas}, {Apples}", apples, pears, bananas);

Parametry se však přiřadí zástupným symbolům v tomto pořadí: apples, pears, bananas. Zpráva protokolu odráží pořadí parametrů:

Parameters: 1, 2, 3

Tento přístup umožňuje zprostředkovatelům protokolování implementovat sémantické neboli strukturované protokolování. Do systému protokolování se předávají samotné argumenty, nikoli pouze formátovaná šablona zprávy. To umožňuje zprostředkovatelům protokolování uchovávat hodnoty parametrů jako pole. Podívejte se například na následující metodu protokolovacího nástroje:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Například při protokolování do služby Azure Table Storage:

  • Každá entita tabulky Azure může mít vlastnosti ID a RequestTime.
  • Tabulky s vlastnostmi zjednodušují dotazy na protokolovaná data. Dotaz může například vyhledat všechny protokoly v určitém rozsahu hodnot RequestTime, aniž by musel parsovat čas z textové zprávy.

Výjimky protokolu

Metody protokolovacího nástroje obsahují přetížení, která jako parametr přebírají výjimku:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

Metody MyDisplayRouteInfo a ToCtxString poskytuje balíček NuGet Rick.Docs.Samples.RouteInfo. Tyto metody zobrazují informace o trasách Controller a Razor Page.

Protokolování výjimek se u jednotlivých zprostředkovatelů liší.

Výchozí úroveň protokolování

Pokud není nastavená výchozí úroveň protokolování, má výchozí úroveň protokolování hodnotu Information.

Podívejte se například na následující webovou aplikaci:

  • Aplikace je vytvořená s využitím šablon webových aplikací ASP.NET.
  • Soubory appsettings.json a appsettings.Development.json se odstranily nebo přejmenovaly.

Při předchozím nastavení se při přechodu na privacy stránku vytvoří home mnoho TraceDebug, a Information zprávy s Microsoft názvem kategorie.

Následující kód nastaví výchozí úroveň protokolování, pokud není nastavená v konfiguraci:

var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

Obecně platí, že by se úrovně protokolování měly zadávat v konfiguraci, a ne v kódu.

Funkce filtru

Funkce filtru se volá pro všechny zprostředkovatele a kategorie, ke kterým nejsou v konfiguraci nebo kódu přiřazená pravidla:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Controller")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Microsoft")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else
    {
        return false;
    }
});

Výše uvedený kód zobrazí protokoly konzoly v případě, že kategorie obsahuje Controller nebo Microsoft a úroveň protokolování je Information nebo vyšší.

Obecně platí, že by se úrovně protokolování měly zadávat v konfiguraci, a ne v kódu.

Kategorie ASP.NET Core

Následující tabulka obsahuje některé kategorie používané ASP.NET Core.

Kategorie Notes
Microsoft.AspNetCore Obecná diagnostika ASP.NET Core.
Microsoft.AspNetCore.DataProtection Informace o zvažovaných, nalezených a použitých klíčích.
Microsoft.AspNetCore.HostFiltering Informace o povolených hostitelích.
Microsoft.AspNetCore.Hosting Informace o tom, kdy se zahájily požadavky HTTP a jak dlouho trvalo jejich dokončení. Informace o načtených hostujících spouštěcích sestavení.
Microsoft.AspNetCore.Mvc Diagnostika MVC a Razor. Informace o vazbě modelu, spuštění filtru, kompilaci zobrazení a výběru akce.
Microsoft.AspNetCore.Routing Informace o porovnávání tras.
Microsoft.AspNetCore.Server Informace o zahájení a ukončení připojení a odpovědích pro zachování připojení. Informace o certifikátu HTTPS.
Microsoft.AspNetCore.StaticFiles Informace o obsluhovaných souborech.

Pokud chcete v okně konzoly zobrazit další kategorie, nastavte soubor appsettings.Development.json následovně:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Seznam kategorií entity Framework najdete v tématu Kategorie zpráv EF.

Obory protokolování

Obor může seskupovat sadu logických operací. Toto seskupení je možné využít k připojení stejných dat ke všem protokolům vytvořeným v rámci sady. Například všechny protokoly vytvořené v rámci zpracování transakce můžou obsahovat ID transakce.

Obor:

Obory podporují následující zprostředkovatelé:

Obor můžete použít tak, že zabalíte volání protokolovacího nástroje do bloku using:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Předdefinovaní zprostředkovatelé protokolování

ASP.NET Core jako součást sdílené architektury obsahuje následující zprostředkovatele protokolování:

Microsoft dodává následující zprostředkovatele protokolování, kteří však nejsou součástí sdílené architektury. Musí se nainstalovat jako další balíček NuGet.

ASP.NET Core neobsahuje žádného zprostředkovatele protokolování pro zápis protokolů do souborů. Pokud chcete v aplikaci ASP.NET Core zapisovat protokoly do souborů, zvažte použití zprostředkovatele protokolování třetí strany.

Informace o výstupu stdout a protokolování ladění s využitím modulu ASP.NET Core najdete v tématech Řešení potíží s ASP.NET Core v Azure App Service a ve službě IIS a Modul ASP.NET Core (ANCM) pro službu IIS.

Konzola

Zprostředkovatel Console protokoluje výstup do konzoly. Další informace o zobrazení protokolů Console při vývoji najdete v části Protokolování výstupu z příkazu dotnet run a sady Visual Studio.

Ladění

Zprostředkovatel Debug zapisuje výstup protokolování s využitím třídy System.Diagnostics.Debug. Do zprostředkovatele Debug se zapisuje voláním metody System.Diagnostics.Debug.WriteLine.

V Linuxu závisí umístění protokolu zprostředkovatele Debug na konkrétní distribuci a může se jednat o jedno z následujících umístění:

  • /var/log/message
  • /var/log/syslog

Zdroj události

Zprostředkovatel EventSource zapisuje do multiplatformního zdroje událostí s názvem Microsoft-Extensions-Logging. Ve Windows tento zprostředkovatel využívá Trasování událostí pro Windows.

nástroje dotnet-trace

Nástroj dotnet-trace je globální multiplatformní nástroj rozhraní příkazového řádku, který umožňuje shromažďování trasování .NET Core spuštěných procesů. Tento nástroj shromažďuje data zprostředkovatele Microsoft.Extensions.Logging.EventSource s využitím třídy LoggingEventSource.

Pokyny k instalaci najdete tady: dotnet-trace.

Použití nástroje dotnet-trace ke shromáždění trasování z aplikace:

  1. Spusťte aplikaci pomocí příkazu dotnet run.

  2. Zjistěte identifikátor procesu (PID) aplikace .NET Core:

    dotnet-trace ps

    Vyhledejte PID procesu se stejným názvem jako sestavení aplikace.

  3. Spusťte příkaz dotnet-trace.

    Obecná syntaxe příkazu:

    dotnet-trace collect -p {PID} 
    --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"

    Pokud používáte příkazové prostředí PowerShellu, uzavřete hodnotu parametru --providers do jednoduchých uvozovek ('):

    dotnet-trace collect -p {PID} 
    --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"'

    Na jiných platformách než Windows přidáním možnosti -f speedscope změňte formát výstupního trasovacího souboru na speedscope.

    Následující tabulka definuje hodnotu Keyword:

    Klíčové slovo Popis
    1 Protokoluje metadata událostí souvisejících s třídou LoggingEventSource. Neprotokoluje události z rozhraní ILogger.
    2 Při zavolání metody ILogger.Log() zapne událost Message. Poskytuje programové (neformátované) informace.
    4 Při zavolání metody ILogger.Log() zapne událost FormatMessage. Poskytuje informace v podobě formátovaného řetězce.
    8 Při zavolání metody ILogger.Log() zapne událost MessageJson. Poskytuje reprezentaci argumentů ve formátu JSON.

    Následující tabulka uvádí úrovně zprostředkovatele:

    Úroveň zprostředkovatele Popis
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Úroveň kategorie se může parsovat na základě řetězce nebo čísla:

    Pojmenovaná hodnota kategorie Číselná hodnota
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Úroveň zprostředkovatele a úroveň kategorie:

    • Jsou v obráceném pořadí.
    • Řetězcové konstanty nejsou všechny identické.

    Pokud nejsou zadané žádné položky FilterSpecs, implementace EventSourceLogger se pokusí převést úroveň zprostředkovatele na úroveň kategorie, kterou použije pro všechny kategorie.

    Úroveň zprostředkovatele Úroveň kategorie
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Pokud jsou zadané položky FilterSpecs, pro všechny kategorie na seznamu se použije zakódovaná kategorie a všechny ostatní kategorie se odfiltrují.

    V následujících příkladech se předpokládá, že:

    • Aplikace je spuštěná a volá metodu logger.LogDebug("12345").
    • ID procesu (PID) se nastavilo prostřednictvím set PID=12345, kde 12345 je skutečné PID.

    Zvažte použití následujícího příkazu:

    dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5

    Předchozí příkaz:

    • Zachytává zprávy ladění.
    • Nepoužívá položky FilterSpecs.
    • Určuje úroveň 5, která se mapuje na kategorii Debug (Ladění).

    Zvažte použití následujícího příkazu:

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"

    Předchozí příkaz:

    • Nezachytává zprávy ladění, protože kategorie úrovně 5 je Critical.
    • Poskytuje položky FilterSpecs.

    Následující příkaz zachytává zprávy ladění, protože kategorie úrovně 1 je Debug.

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"

    Následující příkaz zachytává zprávy ladění, protože kategorie je Debug.

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"

    Položky FilterSpecs pro {Logger Category} a {Category Level} představují další podmínky filtrování protokolů. K oddělení položek FilterSpecs použijte znak středníku (;).

    Příklad s použitím příkazového prostředí Windows:

    dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"

    Výše uvedený příkaz aktivuje:

    • Protokolovací nástroj zdroje událostí, který generuje formátované řetězce (4) v případě chyb (2).
    • Protokolování Microsoft.AspNetCore.Hosting na úrovni protokolování Informational (4).

  4. dotnet-trace Zastavte nástroje stisknutím klávesy Enter nebo Ctrl+C.

    Trasování se uloží s názvem trace.nettrace ve složce, ve které se spustil příkaz dotnet-trace.

  5. Otevřete trasování v nástroji PerfView. Otevřete soubor trace.nettrace a prozkoumejte události trasování.

Pokud aplikace nesestaví hostitele pomocí metody WebApplication.CreateBuilder, přidejte do konfigurace protokolování aplikace zprostředkovatele zdroje událostí.

Další informace naleznete v tématu:

PerfView

Pomocí nástroje PerfView můžete shromažďovat a zobrazovat protokoly. Protokoly Trasování událostí pro Windows je možné zobrazit i v jiných nástrojích, ale PerfView nabízí nejlepší prostředí pro práci s událostmi Trasování událostí pro Windows, které generuje ASP.NET Core.

Pokud chcete nástroj PerfView nakonfigurovat tak, aby shromažďoval události protokolované tímto zprostředkovatelem, přidejte na seznam Additional Providers (Další zprostředkovatelé) řetězec *Microsoft-Extensions-Logging. Nevynechejte znak * na začátku řetězce.

Windows EventLog

Zprostředkovatel EventLog odesílá výstup protokolování do protokolu událostí Windows. Na rozdíl od ostatních zprostředkovatelů zprostředkovatel EventLog nedědí výchozí nastavení pro všechny zprostředkovatele. Pokud není zadané nastavení protokolování EventLog, použije se výchozí nastavení LogLevel.Warning.

Pokud chcete protokolovat události nižší úrovně než LogLevel.Warning, nastavte úroveň protokolování explicitně. Následující příklad nastaví výchozí úroveň protokolování do protokolu událostí na LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Přetížení AddEventLog přijímá parametr EventLogSettings. Pokud má tento parametr hodnotu null nebo není nastavený, použije se následující výchozí nastavení:

  • LogName: "Application"
  • SourceName: ".NET Runtime"
  • MachineName: Použije se název místního počítače.

Následující kód změní vlastnost SourceName z výchozí hodnoty ".NET Runtime" na hodnotu MyLogs:


var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "MyLogs";
});

Azure App Service

Balíček zprostředkovatele Microsoft.Extensions.Logging.AzureAppServices zapisuje protokoly do textových souborů v systému souborů aplikace Azure App Service a do úložiště objektů blob v účtu služby Azure Storage.

Tento balíček zprostředkovatele není součástí sdílené architektury. Pokud chcete tohoto zprostředkovatele použít, přidejte do projektu balíček zprostředkovatele.

Ke konfiguraci nastavení zprostředkovatele použijte třídy AzureFileLoggerOptions a AzureBlobLoggerOptions, jak je znázorněno v následujícím příkladu:

using Microsoft.Extensions.Logging.AzureAppServices;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

Když se aplikace nasadí v Azure App Service, používá nastavení v části Protokoly App Service na stránce App Service na webu Azure Portal. Pokud se upraví následující nastavení, změny se projeví okamžitě bez nutnosti aplikaci restartovat nebo nasadit znovu.

  • Protokolování aplikace (systém souborů)
  • Protokolování aplikace (objekt blob)

Výchozí umístění souborů protokolu je ve složce D:\\home\\LogFiles\\Application a výchozí název souboru je diagnostics-yyyymmdd.txt. Výchozí limit velikosti souboru je 10 MB a výchozí maximální počet uchovávaných souborů je 2. Výchozí název objektu blob je {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Tento zprostředkovatel provádí protokolování pouze v případě, že projekt běží v prostředí Azure.

Streamování protokolů Azure

Streamování protokolů Azure podporuje zobrazení aktivity protokolování v reálném čase z následujících zdrojů:

  • Aplikační server
  • Webový server
  • Trasování neúspěšných požadavků

Konfigurace streamování protokolů Azure:

  • Na stránce aplikace na portálu přejděte na stránku Protokoly App Service.
  • Nastavte možnost Protokolování aplikace (systém souborů) na hodnotu Zapnuto.
  • Zvolte Úroveň protokolování. Toto nastavení se vztahuje pouze na streamování protokolů Azure.

Pokud chcete zobrazit protokoly, přejděte na stránku Stream protokolů. Protokolované zprávy se protokolují s využitím rozhraní ILogger.

Azure Application Insights

Balíček zprostředkovatele Microsoft.Extensions.Logging.ApplicationInsights zapisuje protokoly do Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a nabízí nástroje pro dotazování a analýzu telemetrických dat. Pokud použijete tohoto zprostředkovatele, můžete dotazovat a analyzovat protokoly pomocí nástrojů Application Insights.

Tento zprostředkovatel protokolování je jako závislost součástí balíčku Microsoft.ApplicationInsights.AspNetCore, který poskytuje veškerou dostupnou telemetrii pro ASP.NET Core. Pokud tento balíček používáte, nemusíte instalovat balíček zprostředkovatele.

Balíček Microsoft.ApplicationInsights.Web je určený pro ASP.NET 4.x, a ne pro ASP.NET Core.

Další informace naleznete v následujících zdrojích:

Zprostředkovatelé protokolování třetích stran

Architektury protokolování třetích stran, které fungují s ASP.NET Core:

Některé architektury třetích stran můžou provádět sémantické protokolování, označované také jako strukturované protokolování.

Používání architektury třetí strany se podobá používání některého z předdefinovaných zprostředkovatelů:

  1. Přidejte do svého projektu příslušný balíček NuGet.
  2. Zavolejte rozšiřující metodu ILoggerFactory dané architektury protokolování.

Další informace najdete v dokumentaci k jednotlivým zprostředkovatelům. Microsoft nenabízí podporu zprostředkovatelů protokolování třetích stran.

Žádné asynchronní metody protokolovacího nástroje

Protokolování by mělo být tak rychlé, že asynchronní kód nedává smysl z hlediska dopadu na výkon. Pokud je pomalé úložiště dat protokolování, nezapisujte do něj přímo. Zvažte možnost nejprve zapisovat zprávy protokolu do rychlého úložiště a přesouvat je do pomalého úložiště později. Pokud například využíváte protokolování na SQL Server, neprovádějte to přímo v metodě Log, protože metody Log jsou synchronní. Místo toho synchronně přidávejte zprávy protokolu do fronty v paměti a nastavte pracovní proces na pozadí, který bude zprávy přetahovat z fronty a asynchronně publikovat data na SQL Server. Další informace najdete v pokynech k protokolování do fronty zpráv v případě pomalých úložišť dat (č. 11801 v úložišti dotnet/AspNetCore.Docs).

Změna úrovní protokolování ve spuštěné aplikaci

Rozhraní API pro protokolování neumožňuje změnit úrovně protokolování, když je aplikace spuštěná. Někteří zprostředkovatelé konfigurace však podporují opětovné načtení konfigurace, která se okamžitě projeví na konfiguraci protokolování. Například zprostředkovatel konfigurace souborů opětovně načítá konfiguraci protokolování ve výchozím nastavení. Pokud se v kódu změní konfigurace, když je aplikace spuštěná, může aplikace aktualizovat svou konfiguraci protokolování zavoláním metody IConfigurationRoot.Reload.

ILogger a ILoggerFactory

Rozhraní ILogger<TCategoryName> a ILoggerFactory a jejich implementace jsou součástí sady .NET Core SDK. K dispozici jsou také v následujících balíčcích NuGet:

Používání pravidel filtrování protokolů v kódu

Při nastavování pravidel filtrování protokolů se upřednostňuje použití konfigurace.

Následující příklad ukazuje, jak zaregistrovat pravidla filtrování protokolů v kódu:

using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);

Metoda logging.AddFilter("System", LogLevel.Debug) určuje kategorii System a úroveň protokolování Debug. Filtr se použije pro všechny zprostředkovatele, protože se nenakonfiguroval konkrétní zprostředkovatel.

Metoda AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) určuje:

  • Zprostředkovatele protokolování Debug
  • Úroveň protokolování Information a vyšší
  • Všechny kategorie začínající na "Microsoft"

Automatické nastavení oboru protokolování pomocí vlastností SpanId, TraceId, ParentId, Baggage a Tags

Knihovny protokolování implicitně vytváří objekt oboru s vlastnostmi SpanId, TraceId, ParentId, Baggage a Tags. Toto chování se konfiguruje prostřednictvím vlastnosti ActivityTrackingOptions.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(options =>
{
    options.IncludeScopes = true;
});

builder.Logging.Configure(options =>
{
    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                       | ActivityTrackingOptions.TraceId
                                       | ActivityTrackingOptions.ParentId
                                       | ActivityTrackingOptions.Baggage
                                       | ActivityTrackingOptions.Tags;
});
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Pokud je nastavená hlavička požadavku HTTP traceparent, ve vlastnosti ParentId v oboru protokolování se zobrazí hodnota W3C parent-id z příchozí hlavičky traceparent a ve vlastnosti SpanId v oboru protokolování se zobrazí aktualizovaná hodnota parent-id pro další odchozí krok nebo rozpětí kroků. Další informace najdete v části věnované úpravám pole traceparent.

Vytvoření vlastního protokolovacího nástroje

Pokud chcete vytvořit vlastní protokolovací nástroj, projděte si téma Implementace vlastního zprostředkovatele protokolování v .NET.

Další materiály

Autoři: Kirk Larkin, Juergen Gutsch a Rick Anderson

Toto téma popisuje protokolování v .NET ve vztahu k aplikacím ASP.NET Core. Podrobné informace o protokolování v .NET najdete v tématu Protokolování v .NET. Další informace o protokolování v aplikacích Blazor najdete v tématu Protokolování ASP.NET Core Blazor.

Zobrazení nebo stažení vzorového kódu (postup stažení)

Zprostředkovatelé protokolování

Zprostředkovatelé protokolování uchovávají protokoly, kromě zprostředkovatele Console, který protokoly pouze zobrazuje. Například zprostředkovatel Azure Application Insights uchovává protokoly v Azure Application Insights. Je možné povolit více zprostředkovatelů.

Výchozí šablony webových aplikací ASP.NET Core:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Výše uvedený kód ukazuje vytvoření třídy Program s využitím šablon webových aplikací ASP.NET Core. Následujících několik částí obsahuje ukázky založené na šablonách webových aplikací ASP.NET Core, které používají obecného hostitele. Jiným než hostitelským konzolovým aplikacím se věnujeme dále v tomto dokumentu.

Pokud chcete přepsat výchozí sadu zprostředkovatelů protokolování přidanou metodou Host.CreateDefaultBuilder, zavolejte metodu ClearProviders a přidejte požadované zprostředkovatele protokolování. Například následující kód:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Informace o dalších zprostředkovatelích najdete tady:

Vytváření protokolů

K vytváření protokolů použijte objekt ILogger<TCategoryName> z injektáže závislostí (DI).

Následující příklad:

  • Vytvoří protokolovací nástroj ILogger<AboutModel>, který jako kategorii protokolu používá plně kvalifikovaný název typu AboutModel. Kategorie protokolu je řetězec přidružený k jednotlivým protokolům.
  • Volá metodu LogInformation, která protokoluje na úrovni Information. Úroveň protokolování označuje závažnost protokolované události.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Úrovním a kategoriím se podrobněji věnujeme dále v tomto dokumentu.

Informace o architektuře Blazor najdete v tématu Protokolování ASP.NET Core Blazor.

Část Vytváření protokolů ve třídách Main a Startup ukazuje, jak vytvářet protokoly ve třídách Main a Startup.

Konfigurace protokolování

Konfiguraci protokolování obvykle zajišťuje oddíl Logging souborů appsettings.{Environment}.json. Šablony webových aplikací ASP.NET Core generují následující soubor appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

V předchozím fragmentu kódu JSON:

  • Jsou zadané kategorie "Default", "Microsoft" a "Microsoft.Hosting.Lifetime".
  • Kategorie "Microsoft" se vztahuje na všechny kategorie, které začínají na "Microsoft". Toto nastavení se například vztahuje i na kategorii "Microsoft.AspNetCore.Routing.EndpointMiddleware".
  • Kategorie "Microsoft" zajišťuje protokolování na úrovni protokolování Warning nebo vyšší.
  • Kategorie "Microsoft.Hosting.Lifetime" je konkrétnější než kategorie "Microsoft", takže kategorie "Microsoft.Hosting.Lifetime" zajišťuje protokolování na úrovni protokolování Information nebo vyšší.
  • Není zadaný žádný konkrétní zprostředkovatel protokolování, takže se vlastnost LogLevel vztahuje na všechny povolené zprostředkovatele protokolování s výjimkou zprostředkovatele Windows EventLog.

Vlastnost Logging může obsahovat vlastnost LogLevel a vlastnosti zprostředkovatele protokolování. Vlastnost LogLevel určuje minimální úroveň protokolování pro vybrané kategorie. V předchozím kódu JSON Information a Warning úrovně protokolu jsou zadané. Vlastnost LogLevel označuje závažnost protokolu v rozsahu od 0 do 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 a None = 6.

Když je zadaná vlastnost LogLevel, protokolování se povolí pro zprávy na zadané úrovni a vyšší. V předchozím kódu JSON Default se kategorie zaprotokoluje a Information je vyšší. Protokolují se například zprávy úrovně Information, Warning, Error a Critical. Pokud není zadaná žádná vlastnost LogLevel, nastaví se výchozí úroveň protokolování Information. Další informace najdete v části Úrovně protokolování.

Vlastnost LogLevel může být zadaná ve vlastnosti zprostředkovatele. Vlastnost LogLevel v rámci zprostředkovatele určuje úrovně protokolování pro daného zprostředkovatele a přepisuje nastavení protokolování pro všechny zprostředkovatele. Vezměme například následující soubor appsettings.json:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Nastavení ve vlastnosti Logging.{providername}.LogLevel přepíše nastavení ve vlastnosti Logging.LogLevel. V předchozím kódu JSON Debug je výchozí úroveň protokolu poskytovatele nastavená na Information:

Logging:Debug:LogLevel:Default:Information

Výše uvedené nastavení určuje úroveň protokolování Information pro všechny kategorie Logging:Debug: s výjimkou kategorie Microsoft.Hosting. Pokud je uvedená konkrétní kategorie, tato konkrétní kategorie přepíše výchozí kategorii. V předchozím kódu JSON Logging:Debug:LogLevel kategorie "Microsoft.Hosting" a "Default" přepsání nastavení v Logging:LogLevel

Minimální úroveň protokolování je možné zadat pro:

  • Konkrétní zprostředkovatele: například Logging:EventSource:LogLevel:Default:Information
  • Konkrétní kategorie: například Logging:LogLevel:Microsoft:Warning
  • Všechny zprostředkovatele a všechny kategorie: Logging:LogLevel:Default:Warning

Žádné protokoly pod minimální úrovní se:

  • Nepředávají zprostředkovateli.
  • Neprotokolují ani nezobrazují.

Pokud chcete potlačit všechny protokoly, zadejte LogLevel.None. Vlastnost LogLevel.None má hodnotu 6, která je vyšší než hodnota vlastnosti LogLevel.Critical (5).

Pokud zprostředkovatel podporuje obory protokolování, vlastnost IncludeScopes označuje, jestli jsou povolené. Další informace najdete v části Obory protokolování.

Následující soubor appsettings.json obsahuje ve výchozím nastavení povolené všechny zprostředkovatele:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Ve výše uvedené ukázce:

  • Kategorie a úrovně nejsou navrhované hodnoty. Ukázka obsahuje všechny výchozí zprostředkovatele.
  • Nastavení ve vlastnosti Logging.{providername}.LogLevel přepíše nastavení ve vlastnosti Logging.LogLevel. Například úroveň ve vlastnosti Debug.LogLevel.Default přepíše úroveň ve vlastnosti LogLevel.Default.
  • Používá se alias všech výchozích zprostředkovatelů. Každý zprostředkovatel definuje alias, který je možné použít v konfiguraci místo plně kvalifikovaného názvu typu. Předdefinované aliasy poskytovatelů jsou:
    • Konzola
    • Ladění
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Nastavení úrovně protokolování pomocí příkazového řádku, proměnných prostředí a další konfigurace

Úroveň protokolování může nastavit jakýkoli zprostředkovatel konfigurace.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Bash například : nepodporuje oddělovač. Dvojité podtržítko je __:

  • Podporuje všemi platformami.
  • Automaticky nahrazen dvojtečka, :.

Následující příkazy:

  • Nastaví klíč prostředí Logging:LogLevel:Microsoft ve Windows na hodnotu Information.
  • Otestují nastavení při použití aplikace vytvořené s využitím šablon webových aplikací ASP.NET Core. Po použití příkazu set se musí v adresáři projektu spustit příkaz dotnet run.
set Logging__LogLevel__Microsoft=Information
dotnet run

Výše uvedené nastavení prostředí se:

  • Nastaví pouze v procesech spuštěných z příkazového okna, ve kterém byly nastavené.
  • Nenačte v prohlížečích spuštěných pomocí sady Visual Studio.

Následující příkaz setx také nastaví klíč prostředí a jeho hodnotu ve Windows. Na rozdíl od příkazu set se nastavení příkazu setx zachovají. Přepínač /M nastaví proměnnou v systémovém prostředí. Pokud se nepoužije přepínač /M, nastaví se proměnná uživatelského prostředí.

setx Logging__LogLevel__Microsoft Information /M

Vezměme například následující soubor appsettings.json:

"Logging": {
    "Console": {
      "LogLevel": {
        "Microsoft.Hosting.Lifetime": "Trace"
      }
    }
}

Následující příkaz nastaví v prostředí výše uvedenou konfiguraci:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

V Azure App Service vyberte Nové nastavení aplikace na stránce Nastavení > Konfigurace. Nastavení aplikace Azure App Service se:

  • Zašifrováno a přenášeno rest přes šifrovaný kanál.
  • Vystavují jako proměnné prostředí.

Další informace viz Azure Apps: Přepsání konfigurace aplikace pomocí webu Azure Portal.

Další informace o nastavení hodnot konfigurace ASP.NET Core pomocí proměnných prostředí najdete v části Proměnné prostředí. Informace o používání dalších zdrojů konfigurace, včetně příkazového řádku, služby Azure Key Vault, služby Azure App Configuration, jiných formátů souborů a dalších, najdete v tématu Konfigurace v ASP.NET Core.

Uplatňování pravidel filtrování

Když se vytvoří objekt ILogger<TCategoryName>, objekt ILoggerFactory vybere pro každého zprostředkovatele jedno pravidlo, které se použije na daný protokolovací nástroj. Všechny zprávy zapsané instancí ILogger se filtrují na základě vybraných pravidel. Pro každou dvojici zprostředkovatele a kategorie se z dostupných pravidel vybere nejkonkrétnější pravidlo.

Při vytvoření objektu ILogger pro danou kategorii se u každého zprostředkovatele použije následující algoritmus:

  • Vyberou se všechna pravidla, která odpovídají zprostředkovateli nebo jeho aliasu. Pokud se nenajde žádná shoda, vyberou se všechna pravidla s neuvedeným zprostředkovatelem.
  • Z výsledku předchozího kroku se vyberou pravidla s nejdelší shodou předpony kategorie. Pokud se nenajde žádná shoda, vyberou se všechna pravidla, která neuvádějí kategorii.
  • Pokud je vybraných více pravidel, vybere se poslední pravidlo.
  • Pokud nejsou vybraná žádná pravidla, použije se pravidlo MinimumLevel.

Protokolování výstupu z příkazu dotnet run a sady Visual Studio

Protokoly vytvořené pomocí výchozích zprostředkovatelů protokolování se zobrazují:

  • V sadě Visual Studio
    • V okně Výstup ladění při ladění
    • V okně Webový server ASP.NET Core
  • V okně konzoly při spuštění aplikace pomocí příkazu dotnet run

Protokoly, jejichž kategorie začíná na Microsoft, pocházejí z kódu architektury ASP.NET Core. ASP.NET Core a kód aplikace používají stejné rozhraní API pro protokolování a zprostředkovatele protokolování.

Kategorie protokolu

Při vytvoření objektu ILogger se určí kategorie. Tato kategorie je součástí každé zprávy protokolu vytvořené danou instancí ILogger. Řetězec kategorie může být libovolný, ale standardně se používá název třídy. Například v kontroleru může název být "TodoApi.Controllers.TodoController". Webové aplikace ASP.NET Core používají ILogger<T> k automatickému získání instance ILogger, která jako kategorii používá plně kvalifikovaný název typu T:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Pokud chcete explicitně zadat kategorii, zavolejte metodu ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Volání metody CreateLogger s pevně daným názvem může být užitečné při použití ve více metodách, aby bylo možné události uspořádat podle kategorie.

Výraz ILogger<T> je ekvivalentní volání metody CreateLogger s plně kvalifikovaným názvem typu T.

Úroveň protokolu

Následující tabulka uvádí hodnoty vlastnosti LogLevel, vhodnou rozšiřující metodu Log{LogLevel} a navrhované použití:

ÚroveňProtokolu Hodnota metoda Popis
Trasování 0 LogTrace Obsahuje nejpodrobnější zprávy. Tyto zprávy můžou obsahovat citlivá data aplikace. Tyto zprávy jsou ve výchozím nastavení zakázané a neměly by se povolovat v produkčním prostředí.
Debug 0 LogDebug Slouží pro účely ladění a vývoje. Vzhledem k velkému objemu používejte tuto úroveň opatrně v produkčním prostředí.
Informace 2 LogInformation Sleduje obecný tok aplikace. Může mít dlouhodobou hodnotu.
Upozorňující 3 LogWarning Slouží k protokolování neobvyklých nebo neočekávaných událostí. Obvykle zahrnuje chyby nebo podmínky, které nezpůsobují selhání aplikace.
Chyba 4 LogError Slouží k protokolování chyb a výjimek, které není možné zpracovat. Tyto zprávy značí selhání v aktuální operaci nebo požadavku, nikoli selhání na úrovni aplikace.
Kritická 5 LogCritical Slouží k protokolování událostí, které vyžadují okamžitou pozornost. Příklady: scénáře ztráty dat, nedostatek místa na disku.
Nic 6 Určuje, že kategorie protokolování nemá zapisovat žádné zprávy.

Ve výše uvedené tabulce jsou hodnoty vlastnosti LogLevel uvedené v pořadí od nejnižší po nejvyšší závažnost.

První parametr metody Log, LogLevel, označuje závažnost protokolu. Většina vývojářů místo volání metody Log(LogLevel, ...) volá rozšiřující metody Log{LogLevel}. Rozšiřující metody Log{LogLevel} volají metodu Log a určují hodnotu LogLevel. Například následující dvě volání protokolování jsou funkčně ekvivalentní a generují stejné protokoly:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem je ID události. MyLogEvents je součástí ukázkové aplikace a zobrazuje se v části ID události protokolu.

Metody MyDisplayRouteInfo a ToCtxString poskytuje balíček NuGet Rick.Docs.Samples.RouteInfo. Tyto metody zobrazují informace o trasách Controller a Razor Page.

Následující kód vytvoří protokoly Information a Warning:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

První parametr metody Log{LogLevel}, MyLogEvents.GetItem, ve výše uvedeném kódu je ID události protokolu. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů, které poskytují zbývající parametry metody. Vysvětlení parametrů metody najdete v části věnované šabloně zprávy dále v tomto dokumentu.

Voláním vhodné metody Log{LogLevel} můžete řídit, jak velký výstup protokolování se bude zapisovat na konkrétní úložné médium. Příklad:

  • V produkčním prostředí:
    • Protokolování na úrovni Trace nebo Information generuje velké množství podrobných zpráv protokolu. Pokud chcete mít náklady pod kontrolou a nepřekročit limity úložiště dat, protokolujte zprávy úrovně Trace a Information do velkoobjemového a nízkonákladového úložiště dat. Zvažte omezení úrovní Trace a Information na konkrétní kategorie.
    • Protokolování na úrovni Warning až Critical by mělo generovat malé množství zpráv protokolu.
      • Náklady a limity úložiště obvykle nepředstavují problém.
      • Malé množství protokolů znamená větší flexibilitu při výběru úložiště dat.
  • Ve vývoji:
    • Nastavte na Warning.
    • Při řešení potíží přidejte zprávy úrovně Trace nebo Information. Pokud chcete omezit výstup, nastavte úroveň Trace nebo Information pouze pro kategorie, které zkoumáte.

ASP.NET Core zapisuje protokoly pro události architektury. Podívejte se například na výstup protokolu s následujícími informacemi:

  • Vytvoření aplikace Razor Pages s využitím šablon ASP.NET Core
  • Nastavení protokolování na úrovni Logging:Console:LogLevel:Microsoft:Information
  • Přechod na stránku Privacy:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Následující sady Logging:Console:LogLevel:Microsoft:InformationJSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID události protokolu

Každý protokol může uvádět ID události. V ukázkové aplikaci se k definování ID událostí používá třída MyLogEvents:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

ID události spojuje sadu událostí. Například všechny protokoly související se zobrazením seznamu položek na stránce můžou mít ID 1001.

Zprostředkovatel protokolování může uchovávat ID události v poli ID, ve zprávě protokolování nebo ho nemusí uchovávat vůbec. Zprostředkovatel Debug nezobrazuje ID událostí. Zprostředkovatel Console zobrazuje ID událostí v závorkách za kategorií:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Někteří zprostředkovatelé protokolování uchovávají ID událostí v poli, což umožňuje filtrování podle ID.

Šablona zprávy protokolu

Každé rozhraní API pro protokoly používá šablony zprávy. Šablona zprávy může obsahovat zástupné symboly, pro které se poskytnou argumenty. Jako zástupné symboly používejte názvy, a ne čísla.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Pořadí parametrů, nikoli názvy zástupných symbolů, určuje, které parametry se použijí k zadání hodnot zástupných symbolů ve zprávách protokolu. V následujícím kódu mají v šabloně zprávy názvy parametrů jiné pořadí než zástupné symboly:

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

Parametry se však přiřadí zástupným symbolům v tomto pořadí: apples, pears, bananas. Zpráva protokolu odráží pořadí parametrů:

Parameters: 1, 2, 3

Tento přístup umožňuje zprostředkovatelům protokolování implementovat sémantické neboli strukturované protokolování. Do systému protokolování se předávají samotné argumenty, nikoli pouze formátovaná šablona zprávy. To umožňuje zprostředkovatelům protokolování uchovávat hodnoty parametrů jako pole. Podívejte se například na následující metodu protokolovacího nástroje:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Například při protokolování do služby Azure Table Storage:

  • Každá entita tabulky Azure může mít vlastnosti ID a RequestTime.
  • Tabulky s vlastnostmi zjednodušují dotazy na protokolovaná data. Dotaz může například vyhledat všechny protokoly v určitém rozsahu hodnot RequestTime, aniž by musel parsovat čas z textové zprávy.

Výjimky protokolu

Metody protokolovacího nástroje obsahují přetížení, která jako parametr přebírají výjimku:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

Metody MyDisplayRouteInfo a ToCtxString poskytuje balíček NuGet Rick.Docs.Samples.RouteInfo. Tyto metody zobrazují informace o trasách Controller a Razor Page.

Protokolování výjimek se u jednotlivých zprostředkovatelů liší.

Výchozí úroveň protokolování

Pokud není nastavená výchozí úroveň protokolování, má výchozí úroveň protokolování hodnotu Information.

Podívejte se například na následující webovou aplikaci:

  • Aplikace je vytvořená s využitím šablon webových aplikací ASP.NET.
  • Soubory appsettings.json a appsettings.Development.json se odstranily nebo přejmenovaly.

Při předchozím nastavení se při přechodu na privacy stránku vytvoří home mnoho TraceDebug, a Information zprávy s Microsoft názvem kategorie.

Následující kód nastaví výchozí úroveň protokolování, pokud není nastavená v konfiguraci:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Obecně platí, že by se úrovně protokolování měly zadávat v konfiguraci, a ne v kódu.

Funkce filtru

Funkce filtru se volá pro všechny zprostředkovatele a kategorie, ke kterým nejsou v konfiguraci nebo kódu přiřazená pravidla:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Výše uvedený kód zobrazí protokoly konzoly v případě, že kategorie obsahuje Controller nebo Microsoft a úroveň protokolování je Information nebo vyšší.

Obecně platí, že by se úrovně protokolování měly zadávat v konfiguraci, a ne v kódu.

ASP.NET Core a EF Core kategorie

Následující tabulka obsahuje několik kategorií, které se používají v ASP.NET Core a Entity Framework Core, a poznámky o protokolech:

Kategorie Notes
Microsoft.AspNetCore Obecná diagnostika ASP.NET Core.
Microsoft.AspNetCore.DataProtection Informace o zvažovaných, nalezených a použitých klíčích.
Microsoft.AspNetCore.HostFiltering Informace o povolených hostitelích.
Microsoft.AspNetCore.Hosting Informace o tom, kdy se zahájily požadavky HTTP a jak dlouho trvalo jejich dokončení. Informace o načtených hostujících spouštěcích sestavení.
Microsoft.AspNetCore.Mvc Diagnostika MVC a Razor. Informace o vazbě modelu, spuštění filtru, kompilaci zobrazení a výběru akce.
Microsoft.AspNetCore.Routing Informace o porovnávání tras.
Microsoft.AspNetCore.Server Informace o zahájení a ukončení připojení a odpovědích pro zachování připojení. Informace o certifikátu HTTPS.
Microsoft.AspNetCore.StaticFiles Informace o obsluhovaných souborech.
Microsoft.EntityFrameworkCore Obecná diagnostika Entity Framework Core. Informace o aktivitě a konfiguraci databáze, detekci změn a migracích.

Pokud chcete v okně konzoly zobrazit další kategorie, nastavte soubor appsettings.Development.json následovně:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Obory protokolování

Obor může seskupovat sadu logických operací. Toto seskupení je možné využít k připojení stejných dat ke všem protokolům vytvořeným v rámci sady. Například všechny protokoly vytvořené v rámci zpracování transakce můžou obsahovat ID transakce.

Obor:

Obory podporují následující zprostředkovatelé:

Obor můžete použít tak, že zabalíte volání protokolovacího nástroje do bloku using:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Předdefinovaní zprostředkovatelé protokolování

ASP.NET Core jako součást sdílené architektury obsahuje následující zprostředkovatele protokolování:

Microsoft dodává následující zprostředkovatele protokolování, kteří však nejsou součástí sdílené architektury. Musí se nainstalovat jako další balíček NuGet.

ASP.NET Core neobsahuje žádného zprostředkovatele protokolování pro zápis protokolů do souborů. Pokud chcete v aplikaci ASP.NET Core zapisovat protokoly do souborů, zvažte použití zprostředkovatele protokolování třetí strany.

Informace o výstupu stdout a protokolování ladění s využitím modulu ASP.NET Core najdete v tématech Řešení potíží s ASP.NET Core v Azure App Service a ve službě IIS a Modul ASP.NET Core (ANCM) pro službu IIS.

Konzola

Zprostředkovatel Console protokoluje výstup do konzoly. Další informace o zobrazení protokolů Console při vývoji najdete v části Protokolování výstupu z příkazu dotnet run a sady Visual Studio.

Ladění

Zprostředkovatel Debug zapisuje výstup protokolování s využitím třídy System.Diagnostics.Debug. Do zprostředkovatele Debug se zapisuje voláním metody System.Diagnostics.Debug.WriteLine.

V Linuxu závisí umístění protokolu zprostředkovatele Debug na konkrétní distribuci a může se jednat o jedno z následujících umístění:

  • /var/log/message
  • /var/log/syslog

Zdroj události

Zprostředkovatel EventSource zapisuje do multiplatformního zdroje událostí s názvem Microsoft-Extensions-Logging. Ve Windows tento zprostředkovatel využívá Trasování událostí pro Windows.

Nástroj dotnet-trace

Nástroj dotnet-trace je globální multiplatformní nástroj rozhraní příkazového řádku, který umožňuje shromažďování trasování .NET Core spuštěných procesů. Tento nástroj shromažďuje data zprostředkovatele Microsoft.Extensions.Logging.EventSource s využitím třídy LoggingEventSource.

Pokyny k instalaci najdete tady: dotnet-trace.

Použití nástroje dotnet-trace ke shromáždění trasování z aplikace:

  1. Spusťte aplikaci pomocí příkazu dotnet run.

  2. Zjistěte identifikátor procesu (PID) aplikace .NET Core:

    dotnet trace ps

    Vyhledejte PID procesu se stejným názvem jako sestavení aplikace.

  3. Spusťte příkaz dotnet trace.

    Obecná syntaxe příkazu:

    dotnet trace collect -p {PID} 
    --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"

    Pokud používáte příkazové prostředí PowerShellu, uzavřete hodnotu parametru --providers do jednoduchých uvozovek ('):

    dotnet trace collect -p {PID} 
    --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"'

    Na jiných platformách než Windows přidáním možnosti -f speedscope změňte formát výstupního trasovacího souboru na speedscope.

    Následující tabulka definuje hodnotu Keyword:

    Klíčové slovo Popis
    1 Protokoluje metadata událostí souvisejících s třídou LoggingEventSource. Neprotokoluje události z rozhraní ILogger.
    2 Při zavolání metody ILogger.Log() zapne událost Message. Poskytuje programové (neformátované) informace.
    4 Při zavolání metody ILogger.Log() zapne událost FormatMessage. Poskytuje informace v podobě formátovaného řetězce.
    8 Při zavolání metody ILogger.Log() zapne událost MessageJson. Poskytuje reprezentaci argumentů ve formátu JSON.

    Následující tabulka uvádí úrovně zprostředkovatele:

    Úroveň zprostředkovatele Popis
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Úroveň kategorie se může parsovat na základě řetězce nebo čísla:

    Pojmenovaná hodnota kategorie Číselná hodnota
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Úroveň zprostředkovatele a úroveň kategorie:

    • Jsou v obráceném pořadí.
    • Řetězcové konstanty nejsou všechny identické.

    Pokud nejsou zadané žádné položky FilterSpecs, implementace EventSourceLogger se pokusí převést úroveň zprostředkovatele na úroveň kategorie, kterou použije pro všechny kategorie.

    Úroveň zprostředkovatele Úroveň kategorie
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Pokud jsou zadané položky FilterSpecs, pro všechny kategorie na seznamu se použije zakódovaná kategorie a všechny ostatní kategorie se odfiltrují.

    V následujících příkladech se předpokládá, že:

    • Aplikace je spuštěná a volá metodu logger.LogDebug("12345").
    • ID procesu (PID) se nastavilo prostřednictvím set PID=12345, kde 12345 je skutečné PID.

    Zvažte použití následujícího příkazu:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5

    Předchozí příkaz:

    • Zachytává zprávy ladění.
    • Nepoužívá položky FilterSpecs.
    • Určuje úroveň 5, která se mapuje na kategorii Debug (Ladění).

    Zvažte použití následujícího příkazu:

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"

    Předchozí příkaz:

    • Nezachytává zprávy ladění, protože kategorie úrovně 5 je Critical.
    • Poskytuje položky FilterSpecs.

    Následující příkaz zachytává zprávy ladění, protože kategorie úrovně 1 je Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"

    Následující příkaz zachytává zprávy ladění, protože kategorie je Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"

    Položky FilterSpecs pro {Logger Category} a {Category Level} představují další podmínky filtrování protokolů. K oddělení položek FilterSpecs použijte znak středníku (;).

    Příklad s použitím příkazového prostředí Windows:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"

    Výše uvedený příkaz aktivuje:

    • Protokolovací nástroj zdroje událostí, který generuje formátované řetězce (4) v případě chyb (2).
    • Protokolování Microsoft.AspNetCore.Hosting na úrovni protokolování Informational (4).

  4. Stisknutím klávesy Enter nebo kombinace kláves Ctrl+C zastavte nástroj dotnet-trace.

    Trasování se uloží s názvem trace.nettrace ve složce, ve které se spustil příkaz dotnet trace.

  5. Otevřete trasování v nástroji PerfView. Otevřete soubor trace.nettrace a prozkoumejte události trasování.

Pokud aplikace nesestaví hostitele pomocí metody CreateDefaultBuilder, přidejte do konfigurace protokolování aplikace zprostředkovatele zdroje událostí.

Další informace naleznete v tématu:

PerfView

Pomocí nástroje PerfView můžete shromažďovat a zobrazovat protokoly. Protokoly Trasování událostí pro Windows je možné zobrazit i v jiných nástrojích, ale PerfView nabízí nejlepší prostředí pro práci s událostmi Trasování událostí pro Windows, které generuje ASP.NET Core.

Pokud chcete nástroj PerfView nakonfigurovat tak, aby shromažďoval události protokolované tímto zprostředkovatelem, přidejte na seznam Additional Providers (Další zprostředkovatelé) řetězec *Microsoft-Extensions-Logging. Nevynechejte znak * na začátku řetězce.

Windows EventLog

Zprostředkovatel EventLog odesílá výstup protokolování do protokolu událostí Windows. Na rozdíl od ostatních zprostředkovatelů zprostředkovatel EventLog nedědí výchozí nastavení pro všechny zprostředkovatele. Pokud není zadané nastavení protokolování EventLog, použije se výchozí nastavení LogLevel.Warning.

Pokud chcete protokolovat události nižší úrovně než LogLevel.Warning, nastavte úroveň protokolování explicitně. Následující příklad nastaví výchozí úroveň protokolování do protokolu událostí na LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Přetížení AddEventLog přijímá parametr EventLogSettings. Pokud má tento parametr hodnotu null nebo není nastavený, použije se následující výchozí nastavení:

  • LogName: "Application"
  • SourceName: ".NET Runtime"
  • MachineName: Použije se název místního počítače.

Následující kód změní vlastnost SourceName z výchozí hodnoty ".NET Runtime" na hodnotu MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App Service

Balíček zprostředkovatele Microsoft.Extensions.Logging.AzureAppServices zapisuje protokoly do textových souborů v systému souborů aplikace Azure App Service a do úložiště objektů blob v účtu služby Azure Storage.

Tento balíček zprostředkovatele není součástí sdílené architektury. Pokud chcete tohoto zprostředkovatele použít, přidejte do projektu balíček zprostředkovatele.

Ke konfiguraci nastavení zprostředkovatele použijte třídy AzureFileLoggerOptions a AzureBlobLoggerOptions, jak je znázorněno v následujícím příkladu:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Když se aplikace nasadí v Azure App Service, používá nastavení v části Protokoly App Service na stránce App Service na webu Azure Portal. Pokud se upraví následující nastavení, změny se projeví okamžitě bez nutnosti aplikaci restartovat nebo nasadit znovu.

  • Protokolování aplikace (systém souborů)
  • Protokolování aplikace (objekt blob)

Výchozí umístění souborů protokolu je ve složce D:\home\LogFiles\Application a výchozí název souboru je diagnostics-yyyymmdd.txt. Výchozí limit velikosti souboru je 10 MB a výchozí maximální počet uchovávaných souborů je 2. Výchozí název objektu blob je {název_aplikace}{časové_razítko}/yyyy/mm/dd/hh/{GUID}-applicationLog.txt.

Tento zprostředkovatel provádí protokolování pouze v případě, že projekt běží v prostředí Azure.

Streamování protokolů Azure

Streamování protokolů Azure podporuje zobrazení aktivity protokolování v reálném čase z následujících zdrojů:

  • Aplikační server
  • Webový server
  • Trasování neúspěšných požadavků

Konfigurace streamování protokolů Azure:

  • Na stránce aplikace na portálu přejděte na stránku Protokoly App Service.
  • Nastavte možnost Protokolování aplikace (systém souborů) na hodnotu Zapnuto.
  • Zvolte Úroveň protokolování. Toto nastavení se vztahuje pouze na streamování protokolů Azure.

Pokud chcete zobrazit protokoly, přejděte na stránku Stream protokolů. Protokolované zprávy se protokolují s využitím rozhraní ILogger.

Azure Application Insights

Balíček zprostředkovatele Microsoft.Extensions.Logging.ApplicationInsights zapisuje protokoly do Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a nabízí nástroje pro dotazování a analýzu telemetrických dat. Pokud použijete tohoto zprostředkovatele, můžete dotazovat a analyzovat protokoly pomocí nástrojů Application Insights.

Tento zprostředkovatel protokolování je jako závislost součástí balíčku Microsoft.ApplicationInsights.AspNetCore, který poskytuje veškerou dostupnou telemetrii pro ASP.NET Core. Pokud tento balíček používáte, nemusíte instalovat balíček zprostředkovatele.

Balíček Microsoft.ApplicationInsights.Web je určený pro ASP.NET 4.x, a ne pro ASP.NET Core.

Další informace naleznete v následujících zdrojích:

Zprostředkovatelé protokolování třetích stran

Architektury protokolování třetích stran, které fungují s ASP.NET Core:

Některé architektury třetích stran můžou provádět sémantické protokolování, označované také jako strukturované protokolování.

Používání architektury třetí strany se podobá používání některého z předdefinovaných zprostředkovatelů:

  1. Přidejte do svého projektu příslušný balíček NuGet.
  2. Zavolejte rozšiřující metodu ILoggerFactory dané architektury protokolování.

Další informace najdete v dokumentaci k jednotlivým zprostředkovatelům. Microsoft nenabízí podporu zprostředkovatelů protokolování třetích stran.

Jiná než hostitelská konzolová aplikace

Příklad použití obecného hostitele v jiné než webové konzolové aplikaci najdete v souboru Program.cs ukázkové aplikace s úlohami na pozadí (Úlohy na pozadí a hostované služby v ASP.NET Core).

Kód protokolování pro aplikace bez obecného hostitele se liší ve způsobu přidání zprostředkovatelů a vytvoření protokolovacích nástrojů.

Zprostředkovatelé protokolování

V jiné než hostitelské konzolové aplikaci při vytváření instance LoggerFactory zavolejte rozšiřující metodu Add{provider name} zprostředkovatele:

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Vytváření protokolů

K vytváření protokolů použijte objekt ILogger<TCategoryName>. Pomocí instance LoggerFactory vytvořte objekt ILogger.

Následující příklad vytvoří protokolovací nástroj s kategorií LoggingConsoleApp.Program.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

V následujícím příkladu se protokolovací nástroj používá k vytváření protokolů úrovně Information. Úroveň protokolování označuje závažnost protokolované události.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Úrovním a kategoriím se podrobněji věnujeme dále v tomto dokumentu.

Protokolování během vytváření hostitele

Protokolování během vytváření hostitele se přímo nepodporuje. Je však možné použít samostatný protokolovací nástroj. V následujícím příkladu se k protokolování v metodě CreateHostBuilder používá protokolovací nástroj Serilog. Metoda AddSerilog používá statickou konfiguraci zadanou ve vlastnosti Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Konfigurace služby, která závisí na rozhraní ILogger

Ve starších verzích ASP.NET Core funguje injektáž konstruktoru protokolovacího nástroje do třídy Startup, protože se pro webového hostitele vytvoří samostatný kontejner injektáže závislostí. Informace o tom, proč se pro obecného hostitele vytvoří pouze jeden kontejner, najdete v oznámení změny způsobující chybu.

Při konfiguraci služby, která závisí na rozhraní ILogger<T>, použijte injektáž konstruktoru nebo zadejte metodu pro vytváření objektů. Přístup s využitím metody pro vytváření objektů se doporučuje pouze v případě, že není k dispozici žádná jiná možnost. Představte si například službu, která potřebuje instanci ILogger<T> poskytnutou injektáží závislostí:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

Výše uvedený zvýrazněný kód představuje delegáta Func<T,TResult>, který se spustí, když kontejner injektáže závislostí potřebuje poprvé vytvořit instanci MyService. Tímto způsobem můžete přistupovat ke všem registrovaným službám.

Vytváření protokolů v třídě Main

Následující kód po sestavení hostitele získá z injektáže závislostí instanci ILogger a nastaví protokolování v třídě Main:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Vytváření protokolů v třídě Startup

Následující kód zapisuje protokoly v metodě Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

Zapisování protokolů před dokončením nastavení kontejneru injektáže závislostí v metodě Startup.ConfigureServices se nepodporuje:

  • Injektáž protokolovacího nástroje do konstruktoru třídy Startup se nepodporuje.
  • Injektáž protokolovacího nástroje do signatury metody Startup.ConfigureServices se nepodporuje.

Důvodem tohoto omezení je to, že protokolování závisí na injektáži závislostí a konfiguraci, která zase závisí na injektáži závislostí. Kontejner injektáže závislostí se nastaví až po dokončení metody ConfigureServices.

Informace o konfiguraci služby, která závisí na rozhraní ILogger<T>, nebo o tom, proč ve starších verzích fungovala injektáž protokolovacího nástroje do konstruktoru třídy Startup, najdete v části Konfigurace služby, která závisí na rozhraní ILogger.

Žádné asynchronní metody protokolovacího nástroje

Protokolování by mělo být tak rychlé, že asynchronní kód nedává smysl z hlediska dopadu na výkon. Pokud je pomalé úložiště dat protokolování, nezapisujte do něj přímo. Zvažte možnost nejprve zapisovat zprávy protokolu do rychlého úložiště a přesouvat je do pomalého úložiště později. Pokud například využíváte protokolování na SQL Server, neprovádějte to přímo v metodě Log, protože metody Log jsou synchronní. Místo toho synchronně přidávejte zprávy protokolu do fronty v paměti a nastavte pracovní proces na pozadí, který bude zprávy přetahovat z fronty a asynchronně publikovat data na SQL Server. Další informace najdete u tohoto problému na GitHubu.

Změna úrovní protokolování ve spuštěné aplikaci

Rozhraní API pro protokolování neumožňuje změnit úrovně protokolování, když je aplikace spuštěná. Někteří zprostředkovatelé konfigurace však podporují opětovné načtení konfigurace, která se okamžitě projeví na konfiguraci protokolování. Například zprostředkovatel konfigurace souborů opětovně načítá konfiguraci protokolování ve výchozím nastavení. Pokud se v kódu změní konfigurace, když je aplikace spuštěná, může aplikace aktualizovat svou konfiguraci protokolování zavoláním metody IConfigurationRoot.Reload.

ILogger a ILoggerFactory

Rozhraní ILogger<TCategoryName> a ILoggerFactory a jejich implementace jsou součástí sady .NET Core SDK. K dispozici jsou také v následujících balíčcích NuGet:

Používání pravidel filtrování protokolů v kódu

Při nastavování pravidel filtrování protokolů se upřednostňuje použití konfigurace.

Následující příklad ukazuje, jak zaregistrovat pravidla filtrování protokolů v kódu:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Metoda logging.AddFilter("System", LogLevel.Debug) určuje kategorii System a úroveň protokolování Debug. Filtr se použije pro všechny zprostředkovatele, protože se nenakonfiguroval konkrétní zprostředkovatel.

Metoda AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) určuje:

  • Zprostředkovatele protokolování Debug
  • Úroveň protokolování Information a vyšší
  • Všechny kategorie začínající na "Microsoft"

Automatické nastavení oboru protokolování pomocí vlastností SpanId, TraceId a ParentId

Knihovny protokolování implicitně vytváří objekt oboru s vlastnostmi SpanId, TraceId a ParentId. Toto chování se konfiguruje prostřednictvím vlastnosti ActivityTrackingOptions.

  var loggerFactory = LoggerFactory.Create(logging =>
  {
      logging.Configure(options =>
      {
          options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                              | ActivityTrackingOptions.TraceId
                                              | ActivityTrackingOptions.ParentId;
      }).AddSimpleConsole(options =>
      {
          options.IncludeScopes = true;
      });
  });

Pokud je nastavená hlavička požadavku HTTP traceparent, ve vlastnosti ParentId v oboru protokolování se zobrazí hodnota W3C parent-id z příchozí hlavičky traceparent a ve vlastnosti SpanId v oboru protokolování se zobrazí aktualizovaná hodnota parent-id pro další odchozí krok nebo rozpětí kroků. Další informace najdete v části věnované úpravám pole traceparent.

Vytvoření vlastního protokolovacího nástroje

Pokud chcete vytvořit vlastní protokolovací nástroj, projděte si téma Implementace vlastního zprostředkovatele protokolování v .NET.

Další materiály