Rejestrowanie na platformie .NET Core i ASP.NET Core

A którzy to zroślili się w 2017 r., a ich rick anderson to Jue pojedyńczasowaricka Gutscha

W tym temacie opisano rejestrowanie w programie .NET, tak jak ma to ASP.NET Core aplikacji. Aby uzyskać szczegółowe informacje na temat rejestrowania na platformie .NET, zobacz Rejestrowanie na platformie .NET. Aby uzyskać więcej informacji na temat rejestrowania w aplikacjachBlazor, zobacz ASP.NET Core Blazor rejestrowanie.

Dostawcy rejestrowania

Dostawcy rejestrowania przechowują dzienniki z wyjątkiem dostawcy Console , który wyświetla dzienniki. Na przykład dostawca aplikacja systemu Azure Szczegółowe informacje przechowuje dzienniki w aplikacja systemu Azure Szczegółowe informacje. Można włączyć wielu dostawców.

Domyślne szablony ASP.NET Core aplikacji internetowej:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Powyższy kod przedstawia plik utworzony za Program.cs pomocą ASP.NET Core aplikacji internetowej. Kilka następnych sekcji zawiera przykłady oparte na ASP.NET Core aplikacji internetowej, które korzystają z hosta ogólnego.

Poniższy kod zastępuje domyślny zestaw dostawców rejestrowania dodanych przez program WebApplication.CreateBuilder:

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

builder.Services.AddRazorPages();

var app = builder.Build();

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

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Alternatywnie powyższy kod rejestrowania można zapisywać w następujący sposób:

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

Aby uzyskać informacje o dodatkowych dostawcach, zobacz:

Tworzenie dzienników

Aby utworzyć dzienniki, użyj obiektu ILogger<TCategoryName> z wstrzykiwania zależności.

Poniższy przykład:

  • Tworzy rejestrator, ILogger<AboutModel>, który używa kategorii dziennika w pełni kwalifikowanej nazwy typu AboutModel. Kategoria dziennika to ciąg skojarzony z każdym dziennikami.
  • Wywołania LogInformation do dziennika na Information poziomie. Poziom dziennika wskazuje ważność zarejestrowanego zdarzenia.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

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

Poziomy i kategorie zostały szczegółowo opisane w dalszej części tego dokumentu.

Aby uzyskać informacje na Blazortemat ASP.NET Core Blazor rejestrowania.

Konfigurowanie rejestrowania

Konfiguracja rejestrowania jest często dostarczana przez Logging sekcję plików appsettings.{ENVIRONMENT}.json , gdzie symbol zastępczy {ENVIRONMENT} jest środowiskiem. Następujący plik appsettings.Development.json jest generowany przez ASP.NET Core aplikacji internetowej:

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

W powyższym kodzie JSON:

  • Określono "Default" kategorie "Microsoft.AspNetCore" i .
  • Kategoria "Microsoft.AspNetCore" ma zastosowanie do wszystkich kategorii, które zaczynają się od "Microsoft.AspNetCore". Na przykład to ustawienie ma zastosowanie do "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorii .
  • Kategoria "Microsoft.AspNetCore" rejestruje dane na poziomie dziennika Warning i na wyższym poziomie.
  • Określony dostawca dziennika nie jest określony, więc LogLevel ma zastosowanie do wszystkich włączonych dostawców rejestrowania z wyjątkiem Windows Dziennika zdarzeń.

Właściwość Logging może mieć właściwości LogLevel dostawcy dzienników i . Określa LogLevel minimalny poziom do logowania dla wybranych kategorii. W powyższym pliku JSON określono InformationWarning poziomy dziennika. LogLevel Wskazuje ważność dziennika i zakresy od 0 do 6:

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

Jeśli określono LogLevel wartość , rejestrowanie jest włączone dla komunikatów na określonym poziomie lub wyższym. W poprzednim json kategoria Default jest rejestrowana Information dla kategorii i wyższa. Rejestrowane są Informationna przykład Warningkomunikaty Error, , Critical i . Jeśli nie LogLevel zostanie określony, rejestrowanie zostanie domyślnie określone na Information poziomie . Aby uzyskać więcej informacji, zobacz Poziomy dziennika.

Właściwość dostawcy może określać LogLevel właściwość. LogLevel w obszarze dostawcy określa poziomy logowania dla tego dostawcy i zastępuje ustawienia dziennika bez dostawcy. Rozważmy następujący appsettings.json plik:

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

Ustawienia w ustawieniach Logging.{PROVIDER NAME}.LogLevel przesłonięcia w Logging.LogLevelpliku , gdzie symbol zastępczy {PROVIDER NAME} jest nazwą dostawcy. W powyższym pliku JSON Debug domyślny poziom dziennika dostawcy jest ustawiony na wartość Information:

Logging:Debug:LogLevel:Default:Information

Poprzednie ustawienie określa poziom dziennika Information dla każdej kategorii Logging:Debug: z wyjątkiem Microsoft.Hosting. Gdy określonej kategorii jest wymieniony, określonej kategorii zastępuje kategorii domyślnej. W powyższym JSON kategorie Logging:Debug:LogLevel i przesłaniają "Microsoft.Hosting""Default" ustawienia w .Logging:LogLevel

Minimalny poziom dziennika można określić dla dowolnego z:

  • Konkcyjni dostawcy: na przykład Logging:EventSource:LogLevel:Default:Information
  • Określone kategorie: na przykład Logging:LogLevel:Microsoft:Warning
  • Wszyscy dostawcy i wszystkie kategorie: Logging:LogLevel:Default:Warning

Wszystkie dzienniki poniżej poziomu minimalnego nie są:

  • Przekazana do dostawcy.
  • Zarejestrowane lub wyświetlane.

Aby pominąć wszystkie dzienniki, określ wartość LogLevel.None. LogLevel.None ma wartość 6, która jest większa niż LogLevel.Critical (5).

Jeśli dostawca obsługuje zakresy dzienników, IncludeScopes wskazuje, czy są one włączone. Aby uzyskać więcej informacji, zobacz zakresy dzienników.

Poniższy plik appsettings.json zawiera wszystkich dostawców domyślnie włączonych:

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

W poprzednim przykładzie:

  • Kategorie i poziomy nie są sugerowanymi wartościami. W przykładzie podano, aby wyświetlić wszystkich domyślnych dostawców.
  • Ustawienia w ustawieniach Logging.{PROVIDER NAME}.LogLevel przesłonięcia w Logging.LogLevelpliku , gdzie symbol zastępczy {PROVIDER NAME} jest nazwą dostawcy. Na przykład poziom w wartości Debug.LogLevel.Default zastępuje poziom w .LogLevel.Default
  • Używany jest każdy domyślny alias dostawcy. Każdy dostawca definiuje alias , który może być używany w konfiguracji, a nie w pełni kwalifikowaną nazwę typu. Wbudowane aliasy dostawców to:
    • Console
    • Debug
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Ustawianie poziomu dziennika według wiersza polecenia, zmiennych środowiskowych i innej konfiguracji

Poziom dziennika może być ustawiony przez dowolnego z dostawców konfiguracji.

Separator : nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. __, podwójny podkreślenie, to:

  • Obsługiwane przez wszystkie platformy. Na przykład separator nie : jest obsługiwany przez powłokę Bash, ale __ jest.
  • Automatycznie zastępowane przez :

Następujące polecenia:

  • Ustaw klucz środowiska na Logging:LogLevel:Microsoft wartość na Information Windows.
  • Przetestuj ustawienia w przypadku korzystania z aplikacji utworzonej za pomocą ASP.NET Core aplikacji internetowej. Polecenie dotnet run należy uruchomić w katalogu projektu po użyciu polecenia set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Poprzednie ustawienie środowiska:

  • Jest ustawiany tylko w procesach uruchomionych z okna poleceń, w których zostały ustawione.
  • Nie jest odczytywane przez przeglądarki uruchomione z Visual Studio.

Następujące polecenie setx ustawia również klucz środowiska i wartość na Windows. W przeciwieństwie setdo , setx ustawienia są utrwalane. Przełącznik /M ustawia zmienną w środowisku systemowym. Jeśli /M nie jest używana, ustawiana jest zmienna środowiskowa użytkownika.

setx Logging__LogLevel__Microsoft Information /M

Rozważmy następujący appsettings.json plik:

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

Następujące polecenie ustawia poprzednią konfigurację w środowisku:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Na Azure App Service wybierz pozycję Nowe ustawienie aplikacji na stronie Ustawienia > Konfiguracji aplikacji. Azure App Service aplikacji są:

  • Szyfrowane w spoczynku i przesyłane za pośrednictwem szyfrowanego kanału.
  • Widoczne jako zmienne środowiskowe.

Aby uzyskać więcej informacji, zobacz Azure Apps: Override app configuration using the Azure Portal (Azure Apps: przesłanianie konfiguracji aplikacji przy użyciu witryny Azure Portal).

Aby uzyskać więcej informacji na temat ustawiania ASP.NET Core konfiguracji przy użyciu zmiennych środowiskowych, zobacz zmienne środowiskowe. Aby uzyskać informacje na temat używania innych źródeł konfiguracji, w tym wiersza polecenia, usługi Azure Key Vault, Azure App Configuration, innych formatów plików i innych, zobacz Configuration in ASP.NET Core (Konfiguracja w usłudze ASP.NET Core).

Jak są stosowane reguły filtrowania

Po utworzeniu ILogger<TCategoryName> obiektu obiekt ILoggerFactory wybiera pojedynczą regułę dla każdego dostawcy do zastosowania do tego rejestratora. Wszystkie komunikaty zapisywane przez wystąpienie ILogger są filtrowane na podstawie wybranych reguł. Najbardziej specyficzna reguła dla każdej pary dostawców i kategorii jest wybierana z dostępnych reguł.

