Protokolování v .NET Core a ASP.NET CoreLogging in .NET Core and ASP.NET Core

Od Kirka Larkin, Juergen Gutsch a Rick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

.NET Core podporuje protokolovací rozhraní API, které funguje s řadou integrovaných poskytovatelů protokolování a jiných výrobců..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. V tomto článku se dozvíte, jak používat rozhraní API protokolování s integrovanými poskytovateli.This article shows how to use the logging API with built-in providers.

Většina příkladů kódu, které jsou uvedené v tomto článku, se nachází v ASP.NET Corech aplikacích.Most of the code examples shown in this article are from ASP.NET Core apps. Části těchto fragmentů kódu specifické pro protokolování se vztahují na libovolnou aplikaci .NET Core, která používá obecného hostitele.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Šablony ASP.NET Core webové aplikace používají obecného hostitele.The ASP.NET Core web app templates use the Generic Host.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)View or download sample code (how to download)

Zprostředkovatelé protokolováníLogging providers

Zprostředkovatelé protokolování uchovávají protokoly, s výjimkou Console poskytovatele, který zobrazuje protokoly.Logging providers store logs, except for the Console provider which displays logs. Poskytovatel Azure Application Insights například ukládá protokoly v Azure Application Insights.For example, the Azure Application Insights provider stores logs in Azure Application Insights. Je možné povolit více zprostředkovatelů.Multiple providers can be enabled.

Výchozí ASP.NET Core šablony webové aplikace:The default ASP.NET Core web app templates:

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.The preceding code shows the Program class created with the ASP.NET Core web app templates. Další části obsahují ukázky založené na šablonách ASP.NET Core webových aplikací, které používají obecného hostitele.The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. Další v tomto dokumentu jsou popsány v jiných než hostitelských konzolových aplikacích .Non-host console apps are discussed later in this document.

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í.To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. Například následující kód:For example, the following code:

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:For additional providers, see:

Vytvořit protokolyCreate logs

Chcete-li vytvořit protokoly, použijte ILogger<TCategoryName> objekt z Injektáže závislosti (di).To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

Následující příklad:The following example:

  • Vytvoří protokolovací nástroj, ILogger<AboutModel> který používá kategorii protokolu plně kvalifikovaného názvu typu AboutModel .Creates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. Kategorie protokolu je řetězec, který je spojený s každým protokolem.The log category is a string that is associated with each log.
  • Volání LogInformation do protokolu na Information úrovni.Calls LogInformation to log at the Information level. Úroveň protokolu označuje závažnost protokolované události.The Log level indicates the severity of the logged event.
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.Levels and categories are explained in more detail later in this document.

Informace o najdete v Blazor tématu vytvoření protokolů v Blazor nástroji Blazor WebAssembly a v tomto dokumentu.For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

Při vytváření protokolů v nástroji Main a Startup se dozvíte, jak vytvořit protokoly v Main a Startup .Create logs in Main and Startup shows how to create logs in Main and Startup.

Konfigurovat protokolováníConfigure logging

Konfigurace protokolování je běžně poskytována Logging oddílem appSettings. {Environment} soubory . JSON .Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. Následující appsettings.Development.jsv souboru vygeneruje šablony ASP.NET Core webové aplikace:The following appsettings.Development.json file is generated by the ASP.NET Core web app templates:

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

V předchozím kódu JSON:In the preceding JSON:

  • "Default" "Microsoft" "Microsoft.Hosting.Lifetime" Jsou určeny kategorie, a.The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • "Microsoft"Kategorie se vztahuje na všechny kategorie, které začínají na "Microsoft" .The "Microsoft" category applies to all categories that start with "Microsoft". Toto nastavení se vztahuje například na "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorii.For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • "Microsoft"Protokol kategorie na úrovni protokolu Warning a vyšším.The "Microsoft" category logs at log level Warning and higher.
  • "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šší.The "Microsoft.Hosting.Lifetime" category is more specific than the "Microsoft" category, so the "Microsoft.Hosting.Lifetime" category logs at log level "Information" and higher.
  • 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.A specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

LoggingVlastnost může mít LogLevel vlastnosti a log Provider.The Logging property can have LogLevel and log provider properties. LogLevelUrčuje minimální úroveň protokolu pro vybrané kategorie.The LogLevel specifies the minimum level to log for selected categories. V předchozím kódu JSON Information Warning jsou zadány úrovně protokolu.In the preceding JSON, Information and Warning log levels are specified. LogLeveloznačuje závažnost protokolu a rozsahů od 0 do 6:LogLevel indicates the severity of the log and ranges from 0 to 6:

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

Je-li LogLevel zadán parametr, je protokolování povoleno pro zprávy na zadané úrovni a vyšší.When a LogLevel is specified, logging is enabled for messages at the specified level and higher. V předchozím formátu JSON Default kategorie je protokolována Information a vyšší.In the preceding JSON, the Default category is logged for Information and higher. Například zprávy, Information , Warning Error a Critical jsou protokolovány.For example, Information, Warning, Error, and Critical messages are logged. Pokud LogLevel není zadaný, použije se jako výchozí Information úroveň protokolování.If no LogLevel is specified, logging defaults to the Information level. Další informace najdete v tématu úrovně protokolu.For more information, see Log levels.

Vlastnost zprostředkovatele může určovat LogLevel vlastnost.A provider property can specify a LogLevel property. LogLevelv části poskytovatel Určuje úrovně, které se mají protokolovat pro daného zprostředkovatele, a přepíše nastavení protokolu bez poskytovatele.LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. V souboru zvažte následující appsettings.js :Consider the following appsettings.json file:

