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

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 Blazor jádra.

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í:

• Console
• Debug
• EventSource
• EventLog: Pouze Windows

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:

• Předdefinovaní zprostředkovatelé protokolování
• Zprostředkovatelé protokolování třetích stran

Vytvoř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.

Konfigurujte 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 Logging.LogLevel je název zprostředkovatele, přepíše nastavení ve vlastnosti {PROVIDER NAME}. 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 Logging.LogLevel je název zprostředkovatele, přepíše nastavení ve vlastnosti {PROVIDER NAME}. 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 volá objekt Program.cs 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 AddConsole volá metodu Program.cs 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 AddSimpleConsole volá metodu Program.cs, 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 dotnet run se musí v adresáři projektu spustit příkaz set.

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

Note

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:

• Šifrováno při uložení a přenášeno 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í:

LogLevel	Value	Method	Description
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	1	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. Napří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.

V případě výše uvedeného nastavení se při přechodu na stránku ochrany osobních údajů nebo domovskou stránku vygeneruje velké množství zpráv úrovně Trace, Debug a Information s textem Microsoft v názvu 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 Filter

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.

Category	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	Hostitelé jsou povoleni.
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	Obsloužené soubory.

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 protokolů

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:

• Je typem objektu IDisposable, který vrací metoda BeginScope.
• Platí, dokud se neodstraní.

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

• Console
• AzureAppServicesFile a AzureAppServicesBlob

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í:

• Console
• Debug
• EventSource
• EventLog

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.

• AzureAppServicesFile a AzureAppServicesBlob
• ApplicationInsights

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.

Console

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.

Debug

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

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álostí

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

Tento dotnet-trace nástroj je mezinárodně použitelný CLI nástroj, který umožňuje trasování .NET spuštěného procesu. 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. Určete identifikátor procesu (PID) aplikace .NET:

   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:

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

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

   Úroveň poskytovatele	Description
   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ň poskytovatele	Ú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:

• Trasování pro nástroj pro analýzu výkonu () (dotnet-tracedokumentace k .NET)
• Trasování pro nástroj pro analýzu výkonu (dotnet-trace) (dokumentace v úložišti dotnet/diagnostics na GitHubu)
• LoggingEventSource
• EventLevel
• PerfView: Užitečný nástroj pro zobrazení trasování zdroje událostí

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 *Microsoft-Extensions-Logging (Další zprostředkovatelé) řetězec . Nevynechejte znak * na začátku řetězce.

Protokol událostí windows

Zprostředkovatel EventLog odesílá výstup protokolování do protokolu událostí Windows. Na rozdíl od ostatních zprostředkovatelů zprostředkovatel EventLognedě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: "Aplikace"
• 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:

• Přehled Application Insights
• Application Insights pro aplikace ASP.NET Core: Začněte tady, pokud chcete spolu s protokolováním v plném rozsahu implementovat i telemetrii Application Insights.
• ApplicationInsightsLoggerProvider pro protokoly ILogger .NET: Pokud chcete implementovat poskytovatele protokolování bez zbytku telemetrie Application Insights, začněte tady.
• Adaptéry protokolování Application Insights
• Instalace, konfigurace a inicializace sady Application Insights SDK – interaktivní kurz

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

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

• elmah.io (úložiště GitHub)
• Gelf (úložiště GitHub)
• JSNLog (úložiště GitHub)
• KissLog.net (úložiště GitHub)
• Log4Net (úložiště GitHub)
• NLog (úložiště GitHub)
• PLogger (úložiště GitHub)
• Sentry (úložiště GitHub)
• Serilog (úložiště GitHub)
• Stackdriver (úložiště GitHub)

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

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

• Rozhraní se nacházejí v balíčku Microsoft.Extensions.Logging.Abstractions.
• Výchozí implementace se nacházejí v balíčku Microsoft.Extensions.Logging.

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.

Dodatečné zdroje

• Zlepšení výkonu protokolování pomocí generátorů zdrojů
• Za [LogProperties] sebou a nový generátor zdrojů protokolování telemetrie
• Zdroj Microsoft.Extensions.Logging na GitHubu
• Zobrazení nebo stažení vzorového kódu (postup stažení)
• Protokolování s vysokým výkonem
• Chyby protokolování by se měly hlásit v úložišti dotnet/runtime na GitHubu
• Protokolování ASP.NET Core Blazor