Następujący algorytm jest używany dla każdego dostawcy, gdy element jest ILogger tworzony dla danej kategorii:

  • Wybierz wszystkie reguły, które pasują do dostawcy lub jego aliasu. Jeśli dopasowanie nie zostanie znalezione, zaznacz wszystkie reguły z pustym dostawcą.
  • Z wyniku poprzedniego kroku wybierz reguły z najdłuższym pasującymi prefiksami kategorii. Jeśli dopasowanie nie zostanie znalezione, wybierz wszystkie reguły, które nie określają kategorii.
  • Jeśli wybrano wiele reguł, weź ostatnią z nich.
  • Jeśli nie wybrano żadnych reguł, użyj .MinimumLevel

Rejestrowanie danych wyjściowych z dotnet run i Visual Studio

Zostaną wyświetlone dzienniki utworzone przy użyciu domyślnych dostawców rejestrowania:

  • W programie Visual Studio
    • W oknie Dane wyjściowe debugowania podczas debugowania.
    • W oknie ASP.NET Core sieci Web.
  • W oknie konsoli, gdy aplikacja jest uruchamiana za pomocą polecenia dotnet run.

Dzienniki, które zaczynają się od kategorii "Microsoft", ASP.NET Core kodu struktury. ASP.NET Core i kod aplikacji używają tego samego interfejsu API rejestrowania i dostawców.

Kategoria dziennika

Podczas tworzenia ILogger obiektu jest określana kategoria. Ta kategoria jest uwzględniana w każdym komunikacie dziennika utworzonym przez to wystąpienie klasy ILogger. Ciąg kategorii jest dowolny, ale konwencją jest użycie nazwy klasy. Na przykład w kontrolerze nazwa może być ."TodoApi.Controllers.TodoController" Aplikacja ASP.NET Core automatycznie ILogger<T>ILogger pobiera wystąpienie, które używa w pełni kwalifikowanej nazwy T typu jako kategorii:

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

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

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

Aby jawnie określić kategorię, wywołaj wywołanie :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.");
    }

Wywoływanie CreateLogger z stałą nazwą może być przydatne w przypadku korzystania z wielu metod, aby zdarzenia można było uporządkować według kategorii.

ILogger<T> jest odpowiednikiem wywołania CreateLogger z w pełni kwalifikowaną nazwą typu T.

Poziom dziennika

W poniższej tabeli wymieniono LogLevel wartości, wygodną Log{LogLevel} metodę rozszerzenia i sugerowane użycie:

LogLevel Wartość Metoda Opis
Trace 0 LogTrace Zawierają najbardziej szczegółowe komunikaty. Te komunikaty mogą zawierać poufne dane aplikacji. Te komunikaty są domyślnie wyłączone i nie powinny być włączone w środowisku produkcyjnym.
Debug 1 LogDebug Debugowanie i opracowywanie. Należy zachować ostrożność w środowisku produkcyjnym ze względu na dużą ilość danych.
Information 2 LogInformation Śledzi ogólny przepływ aplikacji. Może mieć wartość długoterminową.
Warning 3 LogWarning W przypadku nietypowych lub nieoczekiwanych zdarzeń. Zwykle zawiera błędy lub warunki, które nie powodują awarii aplikacji.
Error 4 LogError Błędy i wyjątki, które nie mogą być obsługiwane. Te komunikaty wskazują błąd w bieżącej operacji lub żądaniu, a nie błąd dla całej aplikacji.
Critical 5 LogCritical W przypadku awarii wymagających natychmiastowej uwagi. Przykłady: scenariusze utraty danych, za dużo miejsca na dysku.
None 6 Określa, że kategoria rejestrowania nie powinna zapisywać komunikatów.

W poprzedniej tabeli wartość jest wymieniona LogLevel od najniższej do najwyższej ważności.

Pierwszy Log parametr metody, LogLevel, wskazuje ważność dziennika. Zamiast wywoływania Log(LogLevel, ...)metody , większość deweloperów wywołują Log{LOG LEVEL} metody rozszerzenia, gdzie symbolem {LOG LEVEL} zastępczym jest poziom dziennika. Na przykład następujące dwa wywołania rejestrowania są funkcjonalnie równoważne i dają ten sam dziennik:

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

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

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem to identyfikator zdarzenia. MyLogEvents element jest częścią przykładowej aplikacji i jest wyświetlany w sekcji Identyfikator zdarzenia dziennika.

MyDisplayRouteInfo i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs.Samples.RouteInfo. Metody wyświetlają i Controller rozsyłają Razor Page informacje.

Poniższy kod tworzy i Information rejestruje Warning :

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

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

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

    return ItemToDTO(todoItem);
}

W poprzednim kodzie pierwszym parametrem Log{LOG LEVEL} jestMyLogEvents.GetItemidentyfikator zdarzenia dziennika. Drugi parametr to szablon komunikatu z symbolami zastępczymi wartości argumentu dostarczonych przez pozostałe parametry metody. Parametry metody zostały wyjaśnione w sekcji szablonu komunikatu w dalszej części tego dokumentu.

Wywołaj odpowiednią metodę Log{LOG LEVEL} , aby kontrolować ilość danych wyjściowych dziennika zapisywanych na określonym nośniku magazynu. Na przykład:

  • W środowisku produkcyjnym:
    • Rejestrowanie na poziomach Trace lub Information generuje dużą ilość szczegółowych komunikatów dziennika. Aby kontrolować koszty i nie przekraczać limitów magazynu danych, TraceInformation rejestruj i wysyłaj komunikaty na poziomie do magazynu danych o dużej ilości danych. Rozważ ograniczenie wartości Trace i Information do określonych kategorii.
    • Rejestrowanie na różnych Warning poziomach Critical powinno tworzyć kilka komunikatów dziennika.
      • Koszty i limity magazynu zwykle nie są problemem.
      • Niewiele dzienników zapewnia większą elastyczność wyboru magazynu danych.
  • W programie:
    • Ustaw wartość Warning.
    • Dodawanie Trace komunikatów lub Information podczas rozwiązywania problemów. Aby ograniczyć dane wyjściowe, ustaw TraceInformation lub tylko dla kategorii, które są pod badaniem.

ASP.NET Core zapisuje dzienniki dla zdarzeń struktury. Rozważmy na przykład dane wyjściowe dziennika dla:

  • Aplikacja Razor Pages utworzona za pomocą ASP.NET Core szablonów.
  • Rejestrowanie ustawione na wartość Logging:Console:LogLevel:Microsoft:Information.
  • Nawigacja do Privacy strony:
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

Następujące zestawy JSON Logging:Console:LogLevel:Microsoft:Information:

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

Identyfikator zdarzenia dziennika

Każdy dziennik może określać identyfikator zdarzenia. Przykładowa aplikacja używa klasy MyLogEvents do definiowania identyfikatorów zdarzeń:

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

Identyfikator zdarzenia kojarzy zestaw zdarzeń. Na przykład wszystkie dzienniki związane z wyświetlaniem listy elementów na stronie mogą mieć numer 1001.

Dostawca rejestrowania może przechowywać identyfikator zdarzenia w polu identyfikatora, w komunikacie rejestrowania lub w ogóle go nie przechowywać. Dostawca debugowania nie wyświetla identyfikatorów zdarzeń. Dostawca konsoli wyświetla identyfikatory zdarzeń w nawiasach po kategorii:

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

Niektórzy dostawcy rejestrowania przechowują identyfikator zdarzenia w polu, co umożliwia filtrowanie identyfikatora.

Szablon wiadomości dziennika

Każdy interfejs API dziennika używa szablonu wiadomości. Szablon wiadomości może zawierać symbole zastępcze, dla których podano argumenty. Użyj nazw symboli zastępczych, a nie liczb.

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

Kolejność parametrów, a nie ich nazw symboli zastępczych, określa, które parametry są używane do zapewnienia wartości symboli zastępczych w komunikatach dziennika. W poniższym kodzie nazwy parametrów są poza sekwencją w symbolach zastępczych szablonu komunikatu:

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

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

Jednak parametry są przypisywane do symboli zastępczych w kolejności: apples, pears, bananas. Komunikat dziennika odzwierciedla kolejność parametrów:

Parameters: 1, 2, 3

Takie podejście umożliwia dostawcom rejestrowania implementowanie rejestrowania semantycznego lub ustrukturyzowanego. Same argumenty są przekazywane do systemu rejestrowania, a nie tylko do sformatowanych szablonów komunikatów. Dzięki temu dostawcy rejestrowania mogą przechowywać wartości parametrów jako pola. Rozważmy na przykład następującą metodę rejestratora:

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

Na przykład podczas logowania do usługi Azure Table Storage:

  • Każda jednostka tabeli platformy Azure może mieć właściwości IDRequestTime i .
  • Tabele z właściwościami upraszczają zapytania dotyczące zarejestrowanych danych. Na przykład zapytanie może znaleźć wszystkie dzienniki w określonym zakresie RequestTime bez konieczności analizowania czasu poza wiadomością TEKSTOWĄ.

Rejestrowanie wyjątków

Metody rejestratora mają przeciążenia, które mają parametr wyjątku:

[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 i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs.Samples.RouteInfo. Metody wyświetlają i Controller rozsyłają Razor Page informacje.

Rejestrowanie wyjątków jest specyficzne dla dostawcy.

Domyślny poziom dziennika

Jeśli domyślny poziom dziennika nie jest ustawiony, domyślna wartość poziomu dziennika to Information.

Rozważmy na przykład następującą aplikację internetową:

  • Utworzone przy użyciu ASP.NET aplikacji internetowej.
  • appsettings.json i appsettings.Development.json usunięto lub zmieniono ich nazwę.

W przypadku poprzedniej konfiguracji przejście Tracedo prywatności lub strony głównej powoduje uzyskanie wielu komunikatów , Debugi InformationMicrosoft z nazwą kategorii.

Poniższy kod ustawia domyślny poziom dziennika, gdy domyślny poziom dziennika nie jest ustawiony w konfiguracji:

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

Ogólnie rzecz biorąc, poziomy dziennika powinny być określone w konfiguracji, a nie w kodzie.

Funkcja Filter

Funkcja filtru jest wywoływana dla wszystkich dostawców i kategorii, które nie mają przypisanych reguł przez konfigurację lub kod:

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

Powyższy kod wyświetla dzienniki konsoli, gdy kategoria zawiera wartość Controller lub , Microsoft a poziom dziennika jest Information lub wyższy.

Ogólnie rzecz biorąc, poziomy dziennika powinny być określone w konfiguracji, a nie w kodzie.

ASP.NET Core i EF Core kategorii

W poniższej tabeli przedstawiono niektóre kategorie używane przez ASP.NET Core i Entity Framework Core oraz uwagi dotyczące dzienników:

Kategoria Uwagi
Microsoft.AspNetCore Ogólne ASP.NET Core diagnostyki.
Microsoft.AspNetCore.DataProtection Które klucze zostały rozważone, znalezione i użyte.
Microsoft.AspNetCore.HostFiltering Hosty dozwolone.
Microsoft.AspNetCore.Hosting Czas ukończenia żądań HTTP i czas ich rozpoczęcia. Które zestawy startowe hostowania zostały załadowane.
Microsoft.AspNetCore.Mvc MVC i diagnostyka Razor . Powiązanie modelu, wykonywanie filtru, kompilacja widoku, wybór akcji.
Microsoft.AspNetCore.Routing Informacje o dopasowywaniu tras.
Microsoft.AspNetCore.Server Połączenia są rozpoczynane, zatrzymywane i utrzymywać aktywne odpowiedzi. Informacje o certyfikacie HTTPS.
Microsoft.AspNetCore.StaticFiles Obsługiwane pliki.
Microsoft.EntityFrameworkCore Ogólne Entity Framework Core diagnostyki. Aktywność i konfiguracja bazy danych, wykrywanie zmian, migracje.

Aby wyświetlić więcej kategorii w oknie konsoli, ustaw appsettings.Development.json na następujące ustawienia:

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

Zakresy dzienników

Zakres może grupowanie zestawu operacji logicznych. To grupowanie może służyć do dołączania tych samych danych do każdego dziennika, który jest tworzony jako część zestawu. Na przykład każdy dziennik utworzony w ramach przetwarzania transakcji może zawierać identyfikator transakcji.

Zakres:

Następujący dostawcy obsługują zakresy:

Użyj zakresu, opakowując wywołania rejestratora w using bloku:

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

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

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

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

    return ItemToDTO(todoItem);
}

Wbudowane dostawcy rejestrowania

ASP.NET Core obejmuje następujących dostawców rejestrowania w ramach udostępnionej struktury:

Następujący dostawcy rejestrowania są dostarczani przez firmę Microsoft, ale nie w ramach udostępnionej struktury. Muszą być one zainstalowane jako dodatkowe nuget.

ASP.NET Core nie zawiera dostawcy rejestrowania do zapisywania dzienników w plikach. Aby zapisywać dzienniki w plikach z ASP.NET Core aplikacji, rozważ użycie zewnętrznego dostawcy rejestrowania.

