Zprostředkovatelé protokolování v .NET

  • Článek

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

Výchozí šablony aplikace .NET Worker:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Předchozí kód zobrazuje třídu vytvořenou Program pomocí šablon aplikací .NET Worker. V následujících několika částech najdete ukázky založené na šablonách aplikace .NET Worker, které používají obecného hostitele.

Chcete-li přepsat výchozí sadu zprostředkovatelů protokolování přidaných pomocí Host.CreateApplicationBuildervolání ClearProviders a přidání požadovaných zprostředkovatelů protokolování. Například následující kód:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

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

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

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

Předchozí kód je Func<IServiceProvider, IExampleService>, který spouští poprvé, když kontejner DI potřebuje sestavit instanci IExampleService. Tímto způsobem můžete přistupovat ke všem registrovaným službám.

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

Rozšíření Microsoftu zahrnují následující zprostředkovatele protokolování jako součást knihoven modulu runtime:

Microsoft dodává následující zprostředkovatele protokolování, ale ne jako součást knihoven modulu runtime. Musí být nainstalované jako další balíčky NuGet.

Konzola

Zprostředkovatel Console protokoluje výstup do konzoly.

Ladění

Debug Zprostředkovatel zapisuje výstup protokolu pomocí System.Diagnostics.Debug třídy, konkrétně prostřednictvím Debug.WriteLine metody a pouze při připojení ladicího programu. DebugLogger Vytvoří DebugLoggerProvider instance, které jsou implementace ILogger rozhraní.

Zdroj události

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

Nástroj dotnet-trace

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

Pokyny k instalaci najdete tady: dotnet-trace. Diagnostický kurz s využitím dotnet-tracenajdete v tématu Ladění vysokého využití procesoru v .NET Core.

Windows EventLog

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

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

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

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

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

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Azure App Service

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

Balíček zprostředkovatele není součástí knihoven modulu runtime. Pokud chcete tohoto zprostředkovatele použít, přidejte do projektu balíček zprostředkovatele.

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

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

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

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

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

Výchozí umístění souborů protokolu je ve složce D:\home\LogFiles\Application . Další výchozí hodnoty se liší podle poskytovatele:

  • Protokolování aplikace (Filesystem):: Výchozí název souboru systému souborů je diagnostics-yyyymmdd.txt. Výchozí limit velikosti souboru je 10 MB a výchozí maximální počet uchovávaných souborů je 2.
  • Protokolování aplikace (objekt blob):Výchozí název objektu blob je {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt.

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

Streamování protokolů Azure

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

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

Konfigurace streamování protokolů Azure:

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

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

Azure Application Insights

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

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

Aspekty návrhu zprostředkovatele protokolování

Pokud plánujete vytvořit vlastní implementaci ILoggerProvider rozhraní a odpovídající vlastní implementaci ILogger, zvažte následující body:

  • Metoda ILogger.Log je synchronní.
  • Životnost stavu protokolu a objektů by se neměla předpokládat.

Implementace ILoggerProvider vytvoří prostřednictvím ILogger své ILoggerProvider.CreateLogger metody. Pokud se vaše implementace snaží zařazovat zprávy protokolování do fronty neblokující způsobem, zprávy by měly být nejprve materializovány nebo stav objektu, který se používá k materializaci položky protokolu, by se měl serializovat. Tím se vyhnete potenciálním výjimkám z odstraněných objektů.

Další informace naleznete v tématu Implementace vlastního zprostředkovatele protokolování v .NET.

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

Tady jsou některé architektury protokolování třetích stran, které pracují s různými úlohami .NET:

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

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

  1. Přidejte do svého projektu příslušný balíček NuGet.
  2. ILoggerFactory Volání metody rozšíření ILoggingBuilder poskytované rozhraním protokolování

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

Viz také