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

  • Článek
  • 25 min ke čtení

Od Kirka Larkin, Juergen Gutsch a Rick Anderson

.NET Core podporuje protokolovací rozhraní API, které funguje s řadou integrovaných poskytovatelů protokolování a jiných výrobců. V tomto článku se dozvíte, jak používat rozhraní API protokolování s integrovanými poskytovateli.

Většina příkladů kódu, které jsou uvedené v tomto článku, se nachází v ASP.NET Corech aplikacích. Části těchto fragmentů kódu specifické pro protokolování se vztahují na libovolnou aplikaci .NET Core, která používá obecného hostitele. Šablony ASP.NET Core webové aplikace používají obecného hostitele.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Zprostředkovatelé protokolování

Zprostředkovatelé protokolování uchovávají protokoly, s výjimkou Console poskytovatele, který zobrazuje protokoly. Poskytovatel Azure Application Insights například ukládá protokoly v Azure Application Insights. Je možné povolit více zprostředkovatelů.

Výchozí ASP.NET Core šablony webové aplikace:

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

Předchozí kód ukazuje Program třídu vytvořenou pomocí šablon webové aplikace ASP.NET Core. Další části obsahují ukázky založené na šablonách ASP.NET Core webových aplikací, které používají obecného hostitele. Další v tomto dokumentu jsou popsány v jiných než hostitelských konzolových aplikacích .

Chcete-li přepsat výchozí sadu zprostředkovatelů protokolování přidaných nástrojem Host.CreateDefaultBuilder , zavolejte ClearProviders a přidejte požadované poskytovatele 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>();
        });

Další poskytovatele najdete v těchto tématech:

Vytvořit protokoly

Chcete-li vytvořit protokoly, použijte ILogger<TCategoryName> objekt z Injektáže závislosti (di).

Následující příklad:

  • Vytvoří protokolovací nástroj, ILogger<AboutModel> který používá kategorii protokolu plně kvalifikovaného názvu typu AboutModel . Kategorie protokolu je řetězec, který je spojený s každým protokolem.
  • Volání LogInformation do protokolu na Information úrovni. Úroveň protokolu 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ě a kategorie jsou podrobněji vysvětleny dále v tomto dokumentu.

Informace o najdete v Blazor tématu vytvoření protokolů v Blazor nástroji Blazor WebAssembly a v tomto dokumentu.

Při vytváření protokolů v nástroji Main a Startup se dozvíte, jak vytvořit protokoly v Main a Startup .

Konfigurovat protokolování

Konfigurace protokolování je běžně poskytována Logging oddílem appSettings. {Environment} soubory . JSON . Následující appsettings.Development.jsv souboru vygeneruje šablony ASP.NET Core webové aplikace:

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

V předchozím kódu JSON:

  • "Default" "Microsoft" "Microsoft.Hosting.Lifetime" Jsou určeny kategorie, a.
  • "Microsoft"Kategorie se vztahuje na všechny kategorie, které začínají na "Microsoft" . Toto nastavení se vztahuje například na "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorii.
  • "Microsoft"Protokol kategorie na úrovni protokolu Warning a vyšším.
  • "Microsoft.Hosting.Lifetime"Kategorie je konkrétnější než "Microsoft" kategorie, takže se v "Microsoft.Hosting.Lifetime" kategorii protokoluje na úrovni protokolu "informace" a vyšší.
  • Konkrétního poskytovatele protokolu není zadaný, takže LogLevel se použije na všechny povolené zprostředkovatele protokolování, s výjimkou protokolu událostí systému Windows.

LoggingVlastnost může mít LogLevel vlastnosti a log Provider. LogLevelUrčuje minimální úroveň protokolu pro vybrané kategorie. V předchozím kódu JSON Information Warning jsou zadány úrovně protokolu. LogLeveloznačuje závažnost protokolu a rozsahů od 0 do 6:

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

Je-li LogLevel zadán parametr, je protokolování povoleno pro zprávy na zadané úrovni a vyšší. V předchozím formátu JSON Default kategorie je protokolována Information a vyšší. Například zprávy, Information , Warning Error a Critical jsou protokolovány. Pokud LogLevel není zadaný, použije se jako výchozí Information úroveň protokolování. Další informace najdete v tématu úrovně protokolu.

Vlastnost zprostředkovatele může určovat LogLevel vlastnost. LogLevelv části poskytovatel Určuje úrovně, které se mají protokolovat pro daného zprostředkovatele, a přepíše nastavení protokolu bez poskytovatele. V souboru zvažte následující appsettings.js :

{
  "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í v Logging.{providername}.LogLevel Nastavení přepsání v Logging.LogLevel . V předchozím formátu JSON Debug je výchozí úroveň protokolu poskytovatele nastavená na Information :

Logging:Debug:LogLevel:Default:Information

Předchozí nastavení určuje Information úroveň protokolu pro každou Logging:Debug: kategorii s výjimkou Microsoft.Hosting . Když je uvedena konkrétní kategorie, konkrétní kategorie přepíše výchozí kategorii. V předchozím formátu JSON Logging:Debug:LogLevel Kategorie "Microsoft.Hosting" a "Default" přepisují nastavení vLogging:LogLevel

Minimální úroveň protokolu může být zadána pro některý z těchto:

  • Konkrétní poskytovatelé: napříkladLogging:EventSource:LogLevel:Default:Information
  • Konkrétní kategorie: napříkladLogging:LogLevel:Microsoft:Warning
  • Všichni zprostředkovatelé a všechny kategorie:Logging:LogLevel:Default:Warning

Všechny protokoly pod minimální úrovní nejsou:

  • Předáno poskytovateli.
  • Protokolováno nebo zobrazeno.

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

Pokud zprostředkovatel podporuje obory protokolů, IncludeScopes označuje, zda jsou povoleny. Další informace najdete v tématu rozsahy protokolů .

Následující appsettings.js souboru obsahuje všechny poskytovatele povolené ve výchozím nastavení:

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

V předchozí ukázce:

  • Kategorie a úrovně nejsou navrhovanými hodnotami. Ukázka je k dispozici pro zobrazení všech výchozích zprostředkovatelů.
  • Nastavení v Logging.{providername}.LogLevel Nastavení přepsání v Logging.LogLevel . Například úroveň v Debug.LogLevel.Default Přepisuje úroveň v LogLevel.Default .
  • Použije se každý alias výchozího zprostředkovatele. Každý zprostředkovatel definuje alias , který lze použít v konfiguraci místo plně kvalifikovaného názvu typu. Předdefinovaná aliasy zprostředkovatelů jsou:
    • Konzola
    • Ladění
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Nastavení úrovně protokolu podle příkazového řádku, proměnných prostředí a jiné konfigurace

Úroveň protokolu může být nastavena libovolnými poskytovateli konfigurace.

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

  • Podporováno všemi platformami. Například : oddělovač není podporován bash, ale __ je.
  • Automaticky nahrazeno :

Následující příkazy:

  • Nastavte klíč prostředí Logging:LogLevel:Microsoft na hodnotu Information ve Windows.
  • Otestujte nastavení při použití aplikace vytvořené pomocí šablon webových aplikací ASP.NET Core. dotnet runPříkaz musí být spuštěn v adresáři projektu po použití set .
set Logging__LogLevel__Microsoft=Information
dotnet run

Předchozí nastavení prostředí:

  • Je nastaveno pouze v procesech spuštěných z příkazového okna, ve kterém byly nastaveny.
  • Není přečteno prohlížeči spuštěným v aplikaci Visual Studio.

Následující příkaz setx taky nastavuje klíč a hodnotu prostředí ve Windows. Na rozdíl set od setx platí, že nastavení jsou trvalá. /MPřepínač nastaví proměnnou v prostředí systému. Pokud se /M nepoužívá, je nastavena proměnná prostředí uživatele.

setx Logging__LogLevel__Microsoft=Information /M

V Azure App Servicena stránce Nastavení > konfigurace vyberte nové nastavení aplikace . Azure App Service nastavení aplikace:

  • Šifrované v klidovém stavu a přenášené přes zašifrovaný kanál.
  • Vystaveno jako proměnné prostředí.

Další informace najdete v tématu aplikace Azure: přepište konfiguraci aplikace pomocí webu Azure Portal.

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

Jak se používají pravidla filtrování

Při ILogger<TCategoryName> vytvoření objektu ILoggerFactory vybere objekt jedno pravidlo pro každého poskytovatele, které se použije pro tento protokolovací nástroj. Všechny zprávy napsané ILogger instancí jsou filtrovány podle vybraných pravidel. Z dostupných pravidel je vybráno pravidlo s nejpřesnější pro každou dvojici zprostředkovatelů a kategorií.

Následující algoritmus se používá pro každého poskytovatele při ILogger vytvoření pro danou kategorii:

  • Vyberte všechna pravidla, která se shodují se zprostředkovatelem nebo jeho aliasem. Pokud se nenajde žádná shoda, vyberte všechna pravidla s prázdným zprostředkovatelem.
  • Z výsledku předchozího kroku vyberte pravidla s nejdelší vyhovující předponou kategorie. Pokud se nenajde žádná shoda, vyberte všechna pravidla, která neurčují kategorii.
  • Pokud je vybráno více pravidel, vezměte Poslední z nich.
  • Pokud nejsou vybrána žádná pravidla, použijte MinimumLevel .

Výstup protokolování z příkazu dotnet Run a Visual Studio

Zobrazí se protokoly vytvořené s výchozím zprostředkovatelem protokolování :

  • V nástroji Visual Studio
    • V okně výstup ladění při ladění.
    • V okně ASP.NET Core webový server.
  • V okně konzoly při spuštění aplikace s nástrojem dotnet run .

Protokoly, které začínají na kategoriích Microsoft, jsou z ASP.NET Coreho kódu rozhraní. ASP.NET Core a kód aplikace používají stejné rozhraní API a poskytovatele protokolování.

Kategorie protokolu

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

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.");
    }
}