stdout Aby uzyskać informacje na temat rejestrowania i debugowania za pomocą modułu ASP.NET Core, zobacz Troubleshoot ASP.NET Core on Azure App Service and IIS and ASP.NET Core Module (ANCM) for IIS (Rozwiązywanie problemów z usługami Azure App Service i usługami IISoraz modułem ASP.NET Core Module (ANCM) dla usług IIS.

Konsola

Dostawca Console rejestruje dane wyjściowe w konsoli. Aby uzyskać więcej informacji na temat wyświetlania Console dzienników w programie, zobacz Rejestrowanie danych wyjściowych z uruchamiania dotnet i Visual Studio.

Debugowanie

Dostawca Debug zapisuje dane wyjściowe dziennika przy użyciu System.Diagnostics.Debug klasy . Wywołania do System.Diagnostics.Debug.WriteLine zapisu do Debug dostawcy.

W systemie Linux lokalizacja Debug dziennika dostawcy jest zależna od dystrybucji i może być jedną z następujących czynności:

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

Źródło zdarzeń

Dostawca EventSource zapisuje w źródle zdarzeń międzyplatformowych o nazwie Microsoft-Extensions-Logging. Na Windows dostawca używa ETW.

dotnet trace tooling

Narzędzie dotnet-trace to jest globalnym narzędziem interfejsu wiersza polecenia dla wielu platform, które umożliwia zbieranie śladów uruchomionego procesu na platformie .NET Core. Narzędzie zbiera dane dostawcy Microsoft.Extensions.Logging.EventSource przy użyciu .LoggingEventSource

Aby uzyskać instrukcje instalacji, zobacz dotnet-trace.

Użyj narzędzi dotnet trace , aby zebrać ślad z aplikacji:

  1. Uruchom aplikację za pomocą dotnet run polecenia .

  2. Określ identyfikator procesu (PID) aplikacji .NET Core:

    dotnet trace ps
    

    Znajdź identyfikator PID dla procesu, który ma taką samą nazwę jak zestaw aplikacji.

  3. dotnet trace Wykonaj polecenie .

    Ogólna składnia poleceń:

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

    W przypadku korzystania z powłoki poleceń programu PowerShell należy ująć --providers wartość w pojedynczy cudzysłów ('):

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

    Na platformach Windows dodaj -f speedscope opcję zmiany formatu wyjściowego pliku śledzenia na speedscope.

    W poniższej tabeli zdefiniowano słowo kluczowe :

    Słowo kluczowe Opis
    1 Rejestruj meta zdarzenia dotyczące pliku LoggingEventSource. Nie rejestruje zdarzeń z usługi ILogger.
    2 Włącza zdarzenie, Message gdy zostanie ILogger.Log() wywołana. Dostarcza informacje w sposób programowy (nie sformatowany).
    4 Włącza zdarzenie, FormatMessage gdy zostanie ILogger.Log() wywołana. Dostarcza sformatowaną wersję ciągu informacji.
    8 Włącza zdarzenie, MessageJson gdy zostanie ILogger.Log() wywołana. Przedstawia reprezentację argumentów w danych JSON.

    W poniższej tabeli wymieniono poziomy dostawcy:

    Poziom dostawcy Opis
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Analizowanie na poziomie kategorii może być ciągiem lub liczbą:

    Kategoria o nazwie value Wartość liczbowa
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Poziom dostawcy i poziom kategorii:

    • Są w odwrotnej kolejności.
    • Stałe ciągu nie są identyczne.

    Jeśli nie FilterSpecs zostaną określone, EventSourceLogger implementacja próbuje przekonwertować poziom dostawcy na poziom kategorii i stosuje go do wszystkich kategorii.

    Poziom dostawcy Poziom kategorii
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Jeśli FilterSpecs zostanie podany, każda kategoria, która znajduje się na liście, używa zakodowanych tam poziomu kategorii, wszystkie inne kategorie zostaną odfiltrowane.

    W poniższych przykładach założono, że:

    • Aplikacja jest uruchomiona i wywołująca .logger.LogDebug("12345")
    • Identyfikator procesu (PID) został ustawiony za pośrednictwem , set PID=12345gdzie 12345 jest rzeczywistym identyfikatorem PID.

    Spójrzmy na następujące polecenie:

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

    Powyższe polecenie ma następujące działanie:

    • Przechwytuje komunikaty debugowania.
    • Nie stosuje .FilterSpecs
    • Określa poziom 5, który mapuje kategorię Debugowanie.

    Spójrzmy na następujące polecenie:

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

    Powyższe polecenie ma następujące działanie:

    • Nie przechwytuje komunikatów debugowania, ponieważ poziom kategorii 5 to Critical.
    • Udostępnia .FilterSpecs

    Następujące polecenie przechwytuje komunikaty debugowania, ponieważ poziom 1 kategorii określa Debugwartość .

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

    Następujące polecenie przechwytuje komunikaty debugowania, ponieważ kategoria określa .Debug

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

    FilterSpecs wpisy dla {Logger Category} i {Category Level} reprezentują dodatkowe warunki filtrowania dzienników. Oddziel FilterSpecs wpisy średnikiem ; .

    Przykład użycia powłoki Windows polecenia:

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

    Poprzednie polecenie aktywuje:

    • Rejestrator źródła zdarzeń do tworzenia ciągów sformatowanych (4) dla błędów (2).
    • Microsoft.AspNetCore.Hosting rejestrowanie na poziomie Informational rejestrowania (4).
  4. Zatrzymaj narzędzia śledzenia dotnet, naciskając klawisz Enter lub klawisze CtrlC+.

    Ślad jest zapisywany z nazwą w trace.nettrace folderze, w dotnet trace którym jest wykonywane polecenie.

  5. Otwórz ślad za pomocą widoku perfview. Otwórz plik trace.nettrace i zapoznaj się ze zdarzeniami śledzenia.

Jeśli aplikacja nie skompilowa hosta za pomocą programu WebApplication.CreateBuilder, dodaj dostawcę źródła zdarzeń do konfiguracji rejestrowania aplikacji.

Aby uzyskać więcej informacji, zobacz:

Perfview

Zbieranie i wyświetlanie dzienników za pomocą narzędzia PerfView . Istnieją inne narzędzia do wyświetlania dzienników ETW, ale PerfView zapewnia najlepsze środowisko pracy ze zdarzeniami ETW emitowane przez ASP.NET Core.

Aby skonfigurować program PerfView do zbierania zdarzeń rejestrowanych przez tego dostawcę, dodaj ciąg *Microsoft-Extensions-Logging do listy Dodatkowi dostawcy. Nie pomijaj ciągu * na początku ciągu.

Windows EventLog

Dostawca EventLog wysyła dane wyjściowe dziennika do Windows dziennika zdarzeń. W przeciwieństwie do innych dostawców dostawca EventLog nie dziedziczy domyślnych ustawień innych niż dostawcy. Jeśli EventLog ustawienia dziennika nie zostaną określone, domyślnie będą mieć wartość LogLevel.Warning.

Aby rejestrować zdarzenia niższe niż LogLevel.Warning, jawnie ustaw poziom dziennika. W poniższym przykładzie domyślny poziom dziennika dzienników zdarzeń jest ustawiany na LogLevel.Information:

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

AddEventLogPrzeciążenia mogą przekazać .EventLogSettings Jeśli null lub nie zostanie określony, są używane następujące ustawienia domyślne:

  • LogName: "Aplikacja"
  • SourceName: "Środowisko uruchomieniowe .NET"
  • MachineName: używana jest nazwa komputera lokalnego.

Poniższy kod zmienia wartość z SourceName domyślnej na ".NET Runtime"MyLogs:


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

Azure App Service

Pakiet Microsoft.Extensions.Logging.AzureAppServices dostawcy zapisuje dzienniki w plikach tekstowych w systemie plików Azure App Service aplikacji oraz w magazynie obiektów blob na koncie usługi Azure Storage.

Pakiet dostawcy nie jest uwzględniony w udostępnionej platformie. Aby użyć dostawcy, dodaj pakiet dostawcy do projektu.

Aby skonfigurować ustawienia dostawcy, użyj i AzureFileLoggerOptionsAzureBlobLoggerOptions, jak pokazano w poniższym przykładzie:

using Microsoft.Extensions.Logging.AzureAppServices;

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

Po wdrożeniu w Azure App Service aplikacja używa ustawień w sekcji dzienników App Service na App Service stronie Azure Portal. Po zaktualizowaniu poniższych ustawień zmiany zostaną wprowadzone natychmiast bez konieczności ponownego uruchomienia lub ponownego uruchomienia aplikacji.

  • Application Logging (System plików)
  • Application Logging (obiekt blob)

Domyślna lokalizacja plików dziennika znajduje się w D:\\home\\LogFiles\\Application folderze , a domyślna nazwa pliku to diagnostics-yyyymmdd.txt. Domyślny limit rozmiaru pliku to 10 MB, a domyślna maksymalna liczba zachowywanych plików to 2. Domyślna nazwa obiektu blob to {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Ten dostawca rejestruje tylko wtedy, gdy projekt jest uruchamiany w środowisku platformy Azure.

Przesyłanie strumieniowe dzienników platformy Azure

Przesyłanie strumieniowe dzienników platformy Azure obsługuje wyświetlanie aktywności dziennika w czasie rzeczywistym z:

  • Serwer aplikacji
  • Serwer internetowy
  • Śledzenie żądań, które zakończyło się niepowodzeniem

Aby skonfigurować przesyłanie strumieniowe dzienników platformy Azure:

  • Przejdź do App Service dzienników aplikacji ze strony portalu aplikacji.
  • Ustaw Application Logging (System plików) na .
  • Wybierz poziom dziennika. To ustawienie dotyczy tylko przesyłania strumieniowego dzienników platformy Azure.

Przejdź do strony Strumień dzienników , aby wyświetlić dzienniki. Zarejestrowane komunikaty są rejestrowane za pomocą ILogger interfejsu .

Azure Application Insights

Pakiet Microsoft.Extensions.Logging.ApplicationInsights dostawcy zapisuje dzienniki do aplikacja systemu Azure Szczegółowe informacje. Application Szczegółowe informacje to usługa, która monitoruje aplikację internetową i udostępnia narzędzia do wykonywania zapytań i analizowania danych telemetrycznych. Jeśli używasz tego dostawcy, możesz analizować dzienniki i analizować je przy użyciu narzędzi application Szczegółowe informacje.

Dostawca rejestrowania jest dołączony jako zależność Microsoft.ApplicationInsights.AspNetCore, czyli pakietu, który udostępnia wszystkie dostępne dane telemetryczne dla ASP.NET Core. Jeśli używasz tego pakietu, nie musisz instalować pakietu dostawcy.

Pakiet Microsoft.ApplicationInsights.Web jest dla ASP.NET 4.x, a nie ASP.NET Core.

Więcej informacji można znaleźć w następujących zasobach:

Dostawcy rejestrowania innych firm

Struktury rejestrowania innych firm, które działają z ASP.NET Core:

Niektóre struktury innych firm mogą wykonywać rejestrowanie semantyczne, nazywane również rejestrowaniem strukturalnym.

Korzystanie z struktury innej firmy jest podobne do korzystania z jednego z wbudowanych dostawców:

  1. Dodaj NuGet do projektu.
  2. Wywołaj ILoggerFactory metodę rozszerzenia dostarczaną przez platformę rejestrowania.

Aby uzyskać więcej informacji, zobacz dokumentację każdego dostawcy. Dostawcy rejestrowania innych firm nie są obsługiwani przez firmę Microsoft.

Brak asynchronicznych metod rejestratora

Rejestrowanie powinno być tak szybkie, że nie jest warte kosztu wydajności kodu asynchronicznego. Jeśli magazyn danych rejestrowania działa wolno, nie zapisuj w nim bezpośrednio. Rozważ początkowe zapisywanie komunikatów dziennika w szybkim magazynie, a następnie przeniesienie ich do powolnego magazynu później. Na przykład podczas rejestrowania w SQL Server Log nie należy tego robić bezpośrednio w metodzie, Log ponieważ metody są synchroniczne. Zamiast tego synchroniczne dodawanie komunikatów dziennika do kolejki w pamięci i ściąganie komunikatów z kolejki przez proces roboczy w tle w celu asynchronicznego wypychania danych do SQL Server. Aby uzyskać więcej informacji, zobacz Guidance on how to log to a message queue for slow data stores (dotnet/AspNetCore.Docs #11801).

Zmienianie poziomów dziennika w uruchomionej aplikacji

Interfejs API rejestrowania nie zawiera scenariusza zmiany poziomów dziennika, gdy aplikacja jest uruchomiona. Jednak niektórzy dostawcy konfiguracji mogą ponownie załadować konfigurację, co ma natychmiastowy wpływ na konfigurację rejestrowania. Na przykład dostawca konfiguracji plików domyślnie ponownie ładuje konfigurację rejestrowania. Jeśli konfiguracja zostanie zmieniona w kodzie, gdy aplikacja jest uruchomiona, IConfigurationRoot.Reload aplikacja może wywołać wywołanie w celu zaktualizowania konfiguracji rejestrowania aplikacji.

ILogger i ILoggerFactory

Interfejsy ILogger<TCategoryName> i ILoggerFactory oraz implementacje są zawarte w zestaw .NET Core SDK. Są one również dostępne w następujących pakietach NuGet pakietów:

Stosowanie reguł filtrowania dzienników w kodzie

Preferowanym podejściem do ustawiania reguł filtrowania dzienników jest użycie konfiguracji.

W poniższym przykładzie pokazano, jak zarejestrować reguły filtrowania w kodzie:

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

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

logging.AddFilter("System", LogLevel.Debug) Określa poziom System kategorii i dziennika Debug. Filtr jest stosowany do wszystkich dostawców, ponieważ określony dostawca nie został skonfigurowany.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) Określa:

  • Dostawca Debug rejestrowania.
  • Poziom dziennika Information i wyższy.
  • Wszystkie kategorie rozpoczynające się od ."Microsoft"

Automatycznie rejestruj zakres za pomocą SpanId, TraceId, ParentId, Baggagei Tags.

Biblioteki rejestrowania niejawnie tworzą obiekt zakresu za pomocą SpanIdobiektów , TraceId, ParentIdiBaggageTags . To zachowanie jest konfigurowane za pośrednictwem usługi ActivityTrackingOptions.

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

Jeśli ustawiono traceparent nagłówek żądania HTTP, w zakresie dziennika zostanie pokazana wartość W3C parent-idparent-idSpanIdtraceparent z nagłówka powiązanego, ParentId a w zakresie dziennika zostanie pokazana aktualizacja dla następnego powiązanego kroku/zakresu. Aby uzyskać więcej informacji, zobacz Mutating the traceparent Field (Mutating the traceparent Field).

Tworzenie niestandardowego rejestratora

Aby utworzyć niestandardowy rejestrator, zobacz Implementowanie niestandardowego dostawcy rejestrowania na platformie .NET.

Dodatkowe zasoby

A RickAnderson, Juebank Gutsch, A także

W tym temacie opisano rejestrowanie w programie .NET, które ma zastosowanie do ASP.NET Core aplikacji. Aby uzyskać szczegółowe informacje na temat rejestrowania na platformie .NET, zobacz Rejestrowanie na platformie .NET. Aby uzyskać więcej informacji na temat rejestrowania w aplikacjachBlazor, zobacz ASP.NET Core Blazor rejestrowanie.

Wyświetlanie lub pobieranie przykładowego kodu (jak pobrać).

Dostawcy rejestrowania

Dostawcy rejestrowania przechowują dzienniki z wyjątkiem dostawcy Console , który wyświetla dzienniki. Na przykład dostawca aplikacja systemu Azure Szczegółowe informacje przechowuje dzienniki w aplikacja systemu Azure Szczegółowe informacje. Można włączyć wielu dostawców.

Domyślne szablony ASP.NET Core aplikacji internetowych:

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

Powyższy kod przedstawia klasę utworzoną Program za pomocą ASP.NET Core aplikacji internetowej. W kolejnych kilku sekcjach pozyskują przykłady oparte na ASP.NET Core aplikacji internetowej, które korzystają z hosta ogólnego. Aplikacje konsolowe inne niż hosty zostały omówione w dalszej części tego dokumentu.

Aby zastąpić domyślny zestaw dostawców rejestrowania dodany przez Host.CreateDefaultBuilderprogram , ClearProviders wywołaj i dodaj wymaganych dostawców rejestrowania. Na przykład następujący kod:

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

Aby uzyskać informacje o dodatkowych dostawcach, zobacz:

Tworzenie dzienników

Aby utworzyć dzienniki, użyj obiektu z ILogger<TCategoryName>iniekcji zależności (DI).

Poniższy przykład:

  • Tworzy rejestrator, ILogger<AboutModel>, który używa kategorii dziennika w pełni kwalifikowanej nazwy typu AboutModel. Kategoria dziennika jest ciągiem skojarzonym z każdym dziennika.
  • Wywołania LogInformation do logowania na Information poziomie. Poziom dziennika wskazuje ważność zarejestrowanego zdarzenia.
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);
    }
}