{
  "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 .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. V předchozím formátu JSON Debug je výchozí úroveň protokolu poskytovatele nastavená na Information :In the preceding JSON, the Debug provider's default log level is set to 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 .The preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. Když je uvedena konkrétní kategorie, konkrétní kategorie přepíše výchozí kategorii.When a specific category is listed, the specific category overrides the default category. V předchozím formátu JSON Logging:Debug:LogLevel Kategorie "Microsoft.Hosting" a "Default" přepisují nastavení vLogging:LogLevelIn the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

Minimální úroveň protokolu může být zadána pro některý z těchto:The minimum log level can be specified for any of:

  • Konkrétní poskytovatelé: napříkladLogging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • Konkrétní kategorie: napříkladLogging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • Všichni zprostředkovatelé a všechny kategorie:Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

Všechny protokoly pod minimální úrovní nejsou:Any logs below the minimum level are not:

  • Předáno poskytovateli.Passed to the provider.
  • Protokolováno nebo zobrazeno.Logged or displayed.

Pokud chcete potlačit všechny protokoly, zadejte LogLevel. None.To suppress all logs, specify LogLevel.None. LogLevel.Nonemá hodnotu 6, která je vyšší než LogLevel.Critical (5).LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

Pokud zprostředkovatel podporuje obory protokolů, IncludeScopes označuje, zda jsou povoleny.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Další informace najdete v tématu rozsahy protokolů .For more information, see log scopes

Následující appsettings.js souboru obsahuje všechny poskytovatele povolené ve výchozím nastavení:The following appsettings.json file contains all the providers enabled by default:

{
  "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:In the preceding sample:

  • Kategorie a úrovně nejsou navrhovanými hodnotami.The categories and levels are not suggested values. Ukázka je k dispozici pro zobrazení všech výchozích zprostředkovatelů.The sample is provided to show all the default providers.
  • Nastavení v Logging.{providername}.LogLevel Nastavení přepsání v Logging.LogLevel .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Například úroveň v Debug.LogLevel.Default Přepisuje úroveň v LogLevel.Default .For example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • Použije se každý alias výchozího zprostředkovatele.Each default provider alias is used. Každý zprostředkovatel definuje alias , který lze použít v konfiguraci místo plně kvalifikovaného názvu typu.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Předdefinovaná aliasy zprostředkovatelů jsou:The built-in providers aliases are:
    • KonzolaConsole
    • LaděníDebug
    • EventSourceEventSource
    • EventLogEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

Nastavení úrovně protokolu podle příkazového řádku, proměnných prostředí a jiné konfiguraceSet log level by command line, environment variables, and other configuration

Úroveň protokolu může být nastavena libovolnými poskytovateli konfigurace.Log level can be set by any of the configuration providers.

:Oddělovač nefunguje s hierarchickými klíči proměnné prostředí na všech platformách.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, je dvojité podtržítko:__, the double underscore, is:

  • Podporováno všemi platformami.Supported by all platforms. Například : oddělovač není podporován bash, ale __ je.For example, the : separator is not supported by Bash, but __ is.
  • Automaticky nahrazeno :Automatically replaced by a :

Následující příkazy:The following commands:

  • Nastavte klíč prostředí Logging:LogLevel:Microsoft na hodnotu Information ve Windows.Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • Otestujte nastavení při použití aplikace vytvořené pomocí šablon webových aplikací ASP.NET Core.Test the settings when using an app created with the ASP.NET Core web application templates. dotnet runPříkaz musí být spuštěn v adresáři projektu po použití set .The dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Předchozí nastavení prostředí:The preceding environment setting:

  • Je nastaveno pouze v procesech spuštěných z příkazového okna, ve kterém byly nastaveny.Is only set in processes launched from the command window they were set in.
  • Není přečteno prohlížeči spuštěným v aplikaci Visual Studio.Isn't read by browsers launched with Visual Studio.

Následující příkaz setx taky nastavuje klíč a hodnotu prostředí ve Windows.The following setx command also sets the environment key and value on Windows. Na rozdíl set od setx platí, že nastavení jsou trvalá.Unlike set, setx settings are persisted. /MPřepínač nastaví proměnnou v prostředí systému.The /M switch sets the variable in the system environment. Pokud se /M nepoužívá, je nastavena proměnná prostředí uživatele.If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

V Azure App Servicena stránce Nastavení > konfigurace vyberte nové nastavení aplikace .On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service nastavení aplikace:Azure App Service application settings are:

  • Šifrované v klidovém stavu a přenášené přes zašifrovaný kanál.Encrypted at rest and transmitted over an encrypted channel.
  • Vystaveno jako proměnné prostředí.Exposed as environment variables.

Další informace najdete v tématu aplikace Azure: přepište konfiguraci aplikace pomocí webu Azure Portal.For more information, see Azure Apps: Override app configuration using the 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í.For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. 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 .For information on using other configuration sources, including the command line, Azure Key Vault, Azure App Configuration, other file formats, and more, see Konfigurace v ASP.NET Core.

Jak se používají pravidla filtrováníHow filtering rules are applied

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.When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Všechny zprávy napsané ILogger instancí jsou filtrovány podle vybraných pravidel.All messages written by an ILogger instance are filtered based on the selected rules. Z dostupných pravidel je vybráno pravidlo s nejpřesnější pro každou dvojici zprostředkovatelů a kategorií.The most specific rule for each provider and category pair is selected from the available rules.

Následující algoritmus se používá pro každého poskytovatele při ILogger vytvoření pro danou kategorii:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Vyberte všechna pravidla, která se shodují se zprostředkovatelem nebo jeho aliasem.Select all rules that match the provider or its alias. Pokud se nenajde žádná shoda, vyberte všechna pravidla s prázdným zprostředkovatelem.If no match is found, select all rules with an empty provider.
  • Z výsledku předchozího kroku vyberte pravidla s nejdelší vyhovující předponou kategorie.From the result of the preceding step, select rules with longest matching category prefix. Pokud se nenajde žádná shoda, vyberte všechna pravidla, která neurčují kategorii.If no match is found, select all rules that don't specify a category.
  • Pokud je vybráno více pravidel, vezměte Poslední z nich.If multiple rules are selected, take the last one.
  • Pokud nejsou vybrána žádná pravidla, použijte MinimumLevel .If no rules are selected, use MinimumLevel.

Výstup protokolování z příkazu dotnet Run a Visual StudioLogging output from dotnet run and Visual Studio

Zobrazí se protokoly vytvořené s výchozím zprostředkovatelem protokolování :Logs created with the default logging providers are displayed:

  • V nástroji Visual StudioIn Visual Studio
    • V okně výstup ladění při ladění.In the Debug output window when debugging.
    • V okně ASP.NET Core webový server.In the ASP.NET Core Web Server window.
  • V okně konzoly při spuštění aplikace s nástrojem dotnet run .In the console window when the app is run with dotnet run.

Protokoly, které začínají na kategoriích Microsoft, jsou z ASP.NET Coreho kódu rozhraní.Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core a kód aplikace používají stejné rozhraní API a poskytovatele protokolování.ASP.NET Core and application code use the same logging API and providers.

Kategorie protokoluLog category

Při ILogger vytvoření objektu je zadána kategorie .When an ILogger object is created, a category is specified. Tato kategorie je součástí každé zprávy protokolu vytvořené pomocí této instance ILogger .That category is included with each log message created by that instance of ILogger. Řetězec kategorie je libovolný, ale konvence používá název třídy.The category string is arbitrary, but the convention is to use the class name. Například na řadiči může být název "TodoApi.Controllers.TodoController" .For example, in a controller the name might be "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:The ASP.NET Core web apps use ILogger<T> to automatically get an ILogger instance that uses the fully qualified type name of T as the category:

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 :To explicitly specify the category, call 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 .ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Úroveň protokolováníLog level

Následující tabulka uvádí LogLevel hodnoty, Log{LogLevel} způsob rozšíření pohodlí a navrhované použití:The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel HodnotaValue MetodaMethod PopisDescription
TrasováníTrace 00 LogTrace Obsahuje nejpodrobnější zprávy.Contain the most detailed messages. Tyto zprávy mohou obsahovat citlivá data aplikací.These messages may contain sensitive app data. Tyto zprávy jsou ve výchozím nastavení zakázané a neměly by být povolené v produkčním prostředí.These messages are disabled by default and should not be enabled in production.
LaděníDebug 11 LogDebug Pro ladění a vývoj.For debugging and development. Používejte s opatrností v produkčním prostředí kvůli vysokému objemu.Use with caution in production due to the high volume.
InformaceInformation 22 LogInformation Sleduje obecný tok aplikace.Tracks the general flow of the app. Může mít dlouhodobou hodnotu.May have long-term value.
UpozorněníWarning 33 LogWarning Pro neobvyklé nebo neočekávané události.For abnormal or unexpected events. Obvykle obsahuje chyby nebo podmínky, které nezpůsobí selhání aplikace.Typically includes errors or conditions that don't cause the app to fail.
ChybaError 44 LogError Pro chyby a výjimky, které nelze zpracovat.For errors and exceptions that cannot be handled. Tyto zprávy označují selhání aktuální operace nebo žádosti, ne selhání celé aplikace.These messages indicate a failure in the current operation or request, not an app-wide failure.
KritickéCritical 55 LogCritical Chyby, které vyžadují okamžitou pozornost.For failures that require immediate attention. Příklady: scénáře ztráty dat, nedostatek místa na disku.Examples: data loss scenarios, out of disk space.
ŽádnýNone 66 Určuje, že kategorie protokolování by neměla zapisovat žádné zprávy.Specifies that a logging category should not write any messages.

V předchozí tabulce LogLevel je uveden od nejnižší k nejvyšší závažnosti.In the previous table, the LogLevel is listed from lowest to highest severity.

První parametr metody protokolu , LogLevel , označuje závažnost protokolu.The Log method's first parameter, LogLevel, indicates the severity of the log. Místo volání Log(LogLevel, ...) by většina vývojářů volala metody rozšíření log {LogLevel} .Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Log{LogLevel}Rozšiřující metody volají metodu protokolu a určují rozsah LogLevel.The Log{LogLevel} extension methods call the Log method and specify the LogLevel. Například následující dvě volání protokolování jsou funkčně ekvivalentní a tvoří stejný protokol:For example, the following two logging calls are functionally equivalent and produce the same log:

[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.MyLogEvents.TestItem is the event ID. MyLogEventsje součástí ukázkové aplikace a zobrazí se v části ID události protokolu .MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo a ToCtxString poskytuje balíček NuGet Rick.Docs. Samples. RouteInfo .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Metody zobrazují Controller informace o trasách.The methods display Controller route information.

Následující kód vytváří Information a Warning protokoluje:The following code creates Information and Warning logs:

[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.In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů poskytované zbývajícími parametry metody.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Parametry metody jsou vysvětleny v části Šablona zprávy dále v tomto dokumentu.The method parameters are explained in the message template section later in this document.

Zavolejte příslušnou Log{LogLevel} metodu, která určuje, kolik výstupu protokolu se zapisuje na konkrétní paměťové médium.Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. Příklad:For example:

  • V produkčním prostředí:In production:
    • Protokolování na úrovni Trace nebo Information vytváří velké množství podrobných zpráv protokolu.Logging at the Trace or Information levels produces a high-volume of detailed log messages. 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.To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. Zvažte omezení Trace a Information konkrétní kategorie.Consider limiting Trace and Information to specific categories.
    • Přihlášení Warning prostřednictvím Critical úrovní by mělo mít za následek několik zpráv protokolu.Logging at Warning through Critical levels should produce few log messages.
      • Náklady a limity úložiště většinou nejsou obavy.Costs and storage limits usually aren't a concern.
      • Několik protokolů umožňuje větší flexibilitu v možnostech úložiště dat.Few logs allow more flexibility in data store choices.
  • Ve vývoji:In development:
    • Nastavte na Warning.Set to Warning.
    • Přidání Trace Information zpráv při řešení potíží.Add Trace or Information messages when troubleshooting. Pro omezení výstupu, nastavení Trace nebo Information pouze pro kategorie v rámci šetření.To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core zapisuje protokoly pro události rozhraní .NET Framework.ASP.NET Core writes logs for framework events. Zvažte například výstup protokolu pro:For example, consider the log output for:

  • RazorAplikace stránky vytvořená pomocí šablon ASP.NET Core.A Razor Pages app created with the ASP.NET Core templates.
  • Protokolování je nastaveno naLogging:Console:LogLevel:Microsoft:InformationLogging set to Logging:Console:LogLevel:Microsoft:Information
  • Navigace na stránku ochrany osobních údajů:Navigation to the Privacy page:
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 :The following JSON sets Logging:Console:LogLevel:Microsoft:Information:

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

ID události protokoluLog event ID

Každý protokol může určovat ID události.Each log can specify an event ID. Ukázková aplikace používá MyLogEvents třídu k definování ID událostí:The sample app uses the MyLogEvents class to define event IDs:

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í.An event ID associates a set of events. Například všechny protokoly související se zobrazením seznamu položek na stránce může být 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Zprostředkovatel protokolování může ukládat ID události v poli ID, ve zprávě protokolování nebo vůbec ne.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Zprostředkovatel ladění nezobrazuje ID událostí.The Debug provider doesn't show event IDs. Poskytovatel konzoly zobrazuje ID událostí v závorkách za kategorií:The console provider shows event IDs in brackets after the category:

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.Some logging providers store the event ID in a field, which allows for filtering on the ID.

Šablona zprávy protokoluLog message template

Každé rozhraní API protokolu používá šablonu zprávy.Each log API uses a message template. Šablona zprávy může obsahovat zástupné symboly, pro které jsou k dispozici argumenty.The message template can contain placeholders for which arguments are provided. Použijte názvy zástupných symbolů, nikoli čísla.Use names for the placeholders, not numbers.

[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.The order of placeholders, not their names, determines which parameters are used to provide their values. V následujícím kódu jsou názvy parametrů mimo pořadí v šabloně zprávy:In the following code, the parameter names are out of sequence in the message template:

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í:The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

Tento přístup umožňuje zprostředkovatelům protokolování implementovat sémantické nebo strukturované protokolování.This approach allows logging providers to implement semantic or structured logging. Samotné argumenty jsou předány do protokolovacího systému, nikoli pouze ze šablony formátované zprávy.The arguments themselves are passed to the logging system, not just the formatted message template. To umožňuje zprostředkovatelům protokolování ukládat hodnoty parametrů jako pole.This enables logging providers to store the parameter values as fields. Zvažte například následující metodu protokolovacího nástroje:For example, consider the following logger method:

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

Například při protokolování do Azure Table Storage:For example, when logging to Azure Table Storage:

  • Každá entita tabulky Azure může mít ID RequestTime vlastnosti a.Each Azure Table entity can have ID and RequestTime properties.
  • Tabulky s vlastnostmi zjednodušují dotazy na data protokolu.Tables with properties simplify queries on logged data. 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.For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

Protokolovat výjimkyLog exceptions

Metody protokolovacího nástroje mají přetížení, která přijímají parametr výjimky:The logger methods have overloads that take an exception parameter:

[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 .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Metody zobrazují Controller informace o trasách.The methods display Controller route information.

Protokolování výjimek je specifické pro konkrétního zprostředkovatele.Exception logging is provider-specific.

Výchozí úroveň protokolováníDefault log level

Pokud není nastavená výchozí úroveň protokolování, je výchozí hodnota úrovně protokolu Information .If the default log level is not set, the default log level value is Information.

Zvažte například následující webovou aplikaci:For example, consider the following web app:

  • Vytvořeno pomocí šablon webové aplikace ASP.NET.Created with the ASP.NET web app templates.
  • appsettings.js a appsettings.Development.jspři odstranění nebo přejmenování.appsettings.json and appsettings.Development.json deleted or renamed.

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 .With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

Následující kód nastaví výchozí úroveň protokolování, pokud výchozí úroveň protokolu není nastavena v konfiguraci:The following code sets the default log level when the default log level is not set in configuration:

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.Generally, log levels should be specified in configuration and not code.

Filter – funkceFilter function

Funkce filtru je vyvolána pro všechny poskytovatele a kategorie, které nemají pravidla přiřazena pomocí konfigurace nebo kódu:A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code:

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šší.The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

Obecně platí, že úrovně protokolu by měly být zadány v konfiguraci a nikoli kódu.Generally, log levels should be specified in configuration and not code.

Kategorie ASP.NET Core a EF CoreASP.NET Core and EF Core categories

Následující tabulka obsahuje některé kategorie používané ASP.NET Core a Entity Framework Core s poznámkami k protokolům:The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

KategorieCategory PoznámkyNotes
Microsoft. AspNetCoreMicrosoft.AspNetCore Obecná diagnostika ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft. AspNetCore. DataProtectionMicrosoft.AspNetCore.DataProtection Které klíče byly zváženy, nalezeny a použity.Which keys were considered, found, and used.
Microsoft. AspNetCore. HostFilteringMicrosoft.AspNetCore.HostFiltering Hostitelé povoleni.Hosts allowed.
Microsoft. AspNetCore. hostingMicrosoft.AspNetCore.Hosting Doba, po kterou trvalo dokončení požadavků HTTP a čas jejich spuštění.How long HTTP requests took to complete and what time they started. Která hostující spouštěcí sestavení byla načtena.Which hosting startup assemblies were loaded.
Microsoft. AspNetCore. MvcMicrosoft.AspNetCore.Mvc MVC a Razor Diagnostika.MVC and Razor diagnostics. Vazba modelů, spuštění filtru, zobrazení kompilace, výběr akce.Model binding, filter execution, view compilation, action selection.
Microsoft. AspNetCore. RoutingMicrosoft.AspNetCore.Routing Informace o shodě trasy.Route matching information.
Microsoft. AspNetCore. ServerMicrosoft.AspNetCore.Server Připojení – spouštění, zastavování a udržování reakcí na Alive.Connection start, stop, and keep alive responses. Informace o certifikátu HTTPSHTTPS certificate information.
Microsoft. AspNetCore. StaticFilesMicrosoft.AspNetCore.StaticFiles Soubory byly obsluhovány.Files served.
Microsoft. EntityFrameworkCoreMicrosoft.EntityFrameworkCore Obecná diagnostika Entity Framework Core.General Entity Framework Core diagnostics. Databázová aktivita a konfigurace, detekce změn, migrace.Database activity and configuration, change detection, migrations.

Chcete-li zobrazit více kategorií v okně konzoly, nastavte appsettings.Development.jsna následující:To view more categories in the console window, set appsettings.Development.json to the following:

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

Rozsahy protokolůLog scopes

Obor může seskupit sadu logických operací.A scope can group a set of logical operations. Toto seskupení lze použít pro připojení stejných dat ke každému protokolu, který je vytvořen jako součást sady.This grouping can be used to attach the same data to each log that's created as part of a set. Každý protokol vytvořený jako součást zpracování transakce může například zahrnovat ID transakce.For example, every log created as part of processing a transaction can include the transaction ID.

Rozsah:A scope:

Následující poskytovatelé podporují obory:The following providers support scopes:

Použití oboru zabalením volání protokolovacího nástroje v using bloku:Use a scope by wrapping logger calls in a using block:

[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:The following JSON enables scopes for the console provider:

{
  "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:The following code enables scopes for the console provider:

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

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

Obecně platí, že by protokolování mělo být specifikováno v konfiguraci a nikoli kódu.Generally, logging should be specified in configuration and not code.

Vestavění zprostředkovatelé protokolováníBuilt-in logging providers

ASP.NET Core obsahuje následující zprostředkovatele protokolování:ASP.NET Core includes the following logging providers:

Informace o stdout a ladění protokolování pomocí modulu ASP.NET Core naleznete v tématu Řešení potíží s ASP.NET Core v Azure App Service a IIS a Modul ASP.NET Core .For information on stdout and debug logging with the ASP.NET Core Module, see Řešení potíží s ASP.NET Core v Azure App Service a IIS and Modul ASP.NET Core.

KonzolaConsole

ConsoleZprostředkovatel protokoluje výstup do konzoly.The Console provider logs output to the console. Další informace o zobrazení Console protokolů ve vývoji najdete v tématu protokolování výstupu z dotnet Run a Visual Studio.For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

LaděníDebug

DebugZprostředkovatel zapisuje výstup protokolu pomocí třídy System. Diagnostics. Debug .The Debug provider writes log output by using the System.Diagnostics.Debug class. Volání pro System.Diagnostics.Debug.WriteLine zápis do Debug poskytovatele.Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

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:On Linux, the Debug provider log location is distribution-dependent and may be one of the following:

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

Zdroj událostiEvent Source

EventSourceZprostředkovatel zapisuje do zdroje událostí pro různé platformy s názvem Microsoft-Extensions-Logging .The EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. Ve Windows zprostředkovatel používá ETW.On Windows, the provider uses ETW.

nástroje pro trasování dotnetdotnet trace tooling

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.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. Nástroj shromažďuje Microsoft.Extensions.Logging.EventSource data zprostředkovatele pomocí LoggingEventSource .The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Pokyny k instalaci naleznete v tématu dotnet-Trace .See dotnet-trace for installation instructions.

Shromažďování trasování z aplikace pomocí trasovacích nástrojů dotnet:Use the dotnet trace tooling to collect a trace from an app:

  1. Spusťte aplikaci pomocí dotnet run příkazu.Run the app with the dotnet run command.

  2. Určení identifikátoru procesu (PID) aplikace .NET Core:Determine the process identifier (PID) of the .NET Core app:

    Vyhledejte kód PID pro proces, který má stejný název jako sestavení aplikace.Find the PID for the process that has the same name as the app's assembly.

  3. Spusťte dotnet trace příkaz.Execute the dotnet trace command.

    Obecná syntaxe příkazu:General command syntax:

    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 ( ' ):When using a PowerShell command shell, enclose the --providers value in single quotes ('):

    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 .On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    Klíčové slovoKeyword PopisDescription
    11 Protokoluje meta události týkající se LoggingEventSource .Log meta events about the LoggingEventSource. Neprotokoluje události z ILogger ).Doesn't log events from ILogger).
    22 Zapne Message událost při ILogger.Log() volání metody.Turns on the Message event when ILogger.Log() is called. Poskytuje informace v programovém (neformátovaném) způsobu.Provides information in a programmatic (not formatted) way.
    44 Zapne FormatMessage událost při ILogger.Log() volání metody.Turns on the FormatMessage event when ILogger.Log() is called. Poskytuje formátovanou verzi řetězce informací.Provides the formatted string version of the information.
    88 Zapne MessageJson událost při ILogger.Log() volání metody.Turns on the MessageJson event when ILogger.Log() is called. Poskytuje reprezentace argumentů ve formátu JSON.Provides a JSON representation of the arguments.
    Úroveň událostiEvent Level PopisDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecspoložky pro {Logger Category} a {Event Level} reprezentují další podmínky filtrování protokolů.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Jednotlivé FilterSpecs položky oddělte středníkem ( ; ).Separate FilterSpecs entries with a semicolon (;).

    Příklad použití příkazového prostředí systému Windows (bez jednoduchých uvozovek kolem --providers hodnoty):Example using a Windows command shell (no single quotes around the --providers value):

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

    Předchozí příkaz se aktivuje:The preceding command activates:

    • Protokolovací nástroj zdroje událostí pro vytváření formátovaných řetězců ( 4 ) pro chyby ( 2 ).The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.Hostingprotokolování na Informational úrovni protokolování ( 4 ).Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. Kliknutím na klávesu ENTER nebo stisknutím kombinace kláves CTRL + C zastavte nástroje pro trasování dotnet.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    Trasování je uloženo s názvem Trace. nettrace ve složce, ve které dotnet trace je příkaz spuštěn.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. Otevřete trasování pomocí PerfView.Open the trace with Perfview. Otevřete soubor Trace. nettrace a prozkoumejte události trasování.Open the trace.nettrace file and explore the trace events.

Pokud aplikace nevytváří hostitele pomocí CreateDefaultBuilder , přidejte poskytovatele zdroje událostí do konfigurace protokolování aplikace.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

Další informace naleznete v tématu:For more information, see:

PerfViewPerfview

K shromažďování a zobrazování protokolů použijte Nástroj PerfView .Use the PerfView utility to collect and view logs. 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.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by 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é .To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. Nechybíš na * začátku řetězce.Don't miss the * at the start of the string.

Protokol událostí systému WindowsWindows EventLog

EventLogZprostředkovatel odešle výstup protokolu do protokolu událostí systému Windows.The EventLog provider sends log output to the Windows Event Log. Na rozdíl od jiných zprostředkovatelů EventLog nedědí zprostředkovatel not výchozí nastavení bez zprostředkovatele.Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. Pokud EventLog není nastavení protokolu zadané, použijí se ve výchozím nastavení možnost LogLevel. Warning.If EventLog log settings aren't specified, they default to LogLevel.Warning.

Chcete-li protokolovat události nižší než LogLevel.Warning , explicitně nastavte úroveň protokolu.To log events lower than LogLevel.Warning, explicitly set the log level. Následující příklad nastaví výchozí úroveň protokolu událostí na LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

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

Přetížení AddEventLog můžou být předána EventLogSettings .AddEventLog overloads can pass in EventLogSettings. Pokud null není zadaný, použijí se následující výchozí nastavení:If null or not specified, the following default settings are used:

  • LogName: "Application"LogName: "Application"
  • SourceName: ".NET runtime"SourceName: ".NET Runtime"
  • MachineName: Používá se název místního počítače.MachineName: The local machine name is used.

Následující kód změní SourceName výchozí hodnotu z na ".NET Runtime" MyLogs :The following code changes the SourceName from the default value of ".NET Runtime" to 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 ServiceAzure 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.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

Balíček poskytovatele není zahrnutý ve sdíleném rozhraní.The provider package isn't included in the shared framework. Chcete-li použít poskytovatele, přidejte do projektu balíček poskytovatele.To use the provider, add the provider package to the project.

Chcete-li konfigurovat nastavení zprostředkovatele, použijte AzureFileLoggerOptions a AzureBlobLoggerOptions , jak je znázorněno v následujícím příkladu:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

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.When deployed to Azure App Service, the app uses the settings in the App Service logs section of the App Service page of the 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.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Protokolování aplikace (systém souborů)Application Logging (Filesystem)
  • Protokolování aplikace (BLOB)Application Logging (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.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Výchozí omezení velikosti souboru je 10 MB a výchozí maximální počet uchovávaných souborů je 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Výchozí název objektu BLOB je {App-Name} {timestamp}/yyyy/mm/dd/hh/{guid} -applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Tento poskytovatel se zaprotokoluje, jenom když se projekt spustí v prostředí Azure.This provider only logs when the project runs in the Azure environment.

Streamování protokolů AzureAzure log streaming

Streamování protokolů Azure podporuje zobrazení aktivity protokolu v reálném čase z:Azure log streaming supports viewing log activity in real time from:

  • Aplikační serverThe app server
  • Webový serverThe web server
  • Trasování chybných požadavkůFailed request tracing

Konfigurace streamování protokolů Azure:To configure Azure log streaming:

  • Na stránce portálu aplikace přejděte na stránku protokoly App Service .Navigate to the App Service logs page from the app's portal page.
  • Nastavte protokolování aplikace (systém souborů) na zapnuto.Set Application Logging (Filesystem) to On.
  • Vyberte úroveňprotokolu.Choose the log Level. Toto nastavení platí jenom pro streamování protokolů Azure.This setting only applies to Azure log streaming.

Pokud chcete zobrazit protokoly, přejděte na stránku streamu protokolu .Navigate to the Log Stream page to view logs. Protokolované zprávy jsou protokolovány pomocí ILogger rozhraní.The logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

Balíček poskytovatele Microsoft. Extensions. Logging. ApplicationInsights zapisuje protokoly do Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a poskytuje nástroje pro dotazování a analýzu dat telemetrie.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Pokud použijete tohoto poskytovatele, můžete zadávat dotazy a analyzovat protokoly pomocí Application Insightsch nástrojů.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

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.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Pokud použijete tento balíček, nemusíte instalovat balíček poskytovatele.If you use this package, you don't have to install the provider package.

Balíček Microsoft. ApplicationInsights. Web je určen pro ASP.NET 4. x, nikoli ASP.NET Core.The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

Další informace naleznete v následujících zdrojích:For more information, see the following resources:

Zprostředkovatelé protokolování třetích stranThird-party logging providers

Protokolovací architektury třetích stran, které pracují s ASP.NET Core:Third-party logging frameworks that work with 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í.Some third-party frameworks can perform semantic logging, also known as structured logging.

Použití architektury třetí strany se podobá použití jednoho z vestavěných zprostředkovatelů:Using a third-party framework is similar to using one of the built-in providers:

  1. Přidejte do projektu balíček NuGet.Add a NuGet package to your project.
  2. Zavolejte ILoggerFactory metodu rozšíření poskytovanou protokolovacím rozhraním.Call an ILoggerFactory extension method provided by the logging framework.

Další informace najdete v dokumentaci pro každého poskytovatele.For more information, see each provider's documentation. Microsoft nepodporuje zprostředkovatele protokolování třetích stran.Third-party logging providers aren't supported by Microsoft.

Konzolová aplikace bez hostiteleNon-host console app

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 ).For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (Ú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ů.Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

Zprostředkovatelé protokolováníLogging providers

V konzolové aplikaci, která není hostitelem, zavolejte Add{provider name} metodu rozšíření poskytovatele při vytváření LoggerFactory :In a non-host console app, call the provider's Add{provider name} extension method while creating a 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 protokolyCreate logs

K vytváření protokolů použijte ILogger<TCategoryName> objekt.To create logs, use an ILogger<TCategoryName> object. Použijte LoggerFactory k vytvoření ILogger .Use the LoggerFactory to create an ILogger.

Následující příklad vytvoří protokolovací LoggingConsoleApp.Program Nástroj s jako kategorie.The following example creates a logger with LoggingConsoleApp.Program as the category.

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 .In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. Úroveň protokolu označuje závažnost protokolované události.The Log level indicates the severity of the logged event.

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.Levels and categories are explained in more detail in this document.

Přihlášení během konstrukce hostiteleLog during host construction

Protokolování během konstrukce hostitele není přímo podporováno.Logging during host construction isn't directly supported. Lze však použít samostatný protokolovací nástroj.However, a separate logger can be used. V následujícím příkladu se k přihlášení používá protokolovací nástroj Serilog CreateHostBuilder .In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilogpoužívá statickou konfiguraci zadanou v Log.Logger :AddSerilog uses the static configuration specified in 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 ILoggerConfigure a service that depends on 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.Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. Informace o tom, proč je pro obecného hostitele vytvořeno jenom jeden kontejner, najdete v části oznámení o změně.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Chcete-li nakonfigurovat službu, která závisí na ILogger<T> , použijte injektáže konstruktoru nebo poskytněte metodu pro vytváření.To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. Přístup k metodě pro vytváření je doporučen pouze v případě, že není k dispozici žádná jiná možnost.The factory method approach is recommended only if there is no other option. Představte si třeba službu, která potřebuje ILogger<T> instanci poskytovanou výrazem di:For example, consider a service that needs an ILogger<T> instance provided by 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 .The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. Tímto způsobem můžete získat přístup k libovolné registrované službě.You can access any of the registered services in this way.

Vytváření protokolů v MainCreate logs in Main

Následující kód se přihlásí po Main získání ILogger instance z di po sestavení hostitele:The following code logs in Main by getting an ILogger instance from DI after building the host:

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íCreate logs in Startup

Následující kód zapisuje protokoly v Startup.Configure :The following code writes logs in 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:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • Vkládání protokolovacího nástroje do Startup konstruktoru není podporováno.Logger injection into the Startup constructor is not supported.
  • Vkládání protokolovacího nástroje do Startup.ConfigureServices signatury metody není podporováno.Logger injection into the Startup.ConfigureServices method signature is not supported

Důvodem tohoto omezení je, že protokolování závisí na DI a na konfiguraci, která v systému zapíná na DI.The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. Kontejner DI není nastavený, dokud se ConfigureServices nedokončí.The DI container isn't set up until ConfigureServices finishes.

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 .For information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

Žádné metody asynchronního protokolovacího nástrojeNo asynchronous logger methods

Protokolování by mělo být tak rychlé, aby neplatilo náklady na výkon asynchronního kódu.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Pokud je úložiště dat protokolování pomalé, nezapište ho přímo.If a logging data store is slow, don't write to it directly. 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.Consider writing the log messages to a fast store initially, then moving them to the slow store later. 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í.For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. 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.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Další informace najdete v tomto problému GitHubu.For more information, see this GitHub issue.

Změna úrovní protokolu v běžící aplikaciChange log levels in a running app

Rozhraní API pro protokolování neobsahuje scénář pro změnu úrovní protokolu, když je aplikace spuštěná.The Logging API doesn't include a scenario to change log levels while an app is running. Někteří poskytovatelé konfigurace ale mohou znovu načíst konfiguraci, která se projeví okamžitě při konfiguraci protokolování.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Například Poskytovatel konfigurace souboruznovu načte konfiguraci protokolování do výchozího nastavení.For example, the File Configuration Provider, reloads logging configuration by default. 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.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

ILogger a ILoggerFactoryILogger and ILoggerFactory

ILogger<TCategoryName>Rozhraní a ILoggerFactory implementace jsou součástí .NET Core SDK.The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. Jsou také k dispozici v následujících balíčcích NuGet:They are also available in the following NuGet packages:

Použít pravidla filtru protokolů v kóduApply log filter rules in code

Upřednostňovaným přístupem k nastavení pravidel filtru protokolů je použití Konfigurace.The preferred approach for setting log filter rules is by using Configuration.

Následující příklad ukazuje, jak registrovat pravidla filtru v kódu:The following example shows how to register filter rules in code:

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 .logging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. Filtr se použije pro všechny poskytovatele, protože nebyl nakonfigurovaný konkrétní zprostředkovatel.The filter is applied to all providers because a specific provider was not configured.

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

  • DebugZprostředkovatel protokolování.The Debug logging provider.
  • Úroveň protokolu Information a vyšší.Log level Information and higher.
  • Všechny kategorie počínaje "Microsoft" .All categories starting with "Microsoft".

Vytvoření vlastního protokolovacího nástrojeCreate a custom logger

K přidání vlastního protokolovacího nástroje přidejte ILoggerProvider ILoggerFactory :To add a custom logger, add an ILoggerProvider with ILoggerFactory:

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

ILoggerProviderVytvoří jednu nebo více ILogger instancí.The ILoggerProvider creates one or more ILogger instances. ILoggerInstance používá rozhraní k protokolování informací.The ILogger instances are used by the framework to log the information.

Ukázka vlastní konfigurace protokolovacího nástrojeSample custom logger configuration

Ukázka:The sample:

  • Je navržený jako velmi základní vzorek, který nastavuje barvu konzoly protokolu podle ID události a úrovně protokolu.Is designed to be a very basic sample that sets the color of the log console by event ID and log level. Protokolovací nástroje se obecně nemění podle ID události a nevztahují se na úroveň protokolu.Loggers generally don't change by event ID and are not specific to log level.
  • Vytvoří různé položky konzoly barev na úrovni protokolu a ID události s použitím následujícího typu konfigurace:Creates different color console entries per log level and event ID using the following configuration type:
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 .The preceding code sets the default level to Warning and the color to Yellow. Pokud EventId je nastavené na 0, protokolují se všechny události.If the EventId is set to 0, we will log all events.

Vytvoření vlastního protokolovacího nástrojeCreate the custom logger

ILoggerNázev kategorie implementace je obvykle zdrojem protokolování.The ILogger implementation category name is typically the logging source. Například typ, ve kterém je vytvořen protokolovací nástroj:For example, the type where the logger is created:

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:The preceding code:

  • Vytvoří instanci protokolovacího nástroje pro název kategorie.Creates a logger instance per category name.
  • Vrátí logLevel == _config.LogLevel IsEnabled se změnami, takže každá z nich logLevel má jedinečný protokolovací nástroj.Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. Obecně platí, že protokolovací nástroje by měly být povolené i pro všechny vyšší úrovně protokolu:Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

Vytvoření vlastního LoggerProviderCreate the custom LoggerProvider

LoggerProviderJe třída, která vytváří instance protokolovacího nástroje.The LoggerProvider is the class that creates the logger instances. 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.Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. V případě potřeby také můžete zvolit různé cíle pro výstup protokolování na kategorii:Doing this you are also able to choose different logging output targets per category if needed:

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> ;In the preceding code, CreateLogger creates a single instance of the ColorConsoleLogger per category name and stores it in the ConcurrentDictionary<TKey,TValue>;

Využití a registrace vlastního protokolovacího nástrojeUsage and registration of the custom logger

Zaregistrujte protokolovací nástroj v Startup.Configure :Register the logger in the 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 :For the preceding code, provide at least one extension method for the 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ší zdrojeAdditional resources

Tím, že Dykstra a Steve SmithBy Tom Dykstra and Steve Smith

.NET Core podporuje protokolovací rozhraní API, které funguje s řadou integrovaných poskytovatelů protokolování a jiných výrobců..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. V tomto článku se dozvíte, jak používat rozhraní API protokolování s integrovanými poskytovateli.This article shows how to use the logging API with built-in providers.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)View or download sample code (how to download)

Přidat zprostředkovateleAdd providers

Zprostředkovatel protokolování zobrazuje nebo ukládá protokoly.A logging provider displays or stores logs. Například poskytovatel konzoly zobrazuje protokoly v konzole nástroje a poskytovatel Azure Application Insights je ukládá do Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Protokoly lze odesílat do více cílů přidáním více zprostředkovatelů.Logs can be sent to multiple destinations by adding multiple providers.

Chcete-li přidat poskytovatele, zavolejte Add{provider name} metodu rozšíření poskytovatele v program.cs:To add a provider, call the provider's Add{provider name} extension method in 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 .The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

Výchozí volání šablony projektu CreateDefaultBuilder , které přidává následující zprostředkovatele protokolování:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • KonzolaConsole
  • LaděníDebug
  • EventSource (počínaje ASP.NET Core 2,2)EventSource (starting in 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.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Zavolejte ClearProviders a přidejte poskytovatele, které chcete.Call ClearProviders, and add the providers you want.

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.Learn more about built-in logging providers and third-party logging providers later in the article.

Vytvořit protokolyCreate logs

K vytváření protokolů použijte ILogger<TCategoryName> objekt.To create logs, use an ILogger<TCategoryName> object. V rámci webové aplikace nebo hostované služby Získejte ILogger od vložení závislostí (di).In a web app or hosted service, get an ILogger from dependency injection (DI). V konzolových aplikacích bez hostitele použijte LoggerFactory k vytvoření ILogger .In non-host console apps, use the LoggerFactory to create an ILogger.

Následující ASP.NET Core příklad vytvoří protokolovací TodoApiSample.Pages.AboutModel Nástroj s jako kategorie.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. Kategorie protokolu je řetězec, který je spojený s každým protokolem.The log category is a string that is associated with each log. ILogger<T>Instance poskytovaná di vytvoří protokoly, které mají plně kvalifikovaný název typu T jako kategorie.The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

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 .In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. Úroveň protokolu označuje závažnost protokolované události.The Log level indicates the severity of the logged event.

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.Levels and categories are explained in more detail later in this article.

Vytvořit protokoly při spuštěníCreate logs in Startup

Chcete-li zapsat protokoly ve Startup třídě, zahrňte ILogger parametr do signatury konstruktoru:To write logs in the Startup class, include an ILogger parameter in the constructor signature:

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ě programCreate logs in the Program class

Chcete-li zapsat protokoly ve Program třídě, Získejte ILogger instanci od typu di:To write logs in the Program class, get an ILogger instance from 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.Logging during host construction isn't directly supported. Lze však použít samostatný protokolovací nástroj.However, a separate logger can be used. V následujícím příkladu se k přihlášení používá protokolovací nástroj Serilog CreateWebHostBuilder .In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilogpoužívá statickou konfiguraci zadanou v Log.Logger :AddSerilog uses the static configuration specified in 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ástrojeNo asynchronous logger methods

Protokolování by mělo být tak rychlé, aby neplatilo náklady na výkon asynchronního kódu.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Pokud je úložiště dat protokolování pomalé, nezapište ho přímo.If your logging data store is slow, don't write to it directly. 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ě.Consider writing the log messages to a fast store initially, then move them to the slow store later. 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í.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. 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.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Další informace najdete v tomto problému GitHubu.For more information, see this GitHub issue.

KonfiguraceConfiguration

Konfigurace zprostředkovatele protokolování je poskytována jedním nebo více poskytovateli konfigurace:Logging provider configuration is provided by one or more configuration providers:

  • Formáty souborů (INI, JSON a XML).File formats (INI, JSON, and XML).
  • Argumenty příkazového řádku.Command-line arguments.
  • Proměnné prostředí.Environment variables.
  • Objekty rozhraní .NET v paměti.In-memory .NET objects.
  • Úložiště nešifrovaného tajného správce .The unencrypted Secret Manager storage.
  • Šifrované uživatelské úložiště, například Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Vlastní poskytovatelé (nainstalováno nebo vytvořeno).Custom providers (installed or created).

Například konfigurace protokolování je běžně poskytována v Logging části soubory nastavení aplikace.For example, logging configuration is commonly provided by the Logging section of app settings files. Následující příklad ukazuje obsah typické appsettings.Development.js souboru:The following example shows the contents of a typical appsettings.Development.json file:

{
  "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).The Logging property can have LogLevel and log provider properties (Console is shown).

LogLevelVlastnost v rámci Logging Určuje minimální úroveň protokolu pro vybrané kategorie.The LogLevel property under Logging specifies the minimum level to log for selected categories. V tomto příkladu se System Microsoft kategorie přihlásí na Information úrovni a všechny ostatní protokoly na Debug úrovni.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Další vlastnosti v části Logging zadat zprostředkovatele protokolování.Other properties under Logging specify logging providers. Příklad je pro poskytovatele konzoly.The example is for the Console provider. Pokud zprostředkovatel podporuje obory protokolů, IncludeScopes označuje, zda jsou povoleny.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Vlastnost poskytovatele (například Console v příkladu) může také určovat LogLevel vlastnost.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevelv rámci zprostředkovatele Určuje úrovně, které se mají protokolovat pro daného poskytovatele.LogLevel under a provider specifies levels to log for that provider.

Pokud jsou úrovně specifikovány v Logging.{providername}.LogLevel , přepíše cokoli nastavené v Logging.LogLevel .If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. Zvažte například následující kód JSON:For example, consider the following 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.In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

Rozhraní API pro protokolování neobsahuje scénář pro změnu úrovní protokolu, když je aplikace spuštěná.The Logging API doesn't include a scenario to change log levels while an app is running. Někteří poskytovatelé konfigurace ale mohou znovu načíst konfiguraci, která se projeví okamžitě při konfiguraci protokolování.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. 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í.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. 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.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Informace o implementaci zprostředkovatelů konfigurace najdete v tématu Konfigurace v ASP.NET Core .For information on implementing configuration providers, see Konfigurace v ASP.NET Core.

Ukázka výstupu protokolováníSample logging output

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.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Tady je příklad výstupu konzoly:Here's an example of console output:

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 .The preceding logs were generated by making an HTTP Get request to the sample app at 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:Here's an example of the same logs as they appear in the Debug window when you run the sample app in 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".The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Protokoly, které začínají na kategorie Microsoft, jsou z ASP.NET Coreho kódu rozhraní.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core a kód aplikace používají stejné rozhraní API a poskytovatele protokolování.ASP.NET Core and application code are using the same logging API and providers.

Zbývající část tohoto článku vysvětluje několik podrobností a možností protokolování.The remainder of this article explains some details and options for logging.

Balíčky NuGetNuGet packages

ILoggerRozhraní a ILoggerFactory jsou v Microsoft. Extensions. Loggings. Abstractsa výchozí implementace pro ně jsou v Microsoft. Extensions. Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Kategorie protokoluLog category

Při ILogger vytvoření objektu je pro něj zadána kategorie .When an ILogger object is created, a category is specified for it. Tato kategorie je součástí každé zprávy protokolu vytvořené pomocí této instance ILogger .That category is included with each log message created by that instance of ILogger. Kategorie může být libovolný řetězec, ale konvence používá název třídy, jako je například "TodoApi. Controllers. TodoController".The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Použijte ILogger<T> k získání ILogger instance, která používá plně kvalifikovaný název typu T jako kategorii:Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

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 :To explicitly specify the category, call 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 .ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Úroveň protokolováníLog level

Každý protokol Určuje LogLevel hodnotu.Every log specifies a LogLevel value. Úroveň protokolu označuje závažnost nebo důležitost.The log level indicates the severity or importance. Můžete například zapsat Information protokol, pokud metoda končí normálně a Warning protokol, když metoda vrátí stavový kód 404 Nenalezeno .For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

Následující kód vytváří Information a Warning protokoluje:The following code creates Information and Warning logs:

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.In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. Druhý parametr je šablona zprávy se zástupnými symboly pro hodnoty argumentů poskytované zbývajícími parametry metody.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Parametry metody jsou vysvětleny v části Šablona zprávy protokolu v tomto článku.The method parameters are explained in the Log message template section in this article.

Metody protokolu, které zahrnují úroveň v názvu metody (například LogInformation a LogWarning ), jsou metody rozšíření pro ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Tyto metody volají Log metodu, která přebírá LogLevel parametr.These methods call a Log method that takes a LogLevel parameter. 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á.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Další informace naleznete v tématu ILogger a ve zdrojovém kódu rozšíření protokolovacíhonástroje.For more information, see ILogger and the logger extensions source code.

ASP.NET Core definuje následující úrovně protokolu seřazené od nejnižší k nejvyšší závažnosti.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trasování = 0Trace = 0

    Informace, které jsou obvykle užitečné pouze pro ladění.For information that's typically valuable only for debugging. Tyto zprávy mohou obsahovat citlivá data aplikací, a proto by neměly být povoleny v produkčním prostředí.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Ve výchozím nastavení zakázáno.Disabled by default.

  • Ladění = 1Debug = 1

    Informace, které mohou být užitečné při vývoji a ladění.For information that may be useful in development and debugging. 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ů.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Informace = 2Information = 2

    Pro sledování obecného toku aplikace.For tracking the general flow of the app. Tyto protokoly obvykle mají nějakou dlouhodobou hodnotu.These logs typically have some long-term value. Příklad: Request received for path /api/todoExample: Request received for path /api/todo

  • Upozornění = 3Warning = 3

    Pro neobvyklé nebo neočekávané události v toku aplikace.For abnormal or unexpected events in the app flow. Ty můžou zahrnovat chyby nebo jiné podmínky, které nezpůsobí zastavení aplikace, ale možná bude nutné je prozkoumat.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Zpracování výjimek je běžné místo pro použití Warning úrovně protokolu.Handled exceptions are a common place to use the Warning log level. Příklad: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Chyba = 4Error = 4

    Pro chyby a výjimky, které nelze zpracovat.For errors and exceptions that cannot be handled. 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.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Příklad zprávy protokolu:Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Kritické = 5Critical = 5

    Chyby, které vyžadují okamžitou pozornost.For failures that require immediate attention. Příklady: scénáře ztráty dat, nedostatek místa na disku.Examples: data loss scenarios, out of disk space.

Ú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í.Use the log level to control how much log output is written to a particular storage medium or display window. Příklad:For example:

  • V produkčním prostředí:In production:
    • Protokolování na úrovni Trace přes Information vytváří velké množství podrobných zpráv protokolu.Logging at the Trace through Information levels produces a high-volume of detailed log messages. 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.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • Přihlášení Warning přes Critical úrovně obvykle vytváří méně a menší zprávy protokolu.Logging at Warning through Critical levels typically produces fewer, smaller log messages. 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.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Během vývoje:During development:
    • Umožňuje protokolovat Warning Critical zprávy do konzoly.Log Warning through Critical messages to the console.
    • Trace Information Při odstraňování potíží přidejte zprávy.Add Trace through Information messages when troubleshooting.

Část filtrování protokolu dále v tomto článku vysvětluje, jak řídit, které úrovně protokolu zprostředkovateli zpracovává.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core zapisuje protokoly pro události rozhraní .NET Framework.ASP.NET Core writes logs for framework events. 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.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Tady je příklad protokolů konzoly vytvořených spuštěním ukázkové aplikace nakonfigurované pro zobrazení Debug protokolů:Here's an example of console logs produced by running the sample app configured to show Debug logs:

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 protokoluLog event ID

Každý protokol může určovat ID události.Each log can specify an event ID. Tato ukázková aplikace používá lokálně definovanou LoggingEvents třídu:The sample app does this by using a locally defined LoggingEvents class:

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í.An event ID associates a set of events. Například všechny protokoly související se zobrazením seznamu položek na stránce může být 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Zprostředkovatel protokolování může ukládat ID události v poli ID, ve zprávě protokolování nebo vůbec ne.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Zprostředkovatel ladění nezobrazuje ID událostí.The Debug provider doesn't show event IDs. Poskytovatel konzoly zobrazuje ID událostí v závorkách za kategorií:The console provider shows event IDs in brackets after the category:

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

Šablona zprávy protokoluLog message template

Každý protokol Určuje šablonu zprávy.Each log specifies a message template. Šablona zprávy může obsahovat zástupné symboly, pro které jsou k dispozici argumenty.The message template can contain placeholders for which arguments are provided. Použijte názvy zástupných symbolů, nikoli čísla.Use names for the placeholders, not numbers.

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.The order of placeholders, not their names, determines which parameters are used to provide their values. V následujícím kódu si všimněte, že názvy parametrů jsou v šabloně zprávy mimo pořadí:In the following code, notice that the parameter names are out of sequence in the message template:

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:This code creates a log message with the parameter values in sequence:

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í.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Samotné argumenty jsou předány do protokolovacího systému, nikoli pouze ze šablony formátované zprávy.The arguments themselves are passed to the logging system, not just the formatted message template. Tyto informace umožňují poskytovatelům protokolování ukládat hodnoty parametrů jako pole.This information enables logging providers to store the parameter values as fields. Předpokládejme například, že volání metody protokolovacího nástroje vypadá takto:For example, suppose logger method calls look like this:

_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.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. 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.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Protokolování výjimekLogging exceptions

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:The logger methods have overloads that let you pass in an exception, as in the following example:

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.Different providers handle the exception information in different ways. Tady je příklad výstupu poskytovatele ladění z kódu uvedeného výše.Here's an example of Debug provider output from the code shown above.

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ůLog filtering

Můžete zadat minimální úroveň protokolu pro konkrétního zprostředkovatele a kategorii nebo pro všechny poskytovatele nebo všechny kategorie.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Všechny protokoly nižší než minimální úroveň nebudou tomuto poskytovateli předány, takže se nebudou zobrazovat ani ukládat.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Chcete-li potlačit všechny protokoly, zadejte LogLevel.None jako minimální úroveň protokolu.To suppress all logs, specify LogLevel.None as the minimum log level. Celočíselná hodnota LogLevel.None je 6, což je více než LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Vytvořit pravidla filtru v konfiguraciCreate filter rules in configuration

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ší).The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. CreateDefaultBuilderMetoda nastaví protokolování tak, aby hledalo konfiguraci v Logging části, jak je vysvětleno výše v tomto článku.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Konfigurační data určují minimální úrovně protokolu podle poskytovatele a kategorie, jako v následujícím příkladu:The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "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.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Při vytvoření objektu se vybere jedno pravidlo pro každého poskytovatele ILogger .A single rule is chosen for each provider when an ILogger object is created.

Filtrovat pravidla v kóduFilter rules in code

Následující příklad ukazuje, jak registrovat pravidla filtru v kódu:The following example shows how to register filter rules in code:

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.The second AddFilter specifies the Debug provider by using its type name. První AddFilter se vztahuje na všechny poskytovatele, protože neurčuje typ poskytovatele.The first AddFilter applies to all providers because it doesn't specify a provider type.

Jak se používají pravidla filtrováníHow filtering rules are applied

Konfigurační data a AddFilter kód zobrazený v předchozích příkladech vytvoří pravidla uvedená v následující tabulce.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Prvních šest přicházejí z příkladu konfigurace a poslední dva pocházejí z příkladu kódu.The first six come from the configuration example and the last two come from the code example.

ČísloNumber PoskytovatelProvider Kategorie, které začínají na...Categories that begin with ... Minimální úroveň protokolováníMinimum log level
11 LaděníDebug Všechny kategorieAll categories InformaceInformation
22 KonzolaConsole Microsoft. AspNetCore. Mvc. Razor .. VnitřníchMicrosoft.AspNetCore.Mvc.Razor.Internal UpozorněníWarning
33 KonzolaConsole Microsoft. AspNetCore. Mvc. Razor ..RazorMicrosoft.AspNetCore.Mvc.Razor.Razor LaděníDebug
44 KonzolaConsole Microsoft. AspNetCore. Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ChybaError
55 KonzolaConsole Všechny kategorieAll categories InformaceInformation
66 Všichni poskytovateléAll providers Všechny kategorieAll categories LaděníDebug
77 Všichni poskytovateléAll providers SystémSystem LaděníDebug
88 LaděníDebug Partnerský vztah MicrosoftuMicrosoft TrasováníTrace

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.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Všechny zprávy napsané ILogger instancí jsou filtrovány podle vybraných pravidel.All messages written by an ILogger instance are filtered based on the selected rules. V dostupných pravidlech se vybere nejpřesnější pravidlo pro jednotlivé dvojice zprostředkovatel a kategorie.The most specific rule possible for each provider and category pair is selected from the available rules.

Následující algoritmus se používá pro každého poskytovatele při ILogger vytvoření pro danou kategorii:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Vyberte všechna pravidla, která se shodují se zprostředkovatelem nebo jeho aliasem.Select all rules that match the provider or its alias. Pokud se nenajde žádná shoda, vyberte všechna pravidla s prázdným zprostředkovatelem.If no match is found, select all rules with an empty provider.
  • Z výsledku předchozího kroku vyberte pravidla s nejdelší vyhovující předponou kategorie.From the result of the preceding step, select rules with longest matching category prefix. Pokud se nenajde žádná shoda, vyberte všechna pravidla, která neurčují kategorii.If no match is found, select all rules that don't specify a category.
  • Pokud je vybráno více pravidel, vezměte Poslední z nich.If multiple rules are selected, take the last one.
  • Pokud nejsou vybrána žádná pravidla, použijte MinimumLevel .If no rules are selected, use MinimumLevel.

V předchozím seznamu pravidel Předpokládejme, že vytvoříte ILogger objekt pro kategorii "Microsoft. AspNetCore. Mvc. Razor . Razor ViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Pro poskytovatele ladění platí pravidla 1, 6 a 8.For the Debug provider, rules 1, 6, and 8 apply. Pravidlo 8 je nejvíce specifické, takže je to ten vybraný.Rule 8 is most specific, so that's the one selected.
  • Pro poskytovatele konzoly platí pravidla 3, 4, 5 a 6.For the Console provider, rules 3, 4, 5, and 6 apply. Pravidlo 3 je nejvíce specifické.Rule 3 is most specific.

Výsledná ILogger instance odesílá protokoly Trace úrovně a výše do poskytovatele ladění.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Protokoly Debug úrovně a výše jsou odesílány poskytovateli konzoly.Logs of Debug level and above are sent to the Console provider.

Aliasy zprostředkovateleProvider aliases

Každý zprostředkovatel definuje alias , který lze použít v konfiguraci místo plně kvalifikovaného názvu typu.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Pro předdefinované poskytovatele použijte následující aliasy:For the built-in providers, use the following aliases:

  • KonzolaConsole
  • LaděníDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Výchozí minimální úroveňDefault minimum level

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.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. Následující příklad ukazuje, jak nastavit minimální úroveň:The following example shows how to set the minimum level:

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.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Funkce filtrováníFilter functions

Funkce filtru je vyvolána pro všechny poskytovatele a kategorie, které nemají pravidla přiřazena pomocí konfigurace nebo kódu.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Kód ve funkci má přístup k typu poskytovatele, kategorii a úrovni protokolu.Code in the function has access to the provider type, category, and log level. Příklad:For example:

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ěSystem categories and levels

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:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

KategorieCategory PoznámkyNotes
Microsoft. AspNetCoreMicrosoft.AspNetCore Obecná diagnostika ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft. AspNetCore. DataProtectionMicrosoft.AspNetCore.DataProtection Které klíče byly zváženy, nalezeny a použity.Which keys were considered, found, and used.
Microsoft. AspNetCore. HostFilteringMicrosoft.AspNetCore.HostFiltering Hostitelé povoleni.Hosts allowed.
Microsoft. AspNetCore. hostingMicrosoft.AspNetCore.Hosting Doba, po kterou trvalo dokončení požadavků HTTP a čas jejich spuštění.How long HTTP requests took to complete and what time they started. Která hostující spouštěcí sestavení byla načtena.Which hosting startup assemblies were loaded.
Microsoft. AspNetCore. MvcMicrosoft.AspNetCore.Mvc MVC a Razor Diagnostika.MVC and Razor diagnostics. Vazba modelů, spuštění filtru, zobrazení kompilace, výběr akce.Model binding, filter execution, view compilation, action selection.
Microsoft. AspNetCore. RoutingMicrosoft.AspNetCore.Routing Informace o shodě trasy.Route matching information.
Microsoft. AspNetCore. ServerMicrosoft.AspNetCore.Server Připojení – spouštění, zastavování a udržování reakcí na Alive.Connection start, stop, and keep alive responses. Informace o certifikátu HTTPSHTTPS certificate information.
Microsoft. AspNetCore. StaticFilesMicrosoft.AspNetCore.StaticFiles Soubory byly obsluhovány.Files served.
Microsoft. EntityFrameworkCoreMicrosoft.EntityFrameworkCore Obecná diagnostika Entity Framework Core.General Entity Framework Core diagnostics. Databázová aktivita a konfigurace, detekce změn, migrace.Database activity and configuration, change detection, migrations.

Rozsahy protokolůLog scopes

Obor může seskupit sadu logických operací.A scope can group a set of logical operations. Toto seskupení lze použít pro připojení stejných dat ke každému protokolu, který je vytvořen jako součást sady.This grouping can be used to attach the same data to each log that's created as part of a set. Každý protokol vytvořený jako součást zpracování transakce může například zahrnovat ID transakce.For example, every log created as part of processing a transaction can include the transaction ID.

Obor je IDisposable typ, který je vrácen BeginScope metodou a trvá, dokud nebude uvolněn.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Použití oboru zabalením volání protokolovacího nástroje v using bloku:Use a scope by wrapping logger calls in a using block:

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:The following code enables scopes for the console provider:

Program.cs: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.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Informace o konfiguraci najdete v části věnované konfiguraci .For information on configuration, see the Configuration section.

Každá zpráva protokolu obsahuje informace s vymezeným oborem:Each log message includes the scoped information:

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íBuilt-in logging providers

ASP.NET Core dodává následující poskytovatele:ASP.NET Core ships the following providers:

Informace o stdout a protokolování ladění pomocí modulu ASP.NET Core naleznete v tématu Řešení potíží s ASP.NET Core v Azure App Service a IIS a Modul ASP.NET Core .For information on stdout and debug logging with the ASP.NET Core Module, see Řešení potíží s ASP.NET Core v Azure App Service a IIS and Modul ASP.NET Core.

Poskytovatel konzolyConsole provider

Balíček poskytovatele Microsoft. Extensions. Logging. Console odesílá výstup protokolu do konzoly.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

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:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Poskytovatel laděníDebug provider

Balíček poskytovatele Microsoft. Extensions. Logging. Debug zapisuje výstup protokolu pomocí třídy System. Diagnostics. Debug ( Debug.WriteLine volání metody).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

V systému Linux tento poskytovatel zapisuje protokoly do /var/log/Message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

Zprostředkovatel zdroje událostíEvent Source provider

Balíček zprostředkovatele Microsoft. Extensions. Logging. EventSource zapisuje do zdroje událostí pro různé platformy s názvem Microsoft-Extensions-Logging .The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. Ve Windows zprostředkovatel používá ETW.On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

Poskytovatel zdroje událostí se přidá automaticky, když CreateDefaultBuilder se volá k sestavení hostitele.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

K shromažďování a zobrazování protokolů použijte Nástroj PerfView .Use the PerfView utility to collect and view logs. 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.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by 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é .To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (Na začátku řetězce nechybíš hvězdičku.)(Don't miss the asterisk at the start of the string.)

PerfView další poskytovatelé

Zprostředkovatel událostí systému WindowsWindows EventLog provider

Balíček poskytovatele Microsoft. Extensions. log. EventLog odesílá výstup protokolu do protokolu událostí systému Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

AddEventLog přetížení umožňují předat EventLogSettings .AddEventLog overloads let you pass in EventLogSettings. Pokud null není zadaný, použijí se následující výchozí nastavení:If null or not specified, the following default settings are used:

  • LogName: "Application"LogName: "Application"
  • SourceName: ".NET runtime"SourceName: ".NET Runtime"
  • MachineName: Používá se název místního počítače.MachineName: The local machine name is used.

Události jsou protokolovány pro úroveň upozornění a vyšší.Events are logged for Warning level and higher. Následující příklad nastaví výchozí úroveň protokolu událostí na LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

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

Poskytovatel TraceSourceTraceSource provider

Balíček poskytovatele Microsoft. Extensions. Logging. TraceSource používá TraceSource knihovny a poskytovatele.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

Přetížení AddTraceSource umožňují předat zdrojový přepínač a naslouchací proces trasování.AddTraceSource overloads let you pass in a source switch and a trace listener.

Aby bylo možné používat tohoto poskytovatele, aplikace musí běžet na .NET Framework (spíše než .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Poskytovatel může směrovat zprávy na celou řadu posluchačů, jako je například TextWriterTraceListener použití v ukázkové aplikaci.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Poskytovatel Azure App ServiceAzure App Service provider

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.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

Balíček poskytovatele není zahrnutý ve službě Microsoft. AspNetCore. app Metapackage.The provider package isn't included in the 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.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

AddAzureWebAppDiagnosticsPřetížení umožňuje předat AzureAppServicesDiagnosticsSettings .An AddAzureWebAppDiagnostics overload lets you pass in 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.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (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.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Když nasadíte aplikaci do App Service, aplikace respektuje nastavení v části protokoly App Service stránky App Service Azure Portal.When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the 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.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Protokolování aplikace (systém souborů)Application Logging (Filesystem)
  • Protokolování aplikace (BLOB)Application Logging (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.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Výchozí omezení velikosti souboru je 10 MB a výchozí maximální počet uchovávaných souborů je 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Výchozí název objektu BLOB je {App-Name} {timestamp}/yyyy/mm/dd/hh/{guid} -applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Zprostředkovatel funguje pouze v případě, že projekt běží v prostředí Azure.The provider only works when the project runs in the Azure environment. 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.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Streamování protokolů AzureAzure log streaming

Streamování protokolů Azure umožňuje zobrazit aktivitu protokolu v reálném čase z:Azure log streaming lets you view log activity in real time from:

  • Aplikační serverThe app server
  • Webový serverThe web server
  • Trasování chybných požadavkůFailed request tracing

Konfigurace streamování protokolů Azure:To configure Azure log streaming:

  • Na stránce portálu vaší aplikace přejděte na stránku protokoly App Service .Navigate to the App Service logs page from your app's portal page.
  • Nastavte protokolování aplikace (systém souborů) na zapnuto.Set Application Logging (Filesystem) to On.
  • Vyberte úroveňprotokolu.Choose the log Level. Toto nastavení platí jenom pro streamování protokolů Azure, ne pro jiné poskytovatele protokolování v aplikaci.This setting only applies to Azure log streaming, not other logging providers in the app.

Pokud chcete zobrazit zprávy aplikace, přejděte na stránku streamu protokolu .Navigate to the Log Stream page to view app messages. Protokolují ho aplikace přes ILogger rozhraní.They're logged by the app through the ILogger interface.

Protokolování trasování Azure Application InsightsAzure Application Insights trace logging

Balíček poskytovatele Microsoft. Extensions. Logging. ApplicationInsights zapisuje protokoly do Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights je služba, která monitoruje webovou aplikaci a poskytuje nástroje pro dotazování a analýzu dat telemetrie.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Pokud použijete tohoto poskytovatele, můžete zadávat dotazy a analyzovat protokoly pomocí Application Insightsch nástrojů.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

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.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Pokud použijete tento balíček, nemusíte instalovat balíček poskytovatele.If you use this package, you don't have to install the provider package.

Nepoužívejte balíček Microsoft. ApplicationInsights. Web — , který je pro ASP.NET 4. x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Další informace naleznete v následujících zdrojích:For more information, see the following resources:

Zprostředkovatelé protokolování třetích stranThird-party logging providers

Protokolovací architektury třetích stran, které pracují s ASP.NET Core:Third-party logging frameworks that work with 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í.Some third-party frameworks can perform semantic logging, also known as structured logging.

Použití architektury třetí strany se podobá použití jednoho z vestavěných zprostředkovatelů:Using a third-party framework is similar to using one of the built-in providers:

  1. Přidejte do projektu balíček NuGet.Add a NuGet package to your project.
  2. Zavolejte ILoggerFactory metodu rozšíření poskytovanou protokolovacím rozhraním.Call an ILoggerFactory extension method provided by the logging framework.

Další informace najdete v dokumentaci pro každého poskytovatele.For more information, see each provider's documentation. Microsoft nepodporuje zprostředkovatele protokolování třetích stran.Third-party logging providers aren't supported by Microsoft.

Další materiályAdditional resources