Chcete-li explicitně zadat kategorii, zavolejte ILoggerFactory.CreateLogger :

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

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

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

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

Úroveň protokolování

Následující tabulka uvádí LogLevel hodnoty, Log{LogLevel} způsob rozšíření pohodlí a navrhované použití:

LogLevel Hodnota Metoda Popis
Trasování 0 LogTrace Obsahuje nejpodrobnější zprávy. Tyto zprávy mohou obsahovat citlivá data aplikací. Tyto zprávy jsou ve výchozím nastavení zakázané a neměly by být povolené v produkčním prostředí.
Ladění 1 LogDebug Pro ladění a vývoj. Používejte s opatrností v produkčním prostředí kvůli vysokému objemu.
Informace 2 LogInformation Sleduje obecný tok aplikace. Může mít dlouhodobou hodnotu.
Upozornění 3 LogWarning Pro neobvyklé nebo neočekávané události. Obvykle obsahuje chyby nebo podmínky, které nezpůsobí selhání aplikace.
Chyba 4 LogError Pro chyby a výjimky, které nelze zpracovat. Tyto zprávy označují selhání aktuální operace nebo žádosti, ne selhání celé aplikace.
Kritické 5 LogCritical Chyby, které vyžadují okamžitou pozornost. Příklady: scénáře ztráty dat, nedostatek místa na disku.
Žádný 6 Určuje, že kategorie protokolování by neměla zapisovat žádné zprávy.

V předchozí tabulce LogLevel je uveden od nejnižší k nejvyšší závažnosti.

První parametr metody protokolu , LogLevel , označuje závažnost protokolu. Místo volání Log(LogLevel, ...) by většina vývojářů volala metody rozšíření log {LogLevel} . Log{LogLevel}Rozšiřující metody volají metodu protokolu a určují rozsah LogLevel. Například následující dvě volání protokolování jsou funkčně ekvivalentní a tvoří stejný protokol:

[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.TestItemje ID události. MyLogEventsje součástí ukázkové aplikace a zobrazí se v části ID události protokolu .

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

Následující kód vytváří Information a Warning protokoluje:

[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);
}

V předchozím kódu Log{LogLevel} je prvním parametrem MyLogEvents.GetItem ID události protokolu. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů poskytované zbývajícími parametry metody. Parametry metody jsou vysvětleny v části Šablona zprávy dále v tomto dokumentu.

Zavolejte příslušnou Log{LogLevel} metodu, která určuje, kolik výstupu protokolu se zapisuje na konkrétní paměťové médium. Příklad:

  • V produkčním prostředí:
    • Protokolování na úrovni Trace nebo Information vytváří velké množství podrobných zpráv protokolu. Abyste mohli řídit náklady a nepřekračuje limity úložiště dat, protokolovat a vyhodnotit Trace Information zprávy na úrovni cloudového úložiště s nízkými náklady na velké objemy dat. Zvažte omezení Trace a Information konkrétní kategorie.
    • Přihlášení Warning prostřednictvím Critical úrovní by mělo mít za následek několik zpráv protokolu.
      • Náklady a limity úložiště většinou nejsou obavy.
      • Několik protokolů umožňuje větší flexibilitu v možnostech úložiště dat.
  • Ve vývoji:
    • Nastavte na Warning.
    • Přidání Trace Information zpráv při řešení potíží. Pro omezení výstupu, nastavení Trace nebo Information pouze pro kategorie v rámci šetření.

ASP.NET Core zapisuje protokoly pro události rozhraní .NET Framework. Zvažte například výstup protokolu pro:

  • RazorAplikace stránky vytvořená pomocí šablon ASP.NET Core.
  • Protokolování je nastaveno naLogging:Console:LogLevel:Microsoft:Information
  • Navigace na stránku ochrany osobních údajů:
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 JSON Logging:Console:LogLevel:Microsoft:Information :

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

ID události protokolu

Každý protokol může určovat ID události. Ukázková aplikace používá MyLogEvents třídu k definování ID událostí:

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 přidružuje sadu událostí. Například všechny protokoly související se zobrazením seznamu položek na stránce může být 1001.

Zprostředkovatel protokolování může ukládat ID události v poli ID, ve zprávě protokolování nebo vůbec ne. Zprostředkovatel ladění nezobrazuje ID událostí. Poskytovatel konzoly 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í ukládají ID události do pole, které umožňuje filtrování podle ID.

Šablona zprávy protokolu

Každé rozhraní API protokolu používá šablonu zprávy. Šablona zprávy může obsahovat zástupné symboly, pro které jsou k dispozici argumenty. Použijte názvy zástupných symbolů, nikoli čí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í zástupných symbolů, nikoli jejich názvů, určuje, které parametry slouží k zadání jejich hodnot. V následujícím kódu jsou názvy parametrů mimo pořadí v šabloně zprávy:

string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Předchozí kód vytvoří zprávu protokolu s hodnotami parametrů v pořadí:

Parameter values: param1, param2

Tento přístup umožňuje zprostředkovatelům protokolování implementovat sémantické nebo strukturované protokolování. Samotné argumenty jsou předány do protokolovacího systému, nikoli pouze ze šablony formátované zprávy. To umožňuje zprostředkovatelům protokolování ukládat hodnoty parametrů jako pole. Zvažte například 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 Azure Table Storage:

  • Každá entita tabulky Azure může mít ID RequestTime vlastnosti a.
  • Tabulky s vlastnostmi zjednodušují dotazy na data protokolu. Dotaz může například najít všechny protokoly v rámci určitého RequestTime rozsahu bez nutnosti analyzovat časový limit textové zprávy.

Protokolovat výjimky

Metody protokolovacího nástroje mají přetížení, která přijímají parametr výjimky:

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

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

Protokolování výjimek je specifické pro konkrétního zprostředkovatele.

Výchozí úroveň protokolování

Pokud není nastavená výchozí úroveň protokolování, je výchozí hodnota úrovně protokolu Information .

Zvažte například následující webovou aplikaci:

  • Vytvořeno pomocí šablon webové aplikace ASP.NET.
  • appsettings.js a appsettings.Development.jspři odstranění nebo přejmenování.

V předchozím nastavení se při přechodu na soukromí nebo na domovské stránce Trace Debug Information v názvu kategorie vytvoří mnoho zpráv, a Microsoft .