Poziomy i kategorie zostały szczegółowo opisane w dalszej części tego dokumentu.

Aby uzyskać informacje na temat BlazorASP.NET Core Blazor rejestrowania.

Tworzenie dzienników w głównych i uruchamiania pokazuje, jak tworzyć dzienniki w systemach Main i Startup.

Konfigurowanie rejestrowania

Konfiguracja rejestrowania jest często zapewniana przez Logging sekcję appsettings.{Environment}.json plików. Następujący plik appsettings.Development.json jest generowany przez szablony ASP.NET Core aplikacji internetowej:

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

W powyższym kodzie JSON:

  • Określono "Default"kategorie , "Microsoft""Microsoft.Hosting.Lifetime" i .
  • Kategoria "Microsoft" ma zastosowanie do wszystkich kategorii, które zaczynają się od "Microsoft". Na przykład to ustawienie dotyczy kategorii "Microsoft.AspNetCore.Routing.EndpointMiddleware" .
  • Kategoria "Microsoft" rejestruje dane na poziomie dziennika Warning i na wyższym poziomie.
  • Kategoria "Microsoft.Hosting.Lifetime" jest bardziej specyficzna niż "Microsoft" kategoria, "Microsoft.Hosting.Lifetime" więc kategoria rejestruje na poziomie dziennika "Informacje" i na wyższym poziomie.
  • Określony dostawca dziennika nie jest określony, więc LogLevel ma zastosowanie do wszystkich włączonych dostawców rejestrowania z wyjątkiem Windows Dziennika zdarzeń.

Właściwość Logging może mieć właściwości LogLevel dostawcy dzienników i . Określa LogLevel minimalny poziom , aby rejestrować dla wybranych kategorii. W powyższym pliku JSON określono InformationWarning poziomy dziennika. LogLevel wskazuje ważność dziennika i zakres od 0 do 6:

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

Jeśli określono LogLevel wartość , rejestrowanie jest włączone dla komunikatów na określonym poziomie lub wyższym. W poprzednim JSON kategoria Default jest rejestrowana dla Information i wyższych. Rejestrowane są Informationna przykład Warningkomunikaty , Error, Critical i . Jeśli nie LogLevel jest określony, rejestrowanie jest domyślnie na Information poziomie. Aby uzyskać więcej informacji, zobacz Poziomy dziennika.

Właściwość dostawcy może określać LogLevel właściwość. LogLevel w obszarze dostawcy określa poziomy logowania dla tego dostawcy i zastępuje ustawienia dziennika bez dostawcy. Rozważmy następujący appsettings.json plik:

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

Ustawienia w ustawieniach Logging.{providername}.LogLevel przesłonięcia w programie Logging.LogLevel. W poprzednim pliku JSON domyślny Debug poziom dziennika dostawcy jest ustawiony na :Information

Logging:Debug:LogLevel:Default:Information

Poprzednie ustawienie określa poziom dziennika Information dla każdej kategorii Logging:Debug: z wyjątkiem Microsoft.Hosting. Gdy określonej kategorii jest wymieniony, określonej kategorii zastępuje kategorii domyślnej. W powyższym JSON kategorie Logging:Debug:LogLevel i "Microsoft.Hosting""Default" przesłaniają ustawienia w Logging:LogLevel

Minimalny poziom dziennika można określić dla dowolnego z:

  • Konkcyjni dostawcy: na przykład Logging:EventSource:LogLevel:Default:Information
  • Określone kategorie: na przykład Logging:LogLevel:Microsoft:Warning
  • Wszyscy dostawcy i wszystkie kategorie: Logging:LogLevel:Default:Warning

Wszystkie dzienniki poniżej poziomu minimalnego nie są:

  • Przekazane do dostawcy.
  • Zarejestrowane lub wyświetlone.

Aby pominąć wszystkie dzienniki, określ wartość LogLevel.None. LogLevel.None ma wartość 6, która jest wyższa niż LogLevel.Critical (5).

Jeśli dostawca obsługuje zakresy dzienników, wskazuje, IncludeScopes czy są one włączone. Aby uzyskać więcej informacji, zobacz zakresy dzienników

Następujący plik appsettings.json zawiera wszystkich dostawców domyślnie włączonych:

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

W poprzednim przykładzie:

  • Kategorie i poziomy nie są sugerowanymi wartościami. W przykładzie podano, aby wyświetlić wszystkich domyślnych dostawców.
  • Ustawienia w ustawieniach Logging.{providername}.LogLevel przesłonięcia w programie Logging.LogLevel. Na przykład poziom w wartości Debug.LogLevel.Default zastępuje poziom w .LogLevel.Default
  • Używany jest każdy domyślny alias dostawcy. Każdy dostawca definiuje alias, który może być używany w konfiguracji, a nie w pełni kwalifikowaną nazwę typu. Wbudowane aliasy dostawców to:
    • Konsola
    • Debugowanie
    • EventSource
    • Eventlog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Ustawianie poziomu dziennika według wiersza polecenia, zmiennych środowiskowych i innej konfiguracji

Poziom dziennika może być ustawiany przez dowolnego z dostawców konfiguracji.

Separator : nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. __, podwójny podkreślenia, to:

  • Obsługiwane przez wszystkie platformy. Na przykład separator nie : jest obsługiwany przez powłokę Bash, ale __ jest.
  • Automatycznie zastępowane przez :

Następujące polecenia:

  • Ustaw klucz środowiska na Logging:LogLevel:Microsoft wartość na Information Windows.
  • Przetestuj ustawienia podczas korzystania z aplikacji utworzonej za pomocą ASP.NET Core szablonów aplikacji internetowych. Po dotnet run użyciu polecenia należy uruchomić polecenie w katalogu projektu set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Poprzednie ustawienie środowiska:

  • Jest ustawiany tylko w procesach uruchomionych z okna poleceń, w których zostały ustawione.
  • Nie jest odczytywany przez przeglądarki uruchomione z Visual Studio.

Następujące polecenie setx ustawia również klucz środowiska i wartość na Windows. W przeciwieństwie setdo , setx ustawienia są utrwalane. Przełącznik /M ustawia zmienną w środowisku systemowym. Jeśli /M nie jest używana, ustawiana jest zmienna środowiskowa użytkownika.

setx Logging__LogLevel__Microsoft Information /M

Rozważmy następujący appsettings.json plik:

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

Następujące polecenie ustawia poprzednią konfigurację w środowisku:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Na Azure App Service wybierz pozycję Nowe ustawienie aplikacji na stronie Ustawienia > Konfiguracji aplikacji. Azure App Service aplikacji są:

  • Szyfrowane w spoczynku i przesyłane za pośrednictwem szyfrowanego kanału.
  • Widoczne jako zmienne środowiskowe.

Aby uzyskać więcej informacji, zobacz Azure Apps: Override app configuration using the Azure Portal (Azure Apps: przesłanianie konfiguracji aplikacji przy użyciu witryny Azure Portal).

Aby uzyskać więcej informacji na temat ustawiania ASP.NET Core konfiguracji przy użyciu zmiennych środowiskowych, zobacz zmienne środowiskowe. Aby uzyskać informacje na temat używania innych źródeł konfiguracji, w tym wiersza polecenia, usługi Azure Key Vault, Azure App Configuration, innych formatów plików i innych, zobacz Configuration in ASP.NET Core (Konfiguracja w usłudze ASP.NET Core).

Jak są stosowane reguły filtrowania

Po utworzeniu ILogger<TCategoryName> obiektu obiekt ILoggerFactory wybiera pojedynczą regułę dla każdego dostawcy do zastosowania do tego rejestratora. Wszystkie komunikaty zapisywane przez wystąpienie ILogger są filtrowane na podstawie wybranych reguł. Najbardziej specyficzna reguła dla każdej pary dostawców i kategorii jest wybierana z dostępnych reguł.

Następujący algorytm jest używany dla każdego dostawcy, gdy element jest ILogger tworzony dla danej kategorii:

  • Wybierz wszystkie reguły, które pasują do dostawcy lub jego aliasu. Jeśli dopasowanie nie zostanie znalezione, zaznacz wszystkie reguły z pustym dostawcą.
  • Z wyniku poprzedniego kroku wybierz reguły z najdłuższym pasującymi prefiksami kategorii. Jeśli dopasowanie nie zostanie znalezione, wybierz wszystkie reguły, które nie określają kategorii.
  • Jeśli wybrano wiele reguł, weź ostatnią z nich.
  • Jeśli nie wybrano żadnych reguł, użyj .MinimumLevel

Rejestrowanie danych wyjściowych z dotnet run i Visual Studio

Zostaną wyświetlone dzienniki utworzone przy użyciu domyślnych dostawców rejestrowania:

  • W programie Visual Studio
    • W oknie Dane wyjściowe debugowania podczas debugowania.
    • W oknie ASP.NET Core sieci Web.
  • W oknie konsoli, gdy aplikacja jest uruchamiana za pomocą polecenia dotnet run.

Dzienniki, które zaczynają się od kategorii "Microsoft", ASP.NET Core kodu struktury. ASP.NET Core i kod aplikacji używają tego samego interfejsu API rejestrowania i dostawców.

Kategoria dziennika