Následující kód nastaví výchozí úroveň protokolování, pokud výchozí úroveň protokolu není nastavena 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 úrovně protokolu by měly být zadány v konfiguraci a nikoli kódu.

Filter – funkce

Funkce filtru je vyvolána pro všechny poskytovatele a kategorie, které nemají pravidla přiřazena pomocí konfigurace nebo 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((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>();
            });
}

Předchozí kód zobrazí protokoly konzoly, pokud kategorie obsahuje Controller nebo Microsoft a úroveň protokolu je Information nebo vyšší.

Obecně platí, že úrovně protokolu by měly být zadány v konfiguraci a nikoli kódu.

Kategorie ASP.NET Core a EF Core

Následující tabulka obsahuje některé kategorie používané ASP.NET Core a Entity Framework Core s poznámkami k protokolům:

Kategorie Poznámky
Microsoft. AspNetCore Obecná diagnostika ASP.NET Core.
Microsoft. AspNetCore. DataProtection Které klíče byly zváženy, nalezeny a použity.
Microsoft. AspNetCore. HostFiltering Hostitelé povoleni.
Microsoft. AspNetCore. hosting Doba, po kterou trvalo dokončení požadavků HTTP a čas jejich spuštění. Která hostující spouštěcí sestavení byla načtena.
Microsoft. AspNetCore. Mvc MVC a Razor Diagnostika. Vazba modelů, spuštění filtru, zobrazení kompilace, výběr akce.
Microsoft. AspNetCore. Routing Informace o shodě trasy.
Microsoft. AspNetCore. Server Připojení – spouštění, zastavování a udržování reakcí na Alive. Informace o certifikátu HTTPS
Microsoft. AspNetCore. StaticFiles Soubory byly obsluhovány.
Microsoft. EntityFrameworkCore Obecná diagnostika Entity Framework Core. Databázová aktivita a konfigurace, detekce změn, migrace.

Chcete-li zobrazit více kategorií v okně konzoly, nastavte appsettings.Development.jsna následující:

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

Rozsahy protokolů

Obor může seskupit sadu logických operací. Toto seskupení lze použít pro připojení stejných dat ke každému protokolu, který je vytvořen jako součást sady. Každý protokol vytvořený jako součást zpracování transakce může například zahrnovat ID transakce.

Rozsah:

Následující poskytovatelé podporují obory:

Použití oboru zabalením volání protokolovacího nástroje v using bloku:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _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);
}

Následující JSON umožňuje obory pro poskytovatele konzoly:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": true, // Required to use Scopes.
      "LogLevel": {
        "Microsoft": "Warning",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Následující kód umožňuje obory pro poskytovatele konzoly:

Obecně platí, že by protokolování mělo být specifikováno v konfiguraci a nikoli kódu.

Vestavění zprostředkovatelé protokolování

ASP.NET Core obsahuje následující zprostředkovatele protokolování:

Informace o stdout a ladění protokolování pomocí modulu ASP.NET Core naleznete v tématu Řešení ASP.NET Core potíží s Azure App Service a službou IIS a Modul ASP.NET Core .

Konzola

ConsoleZprostředkovatel protokoluje výstup do konzoly. Další informace o zobrazení Console protokolů ve vývoji najdete v tématu protokolování výstupu z dotnet Run a Visual Studio.

Ladění

DebugZprostředkovatel zapisuje výstup protokolu pomocí třídy System. Diagnostics. Debug . Volání pro System.Diagnostics.Debug.WriteLine zápis do Debug poskytovatele.

V systému Linux Debug je umístění protokolu zprostředkovatele závislé na distribuci a může to být jedna z následujících:

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

Zdroj události

EventSourceZprostředkovatel zapisuje do zdroje událostí pro různé platformy s názvem Microsoft-Extensions-Logging . Ve Windows zprostředkovatel používá ETW.

nástroje pro trasování dotnet

Nástroj dotnet-Trace je globální nástroj CLI pro různé platformy, který umožňuje shromažďování trasování .NET Core pro běžící proces. Nástroj shromažďuje Microsoft.Extensions.Logging.EventSource data zprostředkovatele pomocí LoggingEventSource .

Pokyny k instalaci naleznete v tématu dotnet-Trace .

Shromažďování trasování z aplikace pomocí trasovacích nástrojů dotnet:

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

  2. Určení identifikátoru procesu (PID) aplikace .NET Core:

    Vyhledejte kód PID pro proces, který má stejný název jako sestavení aplikace.

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

    Obecná syntaxe příkazu:

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

    Při použití příkazového prostředí PowerShellu uzavřete --providers hodnotu do jednoduchých uvozovek ( ' ):

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

    Na platformách jiných než Windows přidejte -f speedscope možnost změny formátu výstupní trasovacího souboru na speedscope .

    Klíčové slovo Popis
    1 Protokoluje meta události týkající se LoggingEventSource . Neprotokoluje události z ILogger ).
    2 Zapne Message událost při ILogger.Log() volání metody. Poskytuje informace v programovém (neformátovaném) způsobu.
    4 Zapne FormatMessage událost při ILogger.Log() volání metody. Poskytuje formátovanou verzi řetězce informací.
    8 Zapne MessageJson událost při ILogger.Log() volání metody. Poskytuje reprezentace argumentů ve formátu JSON.
    Úroveň události Popis
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    FilterSpecspoložky pro {Logger Category} a {Event Level} reprezentují další podmínky filtrování protokolů. Jednotlivé FilterSpecs položky oddělte středníkem ( ; ).

    Příklad použití příkazového prostředí systému Windows (bez jednoduchých uvozovek kolem --providers hodnoty):

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

    Předchozí příkaz se aktivuje:

    • Protokolovací nástroj zdroje událostí pro vytváření formátovaných řetězců ( 4 ) pro chyby ( 2 ).
    • Microsoft.AspNetCore.Hostingprotokolování na Informational úrovni protokolování ( 4 ).

  4. Kliknutím na klávesu ENTER nebo stisknutím kombinace kláves CTRL + C zastavte nástroje pro trasování dotnet.

    Trasování je uloženo s názvem Trace. nettrace ve složce, ve které dotnet trace je příkaz spuštěn.

  5. Otevřete trasování pomocí PerfView. Otevřete soubor Trace. nettrace a prozkoumejte události trasování.

Pokud aplikace nevytváří hostitele pomocí CreateDefaultBuilder , přidejte poskytovatele zdroje událostí do konfigurace protokolování aplikace.

Další informace naleznete v tématu:

PerfView

K shromažďování a zobrazování protokolů použijte Nástroj PerfView . Existují i další nástroje pro zobrazení protokolů ETW, ale PerfView poskytuje nejlepší prostředí pro práci s událostmi trasování událostí pro Windows vygenerovanými ASP.NET Core.

Pokud chcete nakonfigurovat PerfView pro shromažďování událostí protokolovaných tímto poskytovatelem, přidejte řetězec *Microsoft-Extensions-Logging do seznamu další poskytovatelé . Nechybíš na * začátku řetězce.

Protokol událostí systému Windows

EventLogZprostředkovatel odešle výstup protokolu do protokolu událostí systému Windows. Na rozdíl od jiných zprostředkovatelů EventLog nedědí zprostředkovatel not výchozí nastavení bez zprostředkovatele. Pokud EventLog není nastavení protokolu zadané, použijí se ve výchozím nastavení možnost LogLevel. Warning.

Chcete-li protokolovat události nižší než LogLevel.Warning , explicitně nastavte úroveň protokolu. Následující příklad nastaví výchozí úroveň protokolu událostí na LogLevel.Information :

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

Přetížení AddEventLog můžou být předána EventLogSettings . Pokud null není zadaný, použijí se následující výchozí nastavení:

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

Následující kód změní SourceName výchozí hodnotu z na ".NET Runtime" 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 poskytovatele 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 Azure Storagem účtu.

Balíček poskytovatele není zahrnutý ve sdíleném rozhraní. Chcete-li použít poskytovatele, přidejte do projektu balíček poskytovatele.

Chcete-li konfigurovat nastavení zprostředkovatele, použijte 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>();
                });
    }
}

Při nasazení do Azure App Service aplikace používá nastavení v části protokoly App Service stránky App Service Azure Portal. Když se aktualizují následující nastavení, změny se projeví okamžitě bez nutnosti restartování nebo opětovného nasazení aplikace.

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

Výchozí umístění souborů protokolu je ve složce *D: Home program \ \ Logfiles \ * a výchozí název souboru je diagnostics-yyyymmdd.txt. Výchozí omezení 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 poskytovatel se zaprotokoluje, jenom když se projekt spustí v prostředí Azure.

Streamování protokolů Azure

Streamování protokolů Azure podporuje zobrazení aktivity protokolu v reálném čase z:

  • Aplikační server
  • Webový server
  • Trasování chybných požadavků

Konfigurace streamování protokolů Azure:

  • Na stránce portálu aplikace přejděte na stránku protokoly App Service .
  • Nastavte protokolování aplikace (systém souborů) na zapnuto.
  • Vyberte úroveňprotokolu. Toto nastavení platí jenom pro streamování protokolů Azure.

Pokud chcete zobrazit protokoly, přejděte na stránku streamu protokolu . Protokolované zprávy jsou protokolovány pomocí ILogger rozhraní.

Azure Application Insights

Balíček poskytovatele Microsoft. Extensions. Logging. ApplicationInsights zapisuje protokoly do Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a poskytuje nástroje pro dotazování a analýzu dat telemetrie. Pokud použijete tohoto poskytovatele, můžete zadávat dotazy a analyzovat protokoly pomocí Application Insightsch nástrojů.

Zprostředkovatel protokolování je zahrnutý jako závislost na Microsoft. ApplicationInsights. AspNetCore, což je balíček, který poskytuje veškerou dostupnou telemetrii pro ASP.NET Core. Pokud použijete tento balíček, nemusíte instalovat balíček poskytovatele.

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

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

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

Protokolovací architektury třetích stran, které pracují s ASP.NET Core:

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

Použití architektury třetí strany se podobá použití jednoho z vestavěných zprostředkovatelů:

  1. Přidejte do projektu balíček NuGet.
  2. Zavolejte ILoggerFactory metodu rozšíření poskytovanou protokolovacím rozhraním.

Další informace najdete v dokumentaci pro každého poskytovatele. Microsoft nepodporuje zprostředkovatele protokolování třetích stran.

Konzolová aplikace bez hostitele

Příklad použití obecného hostitele v aplikaci jiné než webové konzoly najdete v souboru program.cs ukázkové aplikace úlohy na pozadí ( Úlohy na pozadí s hostovanými službami v ASP.NET Core ).

Kód protokolování pro aplikace bez obecného hostitele se liší v způsobu Přidání zprostředkovatelů a vytváření protokolovacíchnástrojů.

Zprostředkovatelé protokolování

V konzolové aplikaci, která není hostitelem, zavolejte Add{provider name} metodu rozšíření poskytovatele při vytváření LoggerFactory :

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");
    }
}

Vytvořit protokoly

K vytváření protokolů použijte ILogger<TCategoryName> objekt. Použijte LoggerFactory k vytvoření ILogger .

Následující příklad vytvoří protokolovací LoggingConsoleApp.Program Nástroj s jako kategorie.

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ích příkladech ASP.NET základního nástroje se k vytváření protokolů s jako úroveň používá protokolovací nástroj Information . Úroveň protokolu 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ě a kategorie jsou podrobněji vysvětleny v tomto dokumentu.

Přihlášení během konstrukce hostitele

Protokolování během konstrukce hostitele není přímo podporováno. Lze však použít samostatný protokolovací nástroj. V následujícím příkladu se k přihlášení používá protokolovací nástroj Serilog CreateHostBuilder . AddSerilogpoužívá statickou konfiguraci zadanou v 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 ILogger

Vložení konstruktoru protokolovacího nástroje do Startup sady Works v dřívějších verzích ASP.NET Core, protože pro webového hostitele je vytvořen samostatný kontejner di. Informace o tom, proč je pro obecného hostitele vytvořeno jenom jeden kontejner, najdete v části oznámení o změně.

Chcete-li nakonfigurovat službu, která závisí na ILogger<T> , použijte injektáže konstruktoru nebo poskytněte metodu pro vytváření. Přístup k metodě pro vytváření je doporučen pouze v případě, že není k dispozici žádná jiná možnost. Představte si třeba službu, která potřebuje ILogger<T> instanci poskytovanou výrazem di:

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

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

Předchozí zvýrazněný kód je Func , který se spouští při prvním, kdy musí kontejner di vytvořit instanci MyService . Tímto způsobem můžete získat přístup k libovolné registrované službě.

Vytváření protokolů v Main

Následující kód se přihlásí po Main získání ILogger instance z di po sestavení hostitele:

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

Vytvořit protokoly při spuštění

Následující kód zapisuje protokoly v 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();
    });
}

Zápis protokolů před dokončením nastavení DI Container v metodě není Startup.ConfigureServices podporován:

  • Vkládání protokolovacího nástroje do Startup konstruktoru není podporováno.
  • Vkládání protokolovacího nástroje do Startup.ConfigureServices signatury metody není podporováno.

Důvodem tohoto omezení je, že protokolování závisí na DI a na konfiguraci, která v systému zapíná na DI. Kontejner DI není nastavený, dokud se ConfigureServices nedokončí.

Informace o konfiguraci služby, která závisí na ILogger<T> nebo proč konstruktor, který se má Startup přepracovat v dřívějších verzích, najdete v tématu Konfigurace služby, která závisí na ILogger .

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

Protokolování by mělo být tak rychlé, aby neplatilo náklady na výkon asynchronního kódu. Pokud je úložiště dat protokolování pomalé, nezapište ho přímo. Nejprve zvažte možnost zapsat zprávy protokolu do rychlého úložiště a pak je přesunout do pomalého úložiště později. Například když se přihlásíte k SQL Server, neprovádějte přímo v Log metodě, protože Log metody jsou synchronní. Místo toho můžete synchronně přidat protokolové zprávy do fronty v paměti a nechat pracovní proces na pozadí získat zprávy z fronty, aby asynchronní operace vkládání dat do SQL Server. Další informace najdete v tomto problému GitHubu.

Změna úrovní protokolu v běžící aplikaci

Rozhraní API pro protokolování neobsahuje scénář pro změnu úrovní protokolu, když je aplikace spuštěná. Někteří poskytovatelé konfigurace ale mohou znovu načíst konfiguraci, která se projeví okamžitě při konfiguraci protokolování. Například Poskytovatel konfigurace souboruznovu načte konfiguraci protokolování do výchozího nastavení. Pokud se konfigurace v kódu změní, když je aplikace spuštěná, může aplikace volat IConfigurationRoot. Load , aby se aktualizovala konfigurace protokolování aplikace.

ILogger a ILoggerFactory

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

Použít pravidla filtru protokolů v kódu

Upřednostňovaným přístupem k nastavení pravidel filtru protokolů je použití Konfigurace.

Následující příklad ukazuje, jak registrovat pravidla filtru 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>();
            });
}

logging.AddFilter("System", LogLevel.Debug)Určuje System kategorii a úroveň protokolu Debug . Filtr se použije pro všechny poskytovatele, protože nebyl nakonfigurovaný konkrétní zprostředkovatel.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)upřesňuj

  • DebugZprostředkovatel protokolování.
  • Úroveň protokolu Information a vyšší.
  • Všechny kategorie počínaje "Microsoft" .

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

K přidání vlastního protokolovacího nástroje přidejte ILoggerProvider ILoggerFactory :

public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory.AddProvider(new CustomLoggerProvider(new CustomLoggerConfiguration()));

ILoggerProviderVytvoří jednu nebo více ILogger instancí. ILoggerInstance používá rozhraní k protokolování informací.

Ukázka vlastní konfigurace protokolovacího nástroje

Ukázka:

  • Je navržený jako velmi základní vzorek, který nastavuje barvu konzoly protokolu podle ID události a úrovně protokolu. Protokolovací nástroje se obecně nemění podle ID události a nevztahují se na úroveň protokolu.
  • Vytvoří různé položky konzoly barev na úrovni protokolu a ID události s použitím následujícího typu konfigurace:
public class ColorConsoleLoggerConfiguration
{
    public LogLevel LogLevel { get; set; } = LogLevel.Warning;
    public int EventId { get; set; } = 0;
    public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
}

Předchozí kód nastaví výchozí úroveň na Warning a barvu na Yellow . Pokud EventId je nastavené na 0, protokolují se všechny události.

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

ILoggerNázev kategorie implementace je obvykle zdrojem protokolování. Například typ, ve kterém je vytvořen protokolovací nástroj:

public class ColorConsoleLogger : ILogger
{
    private readonly string _name;
    private readonly ColorConsoleLoggerConfiguration _config;

    public ColorConsoleLogger(string name, ColorConsoleLoggerConfiguration config)
    {
        _name = name;
        _config = config;
    }

    public IDisposable BeginScope<TState>(TState state)
    {
        return null;
    }

    public bool IsEnabled(LogLevel logLevel)
    {
        return logLevel == _config.LogLevel;
    }

    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, 
                        Exception exception, Func<TState, Exception, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        if (_config.EventId == 0 || _config.EventId == eventId.Id)
        {
            var color = Console.ForegroundColor;
            Console.ForegroundColor = _config.Color;
            Console.WriteLine($"{logLevel} - {eventId.Id} " +
                              $"- {_name} - {formatter(state, exception)}");
            Console.ForegroundColor = color;
        }
    }
}

Předcházející kód:

  • Vytvoří instanci protokolovacího nástroje pro název kategorie.
  • Vrátí logLevel == _config.LogLevel IsEnabled se změnami, takže každá z nich logLevel má jedinečný protokolovací nástroj. Obecně platí, že protokolovací nástroje by měly být povolené i pro všechny vyšší úrovně protokolu:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

Vytvoření vlastního LoggerProvider

LoggerProviderJe třída, která vytváří instance protokolovacího nástroje. Možná není nutné vytvořit instanci protokolovacího nástroje na kategorii, ale to dává smysl pro některé protokolovací nástroje, jako je NLog nebo log4net. V případě potřeby také můžete zvolit různé cíle pro výstup protokolování na kategorii:

public class ColorConsoleLoggerProvider : ILoggerProvider
{
    private readonly ColorConsoleLoggerConfiguration _config;
    private readonly ConcurrentDictionary<string, ColorConsoleLogger> _loggers = new ConcurrentDictionary<string, ColorConsoleLogger>();

    public ColorConsoleLoggerProvider(ColorConsoleLoggerConfiguration config)
    {
        _config = config;
    }

    public ILogger CreateLogger(string categoryName)
    {
        return _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _config));
    }

    public void Dispose()
    {
        _loggers.Clear();
    }
}

V předchozím kódu CreateLogger vytvoří jednu instanci pro ColorConsoleLogger název kategorie a uloží ji do ConcurrentDictionary<TKey,TValue> ;

Využití a registrace vlastního protokolovacího nástroje

Zaregistrujte protokolovací nástroj v Startup.Configure :

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
                      ILoggerFactory loggerFactory)
{
    // Default registration.
    loggerFactory.AddProvider(new ColorConsoleLoggerProvider(
                              new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Error,
        Color = ConsoleColor.Red
    }));

    // Custom registration with default values.
    loggerFactory.AddColorConsoleLogger();

    // Custom registration with a new configuration instance.
    loggerFactory.AddColorConsoleLogger(new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Debug,
        Color = ConsoleColor.Gray
    });

    // Custom registration with a configuration object.
    loggerFactory.AddColorConsoleLogger(c =>
    {
        c.LogLevel = LogLevel.Information;
        c.Color = ConsoleColor.Blue;
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Pro předchozí kód zadejte alespoň jednu metodu rozšíření pro ILoggerFactory :

public static class ColorConsoleLoggerExtensions
{
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory, 
                                      ColorConsoleLoggerConfiguration config)
    {
        loggerFactory.AddProvider(new ColorConsoleLoggerProvider(config));
        return loggerFactory;
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory)
    {
        var config = new ColorConsoleLoggerConfiguration();
        return loggerFactory.AddColorConsoleLogger(config);
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                    this ILoggerFactory loggerFactory, 
                                    Action<ColorConsoleLoggerConfiguration> configure)
    {
        var config = new ColorConsoleLoggerConfiguration();
        configure(config);
        return loggerFactory.AddColorConsoleLogger(config);
    }
}

Další zdroje

Tím, že Dykstra a Steve Smith

.NET Core podporuje protokolovací rozhraní API, které funguje s řadou integrovaných poskytovatelů protokolování a jiných výrobců. V tomto článku se dozvíte, jak používat rozhraní API protokolování s integrovanými poskytovateli.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Přidat zprostředkovatele

Zprostředkovatel protokolování zobrazuje nebo ukládá protokoly. Například poskytovatel konzoly zobrazuje protokoly v konzole nástroje a poskytovatel Azure Application Insights je ukládá do Azure Application Insights. Protokoly lze odesílat do více cílů přidáním více zprostředkovatelů.

Chcete-li přidat poskytovatele, zavolejte Add{provider name} metodu rozšíření poskytovatele v program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Předchozí kód vyžaduje odkazy na Microsoft.Extensions.Logging a Microsoft.Extensions.Configuration .

Výchozí volání šablony projektu CreateDefaultBuilder , které přidává následující zprostředkovatele protokolování:

  • Konzola
  • Ladění
  • EventSource (počínaje ASP.NET Core 2,2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Pokud používáte CreateDefaultBuilder , můžete výchozí poskytovatele nahradit vašimi vlastními možnostmi. Zavolejte ClearProviders a přidejte poskytovatele, které chcete.

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Přečtěte si další informace o integrovaných poskytovatelích protokolování a zprostředkovatelích protokolování třetích stran v tomto článku.

Vytvořit protokoly

K vytváření protokolů použijte ILogger<TCategoryName> objekt. V rámci webové aplikace nebo hostované služby Získejte ILogger od vložení závislostí (di). V konzolových aplikacích bez hostitele použijte LoggerFactory k vytvoření ILogger .

Následující ASP.NET Core příklad vytvoří protokolovací TodoApiSample.Pages.AboutModel Nástroj s jako kategorie. Kategorie protokolu je řetězec, který je spojený s každým protokolem. ILogger<T>Instance poskytovaná di vytvoří protokoly, které mají plně kvalifikovaný název typu T jako kategorie.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

V následujících příkladech ASP.NET Core a konzolových aplikací se k vytváření protokolů s jako úroveň používá protokolovací nástroj Information . Úroveň protokolu označuje závažnost protokolované události.

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

Úrovně a kategorie jsou podrobněji vysvětleny dále v tomto článku.

Vytvořit protokoly při spuštění

Chcete-li zapsat protokoly ve Startup třídě, zahrňte ILogger parametr do signatury konstruktoru:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseMvc();
    }
}

Vytvořit protokoly ve třídě program