Podczas tworzenia ILogger obiektu jest określana kategoria. Ta kategoria jest uwzględniana w każdym komunikacie dziennika utworzonym przez to wystąpienie klasy ILogger. Ciąg kategorii jest dowolny, ale konwencją jest użycie nazwy klasy. Na przykład w kontrolerze nazwa może być ."TodoApi.Controllers.TodoController" Aplikacja ASP.NET Core automatycznie ILogger<T>ILogger pobiera wystąpienie, które używa w pełni kwalifikowanej nazwy T typu jako kategorii:

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

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

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

Aby jawnie określić kategorię, wywołaj wywołanie :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.");
    }

Wywoływanie CreateLogger z stałą nazwą może być przydatne w przypadku korzystania z wielu metod, aby zdarzenia można było uporządkować według kategorii.

ILogger<T> jest odpowiednikiem wywołania CreateLogger z w pełni kwalifikowaną nazwą typu T.

Poziom dziennika

W poniższej tabeli wymieniono LogLevel wartości, wygodną Log{LogLevel} metodę rozszerzenia i sugerowane użycie:

LogLevel Wartość Metoda Opis
Ślad 0 LogTrace Zawierają najbardziej szczegółowe komunikaty. Te komunikaty mogą zawierać poufne dane aplikacji. Te komunikaty są domyślnie wyłączone i nie powinny być włączone w środowisku produkcyjnym.
Debugowania 1 LogDebug Debugowanie i opracowywanie. Należy zachować ostrożność w środowisku produkcyjnym ze względu na dużą ilość danych.
Informacje 2 LogInformation Śledzi ogólny przepływ aplikacji. Może mieć wartość długoterminową.
Ostrzeżenie 3 LogWarning W przypadku nietypowych lub nieoczekiwanych zdarzeń. Zwykle zawiera błędy lub warunki, które nie powodują awarii aplikacji.
Błąd 4 LogError Błędy i wyjątki, które nie mogą być obsługiwane. Te komunikaty wskazują błąd w bieżącej operacji lub żądaniu, a nie błąd dla całej aplikacji.
Krytyczne 5 LogCritical W przypadku awarii wymagających natychmiastowej uwagi. Przykłady: scenariusze utraty danych, za dużo miejsca na dysku.
Brak 6 Określa, że kategoria rejestrowania nie powinna zapisywać żadnych komunikatów.

W poprzedniej tabeli wartość jest wymieniona LogLevel od najniższej do najwyższej ważności.

Pierwszy parametr metody Dziennika, LogLevel, wskazuje ważność dziennika. Zamiast wywoływania Log(LogLevel, ...)metody , większość deweloperów wywołują metody rozszerzenia Log{LogLevel }. Metody Log{LogLevel} rozszerzenia wywołują metodę Log i określają wartość LogLevel. Na przykład następujące dwa wywołania rejestrowania są funkcjonalnie równoważne i dają ten sam dziennik:

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

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

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem to identyfikator zdarzenia. MyLogEvents element jest częścią przykładowej aplikacji i jest wyświetlany w sekcji Identyfikator zdarzenia dziennika.

MyDisplayRouteInfo i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs.Samples.RouteInfo. Metody wyświetlają i Controller rozsyłają Razor Page informacje.

Poniższy kod tworzy i Information rejestruje Warning :

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

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

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

    return ItemToDTO(todoItem);
}

W poprzednim kodzie pierwszym parametrem Log{LogLevel} jestMyLogEvents.GetItemidentyfikator zdarzenia dziennika. Drugi parametr to szablon komunikatu z symbolami zastępczymi wartości argumentu dostarczonych przez pozostałe parametry metody. Parametry metody zostały wyjaśnione w sekcji szablonu komunikatu w dalszej części tego dokumentu.

Wywołaj odpowiednią metodę Log{LogLevel} , aby kontrolować ilość danych wyjściowych dziennika zapisywanych na określonym nośniku magazynu. Na przykład:

  • W środowisku produkcyjnym:
    • Rejestrowanie na poziomach Trace lub Information generuje dużą ilość szczegółowych komunikatów dziennika. Aby kontrolować koszty i nie przekraczać limitów magazynu danych, TraceInformation rejestruj i wysyłaj komunikaty na poziomie do magazynu danych o dużej ilości danych. Rozważ ograniczenie wartości Trace i Information do określonych kategorii.
    • Rejestrowanie na różnych Warning poziomach Critical powinno tworzyć kilka komunikatów dziennika.
      • Koszty i limity magazynu zwykle nie są problemem.
      • Niewiele dzienników zapewnia większą elastyczność wyboru magazynu danych.
  • W programie:
    • Ustaw wartość Warning.
    • Dodawanie Trace komunikatów lub Information podczas rozwiązywania problemów. Aby ograniczyć dane wyjściowe, ustaw TraceInformation lub tylko dla kategorii, które są pod badaniem.

ASP.NET Core zapisuje dzienniki dla zdarzeń struktury. Rozważmy na przykład dane wyjściowe dziennika dla:

  • Aplikacja Razor Pages utworzona za pomocą ASP.NET Core szablonów.
  • Rejestrowanie ustawione na Logging:Console:LogLevel:Microsoft:Information
  • Nawigacja do Privacy strony:
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

Następujące zestawy JSON Logging:Console:LogLevel:Microsoft:Information:

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

Identyfikator zdarzenia dziennika

Każdy dziennik może określać identyfikator zdarzenia. Przykładowa aplikacja używa klasy MyLogEvents do definiowania identyfikatorów zdarzeń:

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

Identyfikator zdarzenia kojarzy zestaw zdarzeń. Na przykład wszystkie dzienniki związane z wyświetlaniem listy elementów na stronie mogą mieć numer 1001.

Dostawca rejestrowania może przechowywać identyfikator zdarzenia w polu identyfikatora, w komunikacie rejestrowania lub w ogóle nie. Dostawca debugowania nie wyświetla identyfikatorów zdarzeń. Dostawca konsoli wyświetla identyfikatory zdarzeń w nawiasach po kategorii:

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

Niektórzy dostawcy rejestrowania przechowują identyfikator zdarzenia w polu, które umożliwia filtrowanie identyfikatora.

Szablon wiadomości dziennika

Każdy interfejs API dziennika używa szablonu wiadomości. Szablon wiadomości może zawierać symbole zastępcze, dla których podano argumenty. Użyj nazw symboli zastępczych, a nie liczb.

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

Kolejność parametrów, a nie ich nazw symboli zastępczych, określa, które parametry są używane do zapewnienia wartości symboli zastępczych w komunikatach dziennika. W poniższym kodzie nazwy parametrów są niesekwencją w symbolach zastępczych szablonu komunikatu:

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

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

Jednak parametry są przypisywane do symboli zastępczych w kolejności: apples, pears, bananas. Komunikat dziennika odzwierciedla kolejność parametrów:

Parameters: 1, 2, 3

Takie podejście umożliwia dostawcom rejestrowania implementowanie rejestrowania semantycznego lub strukturalnego. Same argumenty są przekazywane do systemu rejestrowania, a nie tylko do sformatowanych szablonów komunikatów. Dzięki temu dostawcy rejestrowania mogą przechowywać wartości parametrów jako pola. Rozważmy na przykład następującą metodę rejestratora:

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

Na przykład podczas logowania do usługi Azure Table Storage:

  • Każda jednostka tabeli platformy Azure może mieć właściwości ID i RequestTime .
  • Tabele z właściwościami upraszczają zapytania dotyczące zarejestrowanych danych. Na przykład zapytanie może znaleźć wszystkie dzienniki w RequestTime określonym zakresie bez konieczności analizowania czasu poza wiadomością SMS.

Rejestrowanie wyjątków

Metody rejestratora mają przeciążenia, które przyjmą parametr wyjątku:

[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 i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs.Samples.RouteInfo. Metody wyświetlają i Controller rozsyłają Razor Page informacje.

Rejestrowanie wyjątków jest specyficzne dla dostawcy.

Domyślny poziom dziennika

Jeśli nie ustawiono domyślnego poziomu dziennika, domyślna wartość poziomu dziennika to Information.

Rozważmy na przykład następującą aplikację internetową:

  • Utworzone przy użyciu ASP.NET aplikacji internetowej.
  • appsettings.json i appsettings.Development.json usunięto lub zmieniono nazwę.

W przypadku poprzedniej konfiguracji przejście Tracedo prywatności lub strony głównej powoduje uzyskanie wielu komunikatów , Debugi InformationMicrosoft z nazwą kategorii.

Poniższy kod ustawia domyślny poziom dziennika, gdy domyślny poziom dziennika nie jest ustawiony w konfiguracji:

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

Ogólnie rzecz biorąc, poziomy dziennika powinny być określone w konfiguracji, a nie w kodzie.

Funkcja Filter

Funkcja filtru jest wywoływana dla wszystkich dostawców i kategorii, które nie mają przypisanych reguł przez konfigurację lub kod:

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

Powyższy kod wyświetla dzienniki konsoli, gdy kategoria zawiera lub ControllerMicrosoft , a poziom dziennika jest Information lub wyższy.

Ogólnie rzecz biorąc, poziomy dziennika powinny być określone w konfiguracji, a nie w kodzie.

ASP.NET Core i EF Core kategorii

W poniższej tabeli przedstawiono niektóre kategorie używane przez ASP.NET Core i Entity Framework Core oraz uwagi dotyczące dzienników:

Kategoria Uwagi
Microsoft.AspNetCore Ogólne ASP.NET Core diagnostyki.
Microsoft.AspNetCore.DataProtection Które klucze zostały rozważone, znalezione i użyte.
Microsoft.AspNetCore.HostFiltering Hosty dozwolone.
Microsoft.AspNetCore.Hosting Czas ukończenia żądań HTTP i czas ich rozpoczęcia. Które zestawy startowe hostowania zostały załadowane.
Microsoft.AspNetCore.Mvc MVC i diagnostyka Razor . Powiązanie modelu, wykonywanie filtru, kompilacja widoku, wybór akcji.
Microsoft.AspNetCore.Routing Informacje o dopasowywaniu trasy.
Microsoft.AspNetCore.Server Połączenia uruchamiają, zatrzymują i utrzymują aktywne odpowiedzi. Informacje o certyfikacie HTTPS.
Microsoft.AspNetCore.StaticFiles Obsługiwane pliki.
Microsoft.EntityFrameworkCore Ogólne Entity Framework Core diagnostyki. Aktywność i konfiguracja bazy danych, wykrywanie zmian, migracje.

Aby wyświetlić więcej kategorii w oknie konsoli, ustaw appsettings.Development.json następującą wartość:

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

Zakresy dzienników

Zakres może grupowanie zestawu operacji logicznych. To grupowanie może służyć do dołączania tych samych danych do każdego dziennika, który jest tworzony jako część zestawu. Na przykład każdy dziennik utworzony w ramach przetwarzania transakcji może zawierać identyfikator transakcji.

Zakres:

Następujący dostawcy obsługują zakresy:

Użyj zakresu przez opakowanie wywołań rejestratora w bloku using :

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

Wbudowaniu dostawców rejestrowania

ASP.NET Core obejmuje następujących dostawców rejestrowania w ramach udostępnionej struktury:

Następujący dostawcy rejestrowania są dostarczani przez firmę Microsoft, ale nie w ramach udostępnionej struktury. Muszą być zainstalowane jako dodatkowe nuget.

ASP.NET Core nie zawiera dostawcy rejestrowania do zapisywania dzienników w plikach. Aby zapisywać dzienniki w plikach ASP.NET Core aplikacji, rozważ użycie zewnętrznego dostawcy rejestrowania.

stdout Aby uzyskać informacje na temat rejestrowania i debugowania za pomocą modułu ASP.NET Core, zobacz Troubleshoot ASP.NET Core on Azure App Service and IIS and ASP.NET Core Module (ANCM) for IIS (Rozwiązywanie problemów z usługami Azure App Service i usługami IIS oraz modułem ASP.NET Core Module (ANCM) dla usług IIS.

Konsola

Dostawca Console rejestruje dane wyjściowe w konsoli. Aby uzyskać więcej informacji na temat wyświetlania Console dzienników w czasie opracowywania, zobacz Rejestrowanie danych wyjściowych z dotnet run i Visual Studio.

Debugowanie

Dostawca Debug zapisuje dane wyjściowe dziennika przy użyciu System.Diagnostics.Debug klasy . Wywołania zapisu System.Diagnostics.Debug.WriteLine do Debug dostawcy.

W systemie Linux lokalizacja Debug dziennika dostawcy jest zależna od dystrybucji i może być jedną z następujących czynności:

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

Źródło zdarzeń

Dostawca EventSource zapisuje w źródle zdarzeń międzyplatformowych o nazwie Microsoft-Extensions-Logging. Na Windows dostawca używa ETW.

dotnet trace tooling

Narzędzie dotnet-trace to międzyplatformowe narzędzie globalne interfejsu wiersza polecenia, które umożliwia zbieranie śladów uruchomionego procesu na platformie .NET Core. Narzędzie zbiera dane dostawcy Microsoft.Extensions.Logging.EventSource przy użyciu .LoggingEventSource

Aby uzyskać instrukcje dotyczące instalacji, zobacz dotnet-trace .

Użyj narzędzi śledzenia dotnet, aby zebrać ślad z aplikacji:

  1. Uruchom aplikację za pomocą dotnet run polecenia .

  2. Określ identyfikator procesu (PID) aplikacji .NET Core:

    dotnet trace ps
    

    Znajdź identyfikator PID dla procesu, który ma taką samą nazwę jak zestaw aplikacji.

  3. dotnet trace Wykonaj polecenie .

    Ogólna składnia poleceń:

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

    W przypadku korzystania z powłoki poleceń programu PowerShell należy ująć --providers wartość w a cudzysłów pojedynczy ('):

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

    Na platformach Windows dodaj -f speedscope opcję zmiany formatu wyjściowego pliku śledzenia na speedscope.

    W poniższej tabeli zdefiniowano słowo kluczowe :

    Słowo kluczowe Opis
    1 Rejestruj meta zdarzenia dotyczące pliku LoggingEventSource. Nie rejestruje zdarzeń z pliku ILogger.
    2 Włącza zdarzenie, Message gdy jest ILogger.Log() wywoływana. Dostarcza informacje w sposób programowy (nie sformatowany).
    4 Włącza zdarzenie, FormatMessage gdy jest ILogger.Log() wywoływana. Zawiera sformatowaną wersję ciągu informacji.
    8 Włącza zdarzenie, MessageJson gdy jest ILogger.Log() wywoływana. Przedstawia reprezentację argumentów w danych JSON.

    W poniższej tabeli wymieniono poziomy dostawcy:

    Poziom dostawcy Opis
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Analizowanie na poziomie kategorii może być ciągiem lub liczbą:

    Kategoria o nazwie value Wartość liczbowa
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Poziom dostawcy i poziom kategorii:

    • Są w odwrotnej kolejności.
    • Stałe ciągu nie są identyczne.

    Jeśli nie FilterSpecs zostaną określone, EventSourceLogger implementacja próbuje przekonwertować poziom dostawcy na poziom kategorii i stosuje go do wszystkich kategorii.

    Poziom dostawcy Poziom kategorii
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Jeśli FilterSpecs zostaną podane, każda kategoria, która znajduje się na liście, używa zakodowanych tam poziomu kategorii, wszystkie inne kategorie zostaną odfiltrowane.

    W poniższych przykładach założono, że:

    • Aplikacja jest uruchomiona i wywoływana .logger.LogDebug("12345")
    • Identyfikator procesu (PID) został ustawiony za pośrednictwem , set PID=12345gdzie 12345 jest rzeczywistym identyfikatorem PID.

    Spójrzmy na następujące polecenie:

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

    Powyższe polecenie ma następujące działanie:

    • Przechwytuje komunikaty debugowania.
    • Nie stosuje .FilterSpecs
    • Określa poziom 5, który mapuje kategorię Debugowanie.

    Spójrzmy na następujące polecenie:

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

    Powyższe polecenie ma następujące działanie:

    • Nie przechwytuje komunikatów debugowania, ponieważ poziom kategorii 5 to Critical.
    • Udostępnia .FilterSpecs

    Następujące polecenie przechwytuje komunikaty debugowania, ponieważ poziom kategorii 1 określa Debug.

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

    Następujące polecenie przechwytuje komunikaty debugowania, ponieważ kategoria określa Debug.

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

    FilterSpecs wpisy dla {Logger Category} i {Category Level} reprezentują dodatkowe warunki filtrowania dzienników. Oddziel FilterSpecs wpisy średnikiem ; .

    Przykład użycia powłoki Windows polecenia:

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

    Poprzednie polecenie aktywuje:

    • Rejestrator źródła zdarzeń do tworzenia sformatowanych ciągów (4) dla błędów (2).
    • Microsoft.AspNetCore.Hosting rejestrowanie na poziomie Informational rejestrowania (4).
  4. Zatrzymaj narzędzia śledzenia dotnet, naciskając klawisz Enter lub klawisze Ctrl+C.

    Ślad jest zapisywany z nazwą trace.nettrace w folderze, w którym dotnet trace jest wykonywane polecenie.

  5. Otwórz ślad za pomocą programu Perfview. Otwórz plik trace.nettrace i przejrzyj zdarzenia śledzenia.

Jeśli aplikacja nie skompilowała hosta za pomocą usługi CreateDefaultBuilder, dodaj dostawcę źródła zdarzeń do konfiguracji rejestrowania aplikacji.

Aby uzyskać więcej informacji, zobacz:

Perfview

Zbieranie i wyświetlanie dzienników za pomocą narzędzia PerfView . Istnieją inne narzędzia do wyświetlania dzienników ETW, ale PerfView zapewnia najlepsze środowisko pracy ze zdarzeniami ETW emitowane przez ASP.NET Core.

Aby skonfigurować program PerfView do zbierania zdarzeń rejestrowanych przez tego dostawcę, dodaj ciąg *Microsoft-Extensions-Logging do listy Dodatkowi dostawcy. Nie pomijaj ciągu * na początku ciągu.

Windows EventLog

Dostawca EventLog wysyła dane wyjściowe dziennika do Windows dziennika zdarzeń. W przeciwieństwie do innych dostawców dostawca EventLog nie dziedziczy domyślnych ustawień innych niż dostawcy. Jeśli EventLog ustawienia dziennika nie zostaną określone, domyślnie będą mieć wartość LogLevel.Warning.

Aby rejestrować zdarzenia niższe niż LogLevel.Warning, jawnie ustaw poziom dziennika. W poniższym przykładzie domyślny poziom dziennika dzienników zdarzeń jest ustawiany na LogLevel.Information:

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

Przeciążenia addEventLog mogą przekazywać .EventLogSettings Jeśli null lub nie zostanie określony, są używane następujące ustawienia domyślne:

  • LogName: "Aplikacja"
  • SourceName: "Środowisko uruchomieniowe .NET"
  • MachineName: używana jest nazwa komputera lokalnego.

Poniższy kod zmienia wartość z SourceName domyślnej na ".NET Runtime"MyLogs:

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

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

Azure App Service

Pakiet dostawcy Microsoft.Extensions.Logging.AzureAppServices zapisuje dzienniki w plikach tekstowych w systemie plików aplikacji Azure App Service i w magazynie obiektów blob na koncie usługi Azure Storage.

Pakiet dostawcy nie jest uwzględniony w udostępnionej platformie. Aby użyć dostawcy, dodaj pakiet dostawcy do projektu.

Aby skonfigurować ustawienia dostawcy, użyj i AzureFileLoggerOptionsAzureBlobLoggerOptions, jak pokazano w poniższym przykładzie:

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

Po wdrożeniu w Azure App Service aplikacja używa ustawień w sekcji dzienników App Service na App Service stronie Azure Portal. Po zaktualizowaniu poniższych ustawień zmiany zostaną wprowadzone natychmiast bez konieczności ponownego uruchomienia lub ponownego uruchomienia aplikacji.

  • Application Logging (System plików)
  • Application Logging (obiekt blob)

Domyślna lokalizacja plików dziennika znajduje się w folderze D:\home\LogFiles\Application , a domyślna nazwa pliku todiagnostics-yyyymmdd.txt. Domyślny limit rozmiaru pliku to 10 MB, a domyślna maksymalna liczba zachowywanych plików to 2. Domyślna nazwa obiektu blob to {nazwa aplikacji}{sygnatura czasowa}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Ten dostawca rejestruje tylko wtedy, gdy projekt jest uruchamiany w środowisku platformy Azure.

Przesyłanie strumieniowe dzienników platformy Azure

Przesyłanie strumieniowe dzienników platformy Azure obsługuje wyświetlanie aktywności dziennika w czasie rzeczywistym z:

  • Serwer aplikacji
  • Serwer internetowy
  • Śledzenie żądań, które zakończyło się niepowodzeniem

Aby skonfigurować przesyłanie strumieniowe dzienników platformy Azure:

  • Przejdź do App Service dzienników aplikacji ze strony portalu aplikacji.
  • Ustaw Application Logging (System plików) na .
  • Wybierz poziom dziennika. To ustawienie dotyczy tylko przesyłania strumieniowego dzienników platformy Azure.

Przejdź do strony Strumień dzienników , aby wyświetlić dzienniki. Zarejestrowane komunikaty są rejestrowane za pomocą ILogger interfejsu .

Azure Application Insights

Pakiet dostawcy Microsoft.Extensions.Logging.ApplicationInsights zapisuje dzienniki w aplikacja systemu Azure Szczegółowe informacje. Application Szczegółowe informacje to usługa, która monitoruje aplikację internetową i udostępnia narzędzia do wykonywania zapytań i analizowania danych telemetrycznych. Jeśli używasz tego dostawcy, możesz analizować dzienniki i analizować je przy użyciu narzędzi application Szczegółowe informacje.

Dostawca rejestrowania jest uwzględniony jako zależność Microsoft.ApplicationInsights.AspNetCore, który jest pakietem, który udostępnia wszystkie dostępne dane telemetryczne dla ASP.NET Core. Jeśli używasz tego pakietu, nie musisz instalować pakietu dostawcy.

Pakiet Microsoft.ApplicationInsights.Web jest ASP.NET 4.x, a nie ASP.NET Core.

Więcej informacji można znaleźć w następujących zasobach:

Dostawcy rejestrowania innych firm

Struktury rejestrowania innych firm, które działają z ASP.NET Core:

Niektóre struktury innych firm mogą wykonywać rejestrowanie semantyczne, nazywane również rejestrowaniem strukturalnym.

Korzystanie z struktury innej firmy jest podobne do korzystania z jednego z wbudowanych dostawców:

  1. Dodaj NuGet do projektu.
  2. Wywołaj ILoggerFactory metodę rozszerzenia dostarczaną przez platformę rejestrowania.

Aby uzyskać więcej informacji, zobacz dokumentację każdego dostawcy. Dostawcy rejestrowania innych firm nie są obsługiwani przez firmę Microsoft.

Aplikacja konsolowa bez hosta

Przykład sposobu używania hosta ogólnego w aplikacji konsolowej spoza sieci Web Program.cs można znaleźć w pliku przykładowej aplikacji Zadania w tle (zadania w tle z hostowaną usługą w u ASP.NET Core).

Kod rejestrowania dla aplikacji bez hosta ogólnego różni się sposobem dodaniu dostawców i tworzenia rejestratorów.

Dostawcy rejestrowania

W aplikacji konsolowej, która nie jest hostem, wywołaj metodę Add{provider name} rozszerzenia dostawcy podczas tworzenia pliku 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");
    }
}

Tworzenie dzienników

Aby utworzyć dzienniki, użyj ILogger<TCategoryName> obiektu . Użyj funkcji , LoggerFactory aby utworzyć element ILogger.

Poniższy przykład tworzy rejestrator z jako LoggingConsoleApp.Program kategorii.

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

W poniższym przykładzie rejestrator jest używany do tworzenia dzienników z poziomem Information . Poziom dziennika wskazuje ważność zarejestrowanego zdarzenia.

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

Poziomy i kategorie zostały szczegółowo opisane w tym dokumencie.

Rejestrowanie podczas budowy hosta

Rejestrowanie podczas budowy hosta nie jest obsługiwane bezpośrednio. Można jednak użyć oddzielnego rejestratora. W poniższym przykładzie rejestrator usługi Serilog jest używany do logowania się.CreateHostBuilder AddSerilog używa konfiguracji statycznej określonej w pliku 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();
        }
    }
}