Chcete-li zapsat protokoly ve Program třídě, Získejte ILogger instanci od typu di:

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Protokolování během konstrukce hostitele není přímo podporováno. Lze však použít samostatný protokolovací nástroj. V následujícím příkladu se k přihlášení používá protokolovací nástroj Serilog CreateWebHostBuilder . AddSerilogpoužívá statickou konfiguraci zadanou v Log.Logger :

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

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

    public static IWebHostBuilder CreateWebHostBuilder(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 WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

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

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

Protokolování by mělo být tak rychlé, aby neplatilo náklady na výkon asynchronního kódu. Pokud je úložiště dat protokolování pomalé, nezapište ho přímo. Nejprve zvažte možnost zapsat zprávy protokolu do rychlého úložiště a pak je později přesunout do pomalého úložiště. Například pokud se přihlašujete k SQL Server, nechcete provádět přímo v Log metodě, protože Log metody jsou synchronní. Místo toho můžete synchronně přidat protokolové zprávy do fronty v paměti a nechat pracovní proces na pozadí získat zprávy z fronty, aby asynchronní operace vkládání dat do SQL Server. Další informace najdete v tomto problému GitHubu.

Konfigurace

Konfigurace zprostředkovatele protokolování je poskytována jedním nebo více poskytovateli konfigurace:

  • Formáty souborů (INI, JSON a XML).
  • Argumenty příkazového řádku.
  • Proměnné prostředí.
  • Objekty rozhraní .NET v paměti.
  • Úložiště nešifrovaného tajného správce .
  • Šifrované uživatelské úložiště, například Azure Key Vault.
  • Vlastní poskytovatelé (nainstalováno nebo vytvořeno).

Například konfigurace protokolování je běžně poskytována v Logging části soubory nastavení aplikace. Následující příklad ukazuje obsah typické appsettings.Development.js souboru:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

LoggingVlastnost může mít LogLevel vlastnosti zprostředkovatele a log (zobrazí se konzola).

LogLevelVlastnost v rámci Logging Určuje minimální úroveň protokolu pro vybrané kategorie. V tomto příkladu se System Microsoft kategorie přihlásí na Information úrovni a všechny ostatní protokoly na Debug úrovni.

Další vlastnosti v části Logging zadat zprostředkovatele protokolování. Příklad je pro poskytovatele konzoly. Pokud zprostředkovatel podporuje obory protokolů, IncludeScopes označuje, zda jsou povoleny. Vlastnost poskytovatele (například Console v příkladu) může také určovat LogLevel vlastnost. LogLevelv rámci zprostředkovatele Určuje úrovně, které se mají protokolovat pro daného poskytovatele.

Pokud jsou úrovně specifikovány v Logging.{providername}.LogLevel , přepíše cokoli nastavené v Logging.LogLevel . Zvažte například následující kód JSON:

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

V předchozím formátu JSON Console nastavení zprostředkovatele přepíše předchozí (výchozí) úroveň protokolu.

Rozhraní API pro protokolování neobsahuje scénář pro změnu úrovní protokolu, když je aplikace spuštěná. Někteří poskytovatelé konfigurace ale mohou znovu načíst konfiguraci, která se projeví okamžitě při konfiguraci protokolování. Například Poskytovatel konfigurace souboru, který je přidán nástrojem CreateDefaultBuilder ke čtení souborů nastavení, ve výchozím nastavení znovu načte konfiguraci protokolování. Pokud se konfigurace v kódu změní, když je aplikace spuštěná, může aplikace volat IConfigurationRoot. Load , aby se aktualizovala konfigurace protokolování aplikace.

Informace o implementaci zprostředkovatelů konfigurace najdete v tématu Konfigurace v ASP.NET Core .

Ukázka výstupu protokolování

Pomocí ukázkového kódu zobrazeného v předchozí části se protokoly zobrazí v konzole nástroje při spuštění aplikace z příkazového řádku. Tady je příklad výstupu konzoly:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Předchozí protokoly byly vygenerovány vytvořením žádosti HTTP GET do ukázkové aplikace na adrese http://localhost:5000/api/todo/0 .

Tady je příklad stejného protokolu, který se zobrazí v okně ladění při spuštění ukázkové aplikace v aplikaci Visual Studio:

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Protokoly, které jsou vytvořené voláními, které jsou ILogger uvedené v předchozí části, začínají na "TodoApi". Protokoly, které začínají na kategorie Microsoft, jsou z ASP.NET Coreho kódu rozhraní. ASP.NET Core a kód aplikace používají stejné rozhraní API a poskytovatele protokolování.

Zbývající část tohoto článku vysvětluje několik podrobností a možností protokolování.

Balíčky NuGet

ILoggerRozhraní a ILoggerFactory jsou v Microsoft. Extensions. Loggings. Abstractsa výchozí implementace pro ně jsou v Microsoft. Extensions. Logging.

Kategorie protokolu

Při ILogger vytvoření objektu je pro něj zadána kategorie . Tato kategorie je součástí každé zprávy protokolu vytvořené pomocí této instance ILogger . Kategorie může být libovolný řetězec, ale konvence používá název třídy, jako je například "TodoApi. Controllers. TodoController".

Použijte ILogger<T> k získání ILogger instance, která používá plně kvalifikovaný název typu T jako kategorii:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Chcete-li explicitně zadat kategorii, zavolejte ILoggerFactory.CreateLogger :

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

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

Úroveň protokolování

Každý protokol Určuje LogLevel hodnotu. Úroveň protokolu označuje závažnost nebo důležitost. Můžete například zapsat Information protokol, pokud metoda končí normálně a Warning protokol, když metoda vrátí stavový kód 404 Nenalezeno .

Následující kód vytváří Information a Warning protokoluje:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

V předchozím kódu MyLogEvents.GetItem MyLogEvents.GetItemNotFound parametry a jsou ID události protokolu. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů poskytované zbývajícími parametry metody. Parametry metody jsou vysvětleny v části Šablona zprávy protokolu v tomto článku.

Metody protokolu, které zahrnují úroveň v názvu metody (například LogInformation a LogWarning ), jsou metody rozšíření pro ILogger. Tyto metody volají Log metodu, která přebírá LogLevel parametr. Metodu můžete zavolat Log přímo místo jedné z těchto rozšiřujících metod, ale syntaxe je poměrně složitá. Další informace naleznete v tématu ILogger a ve zdrojovém kódu rozšíření protokolovacíhonástroje.

ASP.NET Core definuje následující úrovně protokolu seřazené od nejnižší k nejvyšší závažnosti.

  • Trasování = 0

    Informace, které jsou obvykle užitečné pouze pro ladění. Tyto zprávy mohou obsahovat citlivá data aplikací, a proto by neměly být povoleny v produkčním prostředí. Ve výchozím nastavení zakázáno.

  • Ladění = 1

    Informace, které mohou být užitečné při vývoji a ladění. Příklad: Entering method Configure with flag set to true. Povolte Debug protokoly úrovně v produkčním prostředí jenom při řešení potíží, protože se jedná o velký objem protokolů.

  • Informace = 2

    Pro sledování obecného toku aplikace. Tyto protokoly obvykle mají nějakou dlouhodobou hodnotu. Příklad: Request received for path /api/todo

  • Upozornění = 3

    Pro neobvyklé nebo neočekávané události v toku aplikace. Ty můžou zahrnovat chyby nebo jiné podmínky, které nezpůsobí zastavení aplikace, ale možná bude nutné je prozkoumat. Zpracování výjimek je běžné místo pro použití Warning úrovně protokolu. Příklad: FileNotFoundException for file quotes.txt.

  • Chyba = 4

    Pro chyby a výjimky, které nelze zpracovat. Tyto zprávy indikují selhání aktuální aktivity nebo operace (jako je aktuální požadavek HTTP), ne při selhání celé aplikace. Příklad zprávy protokolu:Cannot insert record due to duplicate key violation.

  • Kritické = 5

    Chyby, které vyžadují okamžitou pozornost. Příklady: scénáře ztráty dat, nedostatek místa na disku.

Úroveň protokolu můžete použít k určení, kolik výstupu protokolu se zapisuje do konkrétního úložného média nebo okna pro zobrazení. Příklad:

  • V produkčním prostředí:
    • Protokolování na úrovni Trace přes Information vytváří velké množství podrobných zpráv protokolu. Pokud chcete řídit náklady a nepřekročit limity úložiště dat, protokolujte Trace Information zprávy na úrovni do úložiště dat s nízkými náklady na velké objemy dat.
    • Přihlášení Warning přes Critical úrovně obvykle vytváří méně a menší zprávy protokolu. Proto náklady a limity úložiště většinou nejsou obavy, což má za následek větší flexibilitu výběru úložiště dat.
  • Během vývoje:
    • Umožňuje protokolovat Warning Critical zprávy do konzoly.
    • Trace Information Při odstraňování potíží přidejte zprávy.

Část filtrování protokolu dále v tomto článku vysvětluje, jak řídit, které úrovně protokolu zprostředkovateli zpracovává.

ASP.NET Core zapisuje protokoly pro události rozhraní .NET Framework. Příklady protokolů výše v tomto článku vyloučily nižší Information úrovně protokolů, takže se Debug Trace nevytvořily žádné protokoly ani protokoly na úrovni. Tady je příklad protokolů konzoly vytvořených spuštěním ukázkové aplikace nakonfigurované pro zobrazení Debug protokolů:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

ID události protokolu

Každý protokol může určovat ID události. Tato ukázková aplikace používá lokálně definovanou LoggingEvents třídu:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

public class LoggingEvents
{
    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 GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

ID události přidružuje sadu událostí. Například všechny protokoly související se zobrazením seznamu položek na stránce může být 1001.

Zprostředkovatel protokolování může ukládat ID události v poli ID, ve zprávě protokolování nebo vůbec ne. Zprostředkovatel ladění nezobrazuje ID událostí. Poskytovatel konzoly zobrazuje ID událostí v závorkách za kategorií:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

Šablona zprávy protokolu

Každý protokol Určuje šablonu zprávy. Šablona zprávy může obsahovat zástupné symboly, pro které jsou k dispozici argumenty. Použijte názvy zástupných symbolů, nikoli čísla.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

Pořadí zástupných symbolů, nikoli jejich názvů, určuje, které parametry slouží k zadání jejich hodnot. V následujícím kódu si všimněte, že názvy parametrů jsou v šabloně zprávy mimo pořadí:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Tento kód vytvoří zprávu protokolu s hodnotami parametrů v posloupnosti:

Parameter values: parm1, parm2

Protokolovací rozhraní funguje tímto způsobem, aby zprostředkovatelé protokolování mohli implementovat sémantické protokolování, označované také jako strukturované protokolování. Samotné argumenty jsou předány do protokolovacího systému, nikoli pouze ze šablony formátované zprávy. Tyto informace umožňují poskytovatelům protokolování ukládat hodnoty parametrů jako pole. Předpokládejme například, že volání metody protokolovacího nástroje vypadá takto:

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

Pokud odesíláte protokoly do služby Azure Table Storage, Každá entita tabulky Azure může mít ID vlastnosti a RequestTime , což zjednodušuje dotazy na data protokolu. Dotaz může najít všechny protokoly v rámci určitého RequestTime rozsahu, aniž by došlo k analýze časového limitu textové zprávy.

Protokolování výjimek

Metody protokolovacího nástroje mají přetížení, které umožňují předat výjimku, jak je uvedeno v následujícím příkladu:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Různí poskytovatelé zpracovávají informace o výjimce různými způsoby. Tady je příklad výstupu poskytovatele ladění z kódu uvedeného výše.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

Filtrování protokolů

Můžete zadat minimální úroveň protokolu pro konkrétního zprostředkovatele a kategorii nebo pro všechny poskytovatele nebo všechny kategorie. Všechny protokoly nižší než minimální úroveň nebudou tomuto poskytovateli předány, takže se nebudou zobrazovat ani ukládat.

Chcete-li potlačit všechny protokoly, zadejte LogLevel.None jako minimální úroveň protokolu. Celočíselná hodnota LogLevel.None je 6, což je více než LogLevel.Critical (5).

Vytvořit pravidla filtru v konfiguraci

Kód šablony projektu volá CreateDefaultBuilder k nastavení protokolování pro poskytovatele, konzolu, ladění a EventSource (ASP.NET Core 2,2 nebo novější). CreateDefaultBuilderMetoda nastaví protokolování tak, aby hledalo konfiguraci v Logging části, jak je vysvětleno výše v tomto článku.

Konfigurační data určují minimální úrovně protokolu podle poskytovatele a kategorie, jako v následujícím příkladu:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Tento kód JSON vytvoří šest pravidel filtru: jeden pro poskytovatele ladění, čtyři pro poskytovatele konzoly a jeden pro všechny poskytovatele. Při vytvoření objektu se vybere jedno pravidlo pro každého poskytovatele ILogger .

Filtrovat pravidla v kódu

Následující příklad ukazuje, jak registrovat pravidla filtru v kódu:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

Druhý AddFilter Určuje poskytovatele ladění pomocí jeho názvu typu. První AddFilter se vztahuje na všechny poskytovatele, protože neurčuje typ poskytovatele.

Jak se používají pravidla filtrování

Konfigurační data a AddFilter kód zobrazený v předchozích příkladech vytvoří pravidla uvedená v následující tabulce. Prvních šest přicházejí z příkladu konfigurace a poslední dva pocházejí z příkladu kódu.

Číslo Poskytovatel Kategorie, které začínají na... Minimální úroveň protokolování
1 Ladění Všechny kategorie Informace
2 Konzola Microsoft. AspNetCore. Mvc. Razor .. Vnitřních Upozornění
3 Konzola Microsoft. AspNetCore. Mvc. Razor ..Razor Ladění
4 Konzola Microsoft. AspNetCore. Mvc.Razor Chyba
5 Konzola Všechny kategorie Informace
6 Všichni poskytovatelé Všechny kategorie Ladění
7 Všichni poskytovatelé Systém Ladění
8 Ladění Partnerský vztah Microsoftu Trasování

Při ILogger vytvoření objektu ILoggerFactory vybere objekt jedno pravidlo pro každého poskytovatele, které se použije pro tento protokolovací nástroj. Všechny zprávy napsané ILogger instancí jsou filtrovány podle vybraných pravidel. V dostupných pravidlech se vybere nejpřesnější pravidlo pro jednotlivé dvojice zprostředkovatel a kategorie.

Následující algoritmus se používá pro každého poskytovatele při ILogger vytvoření pro danou kategorii:

  • Vyberte všechna pravidla, která se shodují se zprostředkovatelem nebo jeho aliasem. Pokud se nenajde žádná shoda, vyberte všechna pravidla s prázdným zprostředkovatelem.
  • Z výsledku předchozího kroku vyberte pravidla s nejdelší vyhovující předponou kategorie. Pokud se nenajde žádná shoda, vyberte všechna pravidla, která neurčují kategorii.
  • Pokud je vybráno více pravidel, vezměte Poslední z nich.
  • Pokud nejsou vybrána žádná pravidla, použijte MinimumLevel .

V předchozím seznamu pravidel Předpokládejme, že vytvoříte ILogger objekt pro kategorii "Microsoft. AspNetCore. Mvc. Razor . Razor ViewEngine":

  • Pro poskytovatele ladění platí pravidla 1, 6 a 8. Pravidlo 8 je nejvíce specifické, takže je to ten vybraný.
  • Pro poskytovatele konzoly platí pravidla 3, 4, 5 a 6. Pravidlo 3 je nejvíce specifické.

Výsledná ILogger instance odesílá protokoly Trace úrovně a výše do poskytovatele ladění. Protokoly Debug úrovně a výše jsou odesílány poskytovateli konzoly.

Aliasy zprostředkovatele

Každý zprostředkovatel definuje alias , který lze použít v konfiguraci místo plně kvalifikovaného názvu typu. Pro předdefinované poskytovatele použijte následující aliasy:

  • Konzola
  • Ladění
  • EventSource
  • EventLog
  • TraceSource
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Výchozí minimální úroveň

Existuje nastavení minimální úrovně, které se projeví pouze v případě, že se pro daného zprostředkovatele a kategorii nepoužijí žádná pravidla z konfigurace nebo kódu. Následující příklad ukazuje, jak nastavit minimální úroveň:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Pokud nenastavíte explicitně minimální úroveň, výchozí hodnota je Information , což znamená, že Trace protokoly a Debug budou ignorovány.

Funkce filtrování

Funkce filtru je vyvolána pro všechny poskytovatele a kategorie, které nemají pravidla přiřazena pomocí konfigurace nebo kódu. Kód ve funkci má přístup k typu poskytovatele, kategorii a úrovni protokolu. Příklad:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Systémové kategorie a úrovně

Tady je několik kategorií používaných ASP.NET Core a Entity Framework Core s poznámkami o tom, jaké protokoly se mají od nich očekávat:

Kategorie Poznámky
Microsoft. AspNetCore Obecná diagnostika ASP.NET Core.
Microsoft. AspNetCore. DataProtection Které klíče byly zváženy, nalezeny a použity.
Microsoft. AspNetCore. HostFiltering Hostitelé povoleni.
Microsoft. AspNetCore. hosting Doba, po kterou trvalo dokončení požadavků HTTP a čas jejich spuštění. Která hostující spouštěcí sestavení byla načtena.
Microsoft. AspNetCore. Mvc MVC a Razor Diagnostika. Vazba modelů, spuštění filtru, zobrazení kompilace, výběr akce.
Microsoft. AspNetCore. Routing Informace o shodě trasy.
Microsoft. AspNetCore. Server Připojení – spouštění, zastavování a udržování reakcí na Alive. Informace o certifikátu HTTPS
Microsoft. AspNetCore. StaticFiles Soubory byly obsluhovány.
Microsoft. EntityFrameworkCore Obecná diagnostika Entity Framework Core. Databázová aktivita a konfigurace, detekce změn, migrace.

Rozsahy protokolů

Obor může seskupit sadu logických operací. Toto seskupení lze použít pro připojení stejných dat ke každému protokolu, který je vytvořen jako součást sady. Každý protokol vytvořený jako součást zpracování transakce může například zahrnovat ID transakce.

Obor je IDisposable typ, který je vrácen BeginScope metodou a trvá, dokud nebude uvolněn. Použití oboru zabalením volání protokolovacího nástroje v using bloku:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

Následující kód umožňuje obory pro poskytovatele konzoly:

Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Poznámka

IncludeScopesAby bylo možné povolit protokolování na základě oboru, je nutné nakonfigurovat možnost protokolovacího nástroje konzoly.

Informace o konfiguraci najdete v části věnované konfiguraci .

Každá zpráva protokolu obsahuje informace s vymezeným oborem:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Vestavění zprostředkovatelé protokolování

ASP.NET Core dodává následující poskytovatele:

Informace o stdout a protokolování ladění pomocí modulu ASP.NET Core naleznete v tématu Řešení ASP.NET Core potíží s Azure App Service a službou IIS a Modul ASP.NET Core .

Poskytovatel konzoly

Balíček poskytovatele Microsoft. Extensions. Logging. Console odesílá výstup protokolu do konzoly.

logging.AddConsole();

Chcete-li zobrazit výstup protokolování konzoly, otevřete příkazový řádek ve složce projektu a spusťte následující příkaz:

dotnet run

Poskytovatel ladění

Balíček poskytovatele Microsoft. Extensions. Logging. Debug zapisuje výstup protokolu pomocí třídy System. Diagnostics. Debug ( Debug.WriteLine volání metody).

V systému Linux tento poskytovatel zapisuje protokoly do /var/log/Message.

logging.AddDebug();

Zprostředkovatel zdroje událostí

Balíček zprostředkovatele Microsoft. Extensions. Logging. EventSource zapisuje do zdroje událostí pro různé platformy s názvem Microsoft-Extensions-Logging . Ve Windows zprostředkovatel používá ETW.

logging.AddEventSourceLogger();

Poskytovatel zdroje událostí se přidá automaticky, když CreateDefaultBuilder se volá k sestavení hostitele.

K shromažďování a zobrazování protokolů použijte Nástroj PerfView . Existují i další nástroje pro zobrazení protokolů ETW, ale PerfView poskytuje nejlepší prostředí pro práci s událostmi trasování událostí pro Windows vygenerovanými ASP.NET Core.

Pokud chcete nakonfigurovat PerfView pro shromažďování událostí protokolovaných tímto poskytovatelem, přidejte řetězec *Microsoft-Extensions-Logging do seznamu další poskytovatelé . (Na začátku řetězce nechybíš hvězdičku.)

PerfView další poskytovatelé

Zprostředkovatel událostí systému Windows

Balíček poskytovatele Microsoft. Extensions. log. EventLog odesílá výstup protokolu do protokolu událostí systému Windows.

logging.AddEventLog();

AddEventLog přetížení umožňují předat EventLogSettings . Pokud null není zadaný, použijí se následující výchozí nastavení:

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

Události jsou protokolovány pro úroveň upozornění a vyšší. Následující příklad nastaví výchozí úroveň protokolu událostí na LogLevel.Information :

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

Poskytovatel TraceSource

Balíček poskytovatele Microsoft. Extensions. Logging. TraceSource používá TraceSource knihovny a poskytovatele.

logging.AddTraceSource(sourceSwitchName);

Přetížení AddTraceSource umožňují předat zdrojový přepínač a naslouchací proces trasování.

Aby bylo možné používat tohoto poskytovatele, aplikace musí běžet na .NET Framework (spíše než .NET Core). Poskytovatel může směrovat zprávy na celou řadu posluchačů, jako je například TextWriterTraceListener použití v ukázkové aplikaci.

Poskytovatel Azure App Service

Balíček poskytovatele 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 Azure Storagem účtu.

logging.AddAzureWebAppDiagnostics();

Balíček poskytovatele není zahrnutý ve službě Microsoft. AspNetCore. app Metapackage. Při cílení na .NET Framework nebo odkazování na Microsoft.AspNetCore.App Metapackage přidejte do projektu balíček poskytovatele.

AddAzureWebAppDiagnosticsPřetížení umožňuje předat AzureAppServicesDiagnosticsSettings . Objekt nastavení může přepsat výchozí nastavení, jako je například šablona výstupu protokolování, název objektu BLOB a omezení velikosti souboru. (Výstupní šablona je šablona zprávy, která se používá pro všechny protokoly kromě toho, co je k dispozici při ILogger volání metody.)

Když nasadíte aplikaci do App Service, aplikace respektuje nastavení v části protokoly App Service stránky App Service Azure Portal. Když se aktualizují následující nastavení, změny se projeví okamžitě bez nutnosti restartování nebo opětovného nasazení aplikace.

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

Výchozí umístění souborů protokolu je ve složce *D: Home program \ \ Logfiles \ * a výchozí název souboru je diagnostics-yyyymmdd.txt. Výchozí omezení 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.

Zprostředkovatel funguje pouze v případě, že projekt běží v prostředí Azure. Nemá žádný vliv, pokud se projekt spouští místně — , nepíše do místních souborů nebo místního vývojového úložiště pro objekty blob.

Streamování protokolů Azure

Streamování protokolů Azure umožňuje zobrazit aktivitu protokolu v reálném čase z:

  • Aplikační server
  • Webový server
  • Trasování chybných požadavků

Konfigurace streamování protokolů Azure:

  • Na stránce portálu vaší aplikace přejděte na stránku protokoly App Service .
  • Nastavte protokolování aplikace (systém souborů) na zapnuto.
  • Vyberte úroveňprotokolu. Toto nastavení platí jenom pro streamování protokolů Azure, ne pro jiné poskytovatele protokolování v aplikaci.

Pokud chcete zobrazit zprávy aplikace, přejděte na stránku streamu protokolu . Protokolují ho aplikace přes ILogger rozhraní.

Protokolování trasování Azure Application Insights

Balíček poskytovatele Microsoft. Extensions. Logging. ApplicationInsights zapisuje protokoly do Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a poskytuje nástroje pro dotazování a analýzu dat telemetrie. Pokud použijete tohoto poskytovatele, můžete zadávat dotazy a analyzovat protokoly pomocí Application Insightsch nástrojů.

Zprostředkovatel protokolování je zahrnutý jako závislost na Microsoft. ApplicationInsights. AspNetCore, což je balíček, který poskytuje veškerou dostupnou telemetrii pro ASP.NET Core. Pokud použijete tento balíček, nemusíte instalovat balíček poskytovatele.

Nepoužívejte balíček Microsoft. ApplicationInsights. Web — , který je pro ASP.NET 4. x.

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

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

Protokolovací architektury třetích stran, které pracují s ASP.NET Core:

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

Použití architektury třetí strany se podobá použití jednoho z vestavěných zprostředkovatelů:

  1. Přidejte do projektu balíček NuGet.
  2. Zavolejte ILoggerFactory metodu rozšíření poskytovanou protokolovacím rozhraním.

Další informace najdete v dokumentaci pro každého poskytovatele. Microsoft nepodporuje zprostředkovatele protokolování třetích stran.

Další materiály