Konfigurowanie usługi, która zależy od ILogger

Wstrzykiwanie konstruktora rejestratora Startup do działa we wcześniejszych wersjach ASP.NET Core ponieważ dla hosta internetowego jest tworzony oddzielny kontener di. Aby uzyskać informacje o tym, dlaczego dla hosta ogólnego jest tworzony tylko jeden kontener, zobacz anons o istotnej zmianie.

Aby skonfigurować usługę, która zależy od ILogger<T>metody , użyj iniekcji konstruktora lub podaj metodę fabryki. Metoda fabryki jest zalecana tylko wtedy, gdy nie ma innej opcji. Rozważmy na przykład usługę, która wymaga wystąpienia ILogger<T> dostarczonego przez 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 };
    });
}

Powyższy wyróżniony kod jest uruchamiany Func<T,TResult> po raz pierwszy, gdy kontener di musi skonstruować wystąpienie klasy MyService. W ten sposób można uzyskać dostęp do dowolnej z zarejestrowanych usług.

Tworzenie dzienników w programie Main

Poniższy kod loguje się przez Main uzyskanie wystąpienia ILogger z di po sbudowania hosta:

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

Tworzenie dzienników podczas uruchamiania

Poniższy kod zapisuje dzienniki w programie 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();
    });
}

Zapisywanie dzienników przed ukończeniem konfiguracji kontenera di w Startup.ConfigureServices metodzie nie jest obsługiwane:

  • Wstrzykiwanie rejestratora do konstruktora Startup nie jest obsługiwane.
  • Iniekcja rejestratora do Startup.ConfigureServices sygnatury metody nie jest obsługiwana

Przyczyną tego ograniczenia jest to, że rejestrowanie zależy od di i konfiguracji, co z kolei zależy od di. Kontener di nie zostanie ustawiony, dopóki nie ConfigureServices zakończy się.

Aby uzyskać informacje na ILogger<T>Startup temat konfigurowania usługi, która zależy od lub dlaczego wstrzykiwanie konstruktora rejestratora do pracy we wcześniejszych wersjach, zobacz Konfigurowanie usługi, która zależy od ILogger

Brak asynchronicznych metod rejestratora

Rejestrowanie powinno być tak szybkie, że nie jest warte kosztu wydajności kodu asynchronicznego. Jeśli magazyn danych rejestrowania działa wolno, nie zapisuj w nim bezpośrednio. Rozważ początkowe zapisywanie komunikatów dziennika w szybkim magazynie, a następnie przeniesienie ich do powolnego magazynu później. Na przykład podczas rejestrowania w SQL Server Log nie należy tego robić bezpośrednio w metodzie, Log ponieważ metody są synchroniczne. Zamiast tego synchroniczne dodawanie komunikatów dziennika do kolejki w pamięci i ściąganie komunikatów z kolejki przez proces roboczy w tle w celu asynchronicznego wypychania danych do SQL Server. Aby uzyskać więcej informacji, zobacz ten GitHub problem.

Zmienianie poziomów dziennika w uruchomionej aplikacji

Interfejs API rejestrowania nie zawiera scenariusza zmiany poziomów dziennika, gdy aplikacja jest uruchomiona. Jednak niektórzy dostawcy konfiguracji mogą ponownie załadować konfigurację, co ma natychmiastowy wpływ na konfigurację rejestrowania. Na przykład dostawca konfiguracji plików domyślnie ponownie ładuje konfigurację rejestrowania. Jeśli konfiguracja zostanie zmieniona w kodzie, gdy aplikacja jest uruchomiona, IConfigurationRoot.Reload aplikacja może wywołać wywołanie w celu zaktualizowania konfiguracji rejestrowania aplikacji.

ILogger i ILoggerFactory

Interfejsy ILogger<TCategoryName> i ILoggerFactory oraz implementacje są zawarte w zestaw .NET Core SDK. Są one również dostępne w następujących pakietach NuGet pakietów:

Stosowanie reguł filtrowania dzienników w kodzie

Preferowanym podejściem do ustawiania reguł filtrowania dzienników jest użycie konfiguracji.

W poniższym przykładzie pokazano, jak zarejestrować reguły filtrowania w kodzie:

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) Określa poziom System kategorii i dziennika Debug. Filtr jest stosowany do wszystkich dostawców, ponieważ określony dostawca nie został skonfigurowany.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) Określa:

  • Dostawca Debug rejestrowania.
  • Poziom dziennika Information i wyższy.
  • Wszystkie kategorie rozpoczynające się od ."Microsoft"

Automatyczne rejestrowanie zakresu za pomocą spanId, TraceId i ParentId

Biblioteki rejestrowania niejawnie tworzą obiekt zakresu za pomocą obiektów SpanId, TraceIdi ParentId. To zachowanie jest konfigurowane za pośrednictwem usługi ActivityTrackingOptions.

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

Jeśli ustawiono traceparent nagłówek żądania HTTP, w zakresie dziennika zostanie pokazana wartość W3C parent-idparent-idSpanIdtraceparent z nagłówka powiązanego, ParentId a w zakresie dziennika zostanie pokazana aktualizacja dla następnego powiązanego kroku/zakresu. Aby uzyskać więcej informacji, zobacz Mutating the traceparent Field (Mutating the traceparent Field).