Pengelogan di .NET dan ASP.NET Core

Artikel ini menjelaskan pengelogan di aplikasi ASP.NET Core. Untuk panduan umum tentang pengelogan di .NET, lihat Pengelogan di C# dan .NET. Untuk Blazor panduan pengelogan, yang menambahkan atau menggantikan panduan ini, lihat pengelogan ASP.NET CoreBlazor.

Penyedia pencatatan log

ASP.NET Core mendukung pengelogan terstruktur berkinerja tinggi melalui ILogger API untuk membantu Anda memantau perilaku aplikasi dan mendiagnosis masalah. Log ditulis ke tujuan yang berbeda dengan mengonfigurasi penyedia pengelogan. Sekumpulan penyedia pengelogan dibangun ke dalam kerangka kerja, dan ada banyak penyedia pihak ketiga yang tersedia. Beberapa penyedia dapat diaktifkan dalam aplikasi.

Sebagian besar penyedia pengelogan menulis pesan log ke sistem penyimpanan data. Misalnya, penyedia pengelogan Azure Application Insights menyimpan log di Azure Application Insights. Satu penyedia, Console penyedia, hanya menampilkan pesan log. Penyedia Console berguna saat menjalankan aplikasi secara lokal untuk pemantauan dan debugging secara langsung.

Aplikasi yang dibuat dari templat proyek aplikasi web ASP.NET Core akan memanggil WebApplication.CreateBuilder dalam file aplikasi Program, yang menambahkan penyedia pencatatan default berikut:

• Console
• Debug
• EventSource
• Windows EventLog

var builder = WebApplication.CreateBuilder(args);

Untuk mengambil alih penyedia pengelogan default, panggil ClearProvidersWebApplicationBuilder.Logging dan gunakan metode ekstensi penyedia pengelogan untuk menambahkan penyedia pengelogan. Contoh berikut hanya menyiapkan penyedia pengelogan Console :

var builder = WebApplication.CreateBuilder(args);

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

Atau, kode sebelumnya dapat ditulis sebagai berikut dengan ILoggingBuilder :ConfigureLogging

var builder = WebApplication.CreateBuilder(args);

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

Penyedia tambahan tercakup dalam bagian Penyedia pengelogan bawaan dan penyedia pengelogan pihak ketiga .

Output pengelogan

Log yang dibuat oleh penyedia pengelogan default ditampilkan:

• Di Visual Studio
  • Di jendela keluaran Debug saat melakukan debug.
  • Di jendela ASP.NET Core Web Server .
• Di shell perintah, aplikasi dijalankan dengan perintah dotnet run.

.NET secara umum dan ASP.NET Core menggunakan API pengelogan dan penyedia yang sama. Informasi lebih lanjut dapat ditemukan di Pengelogan di C# dan .NET, yang mencakup skenario pengelogan umum untuk C# dan .NET. Artikel ini berfokus pada pengelogan aplikasi ASP.NET Core.

Membuat pesan log

Untuk membuat pesan log, gunakan ILogger<TCategoryName> objek dari injeksi dependensi (DI).

Contoh berikut:

• Buat ILogger yang menentukan kategori log berdasarkan nama jenis yang lengkap. Kategori log adalah string yang terkait dengan setiap log, yang berguna untuk mengidentifikasi, mengurutkan, dan memfilter pesan log. Informasi selengkapnya tentang kategori log disediakan nanti di artikel ini.
• Memanggil LogInformation untuk mencatat log pada level Information. Tingkat log menunjukkan tingkat keparahan peristiwa yang dicatat. Informasi selengkapnya tentang tingkat log disediakan nanti di artikel ini.

Di halaman penghitung berikut (CounterRazor komponen) di aplikasi Blazor, ILogger<Counter> diinjeksikan menggunakan direktif@inject. Instans pencatat (Logger) digunakan untuk mencatat informasi saat metode dipanggil IncrementCount .

Pages/Counter.razor:

@page "/counter"
@inject ILogger<Counter> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        Logger.LogInformation("Someone incremented the counter!");

        currentCount++;
    }
}

Pesan log:

BlazorSample.Components.Pages.Counter: Information: Someone incremented the counter!

Kategori log adalah BlazorSample.Components.Pages.Counter, dan tingkat log (tingkat keparahan) adalah Information. Pesannya adalah Someone incremented the counter!.

Dalam file kelas halaman privasi pada Pages berikut Razor, ILogger<PrivacyModel> disuntikkan ke dalam konstruktor kelas untuk merekam saat halaman dikunjungi. Perhatikan dalam contoh ini bahwa pesan adalah templat yang mengambil tanggal dan waktu UTC saat ini (DateTime.UtcNow) dan menulisnya ke dalam pesan log. Templat pesan log dibahas di bagian Templat pesan log nanti di artikel ini.

Pages/Privacy.cshtml.cs:

public class PrivacyModel(ILogger<PrivacyModel> logger) : PageModel
{
    public void OnGet() => logger.LogInformation("Privacy page visited at {DT}", 
        DateTime.UtcNow);
}

Templat pesan log

Templat pesan log dapat berisi tempat penampung untuk argumen yang disediakan. Gunakan nama untuk placeholder, bukan angka.

Dalam contoh berikut, {Id} adalah tempat penampung pengidentifikasi untuk ID item, dan id merupakan parameter pengidentifikasi.

Logger.LogInformation(LogEvent.GetItem, "Getting item {Id}", id);

Logger.LogWarning(LogEvent.GetItemNotFound, "Get({Id}) NOT FOUND", id);

Urutan parameter, bukan nama tempat penampungnya, menentukan parameter mana yang digunakan untuk memberikan nilai tempat penampung dalam pesan log. Dalam kode berikut, nama parameter tidak berurutan di tempat penampung template pesan:

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

Logger.LogInformation("{Pears}, {Bananas}, {Apples}", apples, pears, bananas);

Namun, parameter diisikan ke placeholder sesuai urutan: apples, pears, bananas. Pesan log mencerminkan urutan parameter:

1, 2, 3

Pendekatan ini memungkinkan penyedia pengelogan untuk mengimplementasikan pengelogan semantik atau terstruktur. Argumen itu sendiri diteruskan ke sistem pengelogan, bukan hanya template pesan yang diformat. Ini memungkinkan penyedia pengelogan untuk menyimpan nilai parameter sebagai bidang. Misalnya, pertimbangkan metode pencatat berikut:

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

Saat masuk ke Penyimpanan Tabel Azure:

• Setiap entitas Azure Table dapat memiliki properti ID dan RequestTime.
• Tabel dengan properti menyederhanakan kueri pada data yang dicatat. Misalnya, kueri dapat menemukan semua log dalam rentang RequestTime tertentu tanpa harus menguraikan waktu habis pesan teks.

Masuk saat pengaktifan aplikasi

Contoh berikut memanggil WebApplication.Logger dalam Program file untuk mencatat pesan informasi:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.Logger.LogInformation("Adding Routes");

app.MapGet("/", () => "Hello World!");

app.Logger.LogInformation("Starting the app");

app.Run();

Contoh ini memanggil AddConsole untuk melakukan pencatatan di titik akhir /Test.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("'Test' logging in the Program file");
    await response.WriteAsync("Testing");
});

app.Run();

Contoh berikut memanggil AddSimpleConsole, menonaktifkan output warna dengan opsi pemformat konsol, dan mencatat di /Test endpoint.

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(
    option => option.ColorBehavior = LoggerColorBehavior.Disabled);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("'Test' logging in the Program file");
    await response.WriteAsync("Testing");
});

app.Run();

Mengonfigurasi pengelogan

Saat objek ILogger dibuat, kategori ditentukan. Kategori tersebut disertakan dengan setiap pesan log yang dibuat oleh instans pencatat tersebut.

Tingkat log menentukan tingkat detail untuk pesan log pada tingkat default untuk aplikasi secara keseluruhan dan untuk rakitan aplikasi tertentu. Tingkat log dapat diatur oleh salah satu penyedia konfigurasi.

Pengaturan aplikasi

Konfigurasi logging biasanya disediakan oleh bagian Logging dalam file appsettings.{ENVIRONMENT}.json, di mana placeholder {ENVIRONMENT} adalah environment. File appsettings.Development.json berikut dibuat oleh template aplikasi web ASP.NET Core:

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

Dalam JSON sebelumnya:

• Kategori "Default" dan "Microsoft.AspNetCore" telah ditentukan.
• Kategori "Microsoft.AspNetCore" berlaku untuk semua kategori yang dimulai dengan "Microsoft.AspNetCore". Misalnya, pengaturan ini berlaku untuk kategori "Microsoft.AspNetCore.Routing.EndpointMiddleware".
• Kategori "Microsoft.AspNetCore" dicatat pada tingkat log Warning atau lebih parah.
• Penyedia log tertentu tidak ditentukan, jadi LogLevel berlaku untuk semua penyedia pengelogan yang diaktifkan kecuali untuk Windows EventLog.

Properti Logging dapat memiliki properti LogLevel dan log provider. LogLevel menentukan tingkat minimum yang akan dicatat untuk kategori yang dipilih. Dalam JSON sebelumnya, level log Information dan Warning ditentukan. LogLevel menunjukkan tingkat keparahan log, yang ditunjukkan dalam tabel berikut dengan nilai enum yang sesuai.

Tingkat catatan	Value
Trace	0
Debug	1
Information	2
Warning	3
Error	4
Critical	5
None	6

Jika LogLevel ditentukan, pencatatan diaktifkan untuk pesan pada tingkat yang ditentukan atau lebih tinggi (lebih parah). Dalam JSON sebelumnya, kategori Default dicatat untuk Information dan yang lebih tinggi. Misalnya, pesan Information, Warning, Error, dan Critical dicatat. Jika tidak ada LogLevel yang ditentukan, pengelogan diatur ke default, yakni tingkat Information. Untuk informasi lebih lanjut, lihat Tingkat log.

Properti penyedia dapat menentukan properti LogLevel. LogLevel di bawah provider menentukan level yang dicatat untuk provider tersebut, dan mengesampingkan pengaturan log umum. Pertimbangkan file appsettings.json berikut:

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

Pengaturan di Logging.{PROVIDER NAME}.LogLevel menggantikan pengaturan di Logging.LogLevel, dengan placeholder {PROVIDER NAME} merupakan nama penyedia. Dalam JSON sebelumnya, tingkat log default penyedia Debug diatur ke Information:

Logging:Debug:LogLevel:Default:Information

Pengaturan sebelumnya menetapkan tingkat log Information untuk setiap kategori Logging:Debug: kecuali Microsoft.Hosting. Ketika kategori tertentu dicantumkan, kategori tersebut menggantikan kategori default. Di JSON sebelumnya, Logging:Debug:LogLevel kategori "Microsoft.Hosting" dan "Default" ambil alih pengaturan di Logging:LogLevel.

Tingkat log minimum dapat ditentukan untuk salah satu dari:

• Contoh penyedia tertentu: Logging:EventSource:LogLevel:Default:Information
• Contoh kategori tertentu: Logging:LogLevel:Microsoft:Warning
• Semua penyedia dan semua kategori: Logging:LogLevel:Default:Warning

Setiap log di bawah tingkat minimum tidak:

• Diteruskan ke penyedia.
• Dicatat atau ditampilkan.

Untuk menyembunyikan semua log, tentukan LogLevel.None. LogLevel.None memiliki nilai 6, yang lebih tinggi dari LogLevel.Critical (5).

Jika penyedia mendukung cakupan log, IncludeScopes menunjukkan apakah cakupan diaktifkan. Untuk informasi lebih lanjut, lihat cakupan pencatatan log.

File appsettings.json berikut berisi semua penyedia yang diaktifkan secara default:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Dalam sampel sebelumnya:

• Kategori dan tingkatan bukan nilai yang disarankan. Sampel disediakan untuk menampilkan semua penyedia default.
• Pengaturan di Logging.{PROVIDER NAME}.LogLevel menggantikan pengaturan di Logging.LogLevel, dengan placeholder {PROVIDER NAME} merupakan nama penyedia. Misalnya, tingkat di Debug.LogLevel.Default menggantikan tingkat di LogLevel.Default.
• Setiap alias penyedia bawaan digunakan. Setiap penyedia mendefinisikan alias yang dapat digunakan dalam konfigurasi sebagai pengganti nama tipe yang sepenuhnya memenuhi syarat. Alias penyedia bawaan adalah:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Antarmuka baris perintah

Variabel lingkungan untuk konfigurasi pengelogan dapat diatur melalui shell perintah.

Pemisah titik dua (:) tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. Misalnya, Bash tidak mendukung titik dua (:) sebagai pemisah. Semua platform mendukung sintaks garis bawah ganda (__) dan secara otomatis menggantinya dengan titik dua (:).

Atur variabel lingkungan dengan perintah set pada Windows untuk command shell saat ini. Dalam contoh berikut, kunci Logging:LogLevel:Microsoft lingkungan diatur ke nilai Information. Anda dapat menguji pengaturan dengan aplikasi apa pun yang dibuat dari templat proyek aplikasi web ASP.NET Core.

set Logging__LogLevel__Microsoft=Information

Jalankan dotnet run perintah di direktori proyek setelah menjalankan perintah sebelumnya set :

dotnet run

Variabel lingkungan sebelumnya:

• Hanya diatur untuk aplikasi yang diluncurkan dari shell perintah saat ini.
• Tidak dibaca oleh browser yang diluncurkan oleh Visual Studio atau Visual Studio Code.

setx Gunakan untuk mempertahankan variabel lingkungan di seluruh instans shell perintah. Pengalih /M mengatur variabel di lingkungan sistem. Jika /M tidak digunakan, variabel lingkungan pengguna diatur.

setx Logging__LogLevel__Microsoft Information /M

Note

Saat mengonfigurasi variabel lingkungan dengan nama yang berisi . (titik) di macOS dan Linux, lihat pertanyaan "Mengekspor variabel dengan titik (.) di dalamnya" di Stack Exchange dan jawaban yang diterima yang terkait.

Konfigurasikan Azure App Service

Di Azure App Service, ikuti panduan di Mengonfigurasi aplikasi App Service untuk mengatur variabel lingkungan pengelogan.

Untuk informasi selengkapnya, lihat Azure Apps: Mengambil alih konfigurasi aplikasi menggunakan portal Azure.

Kategori log

Saat objek ILogger dibuat, kategori ditentukan. Kategori disertakan dengan setiap pesan log yang dibuat oleh instans pencatat tersebut. String kategori bersifat arbitrer, tetapi konvensinya adalah menggunakan nama kelas yang sepenuhnya memenuhi syarat. Aplikasi web ASP.NET Core menggunakan ILogger<T> untuk membuat instance pencatat yang menggunakan nama tipe T yang sepenuhnya berkualifikasi sebagai kategori.

Pesan log dengan nama kategori yang dimulai dengan "Microsoft" berasal dari .NET. Biasanya, pesan log yang dimulai dengan nama rakitan aplikasi berasal dari aplikasi. Paket di luar .NET biasanya memiliki kategori berdasarkan nama rakitan dari paket. Untuk daftar kategori log umum, lihat bagian Kategori log umum .

Dalam komponen Razor dari aplikasi Blazor, di mana tipe T adalah Counter untuk halaman penghitung yang dirender oleh komponen Counter (Pages/Counter.razor):

@inject ILogger<Counter> Logger

Razor Dalam model kelas halaman Halaman, di mana jenisnya T adalah PrivacyModel untuk halaman privasi (Pages/Privacy.cshtml.cs):

public class PrivacyModel(ILogger<PrivacyModel> logger) : PageModel

Jika kategorisasi lebih lanjut diinginkan, konvensinya adalah menggunakan nama hierarkis dengan menambahkan subkategori ke nama kelas yang sepenuhnya memenuhi syarat menggunakan ILoggerFactory.CreateLogger. Pendekatan ini berguna untuk mengaitkan pesan log dengan komponen atau metode kelas.

Komponen berikut Counter menyimpan log dari metode IncrementByOne dengan kategori BlazorSample.Components.Pages.Counter.IncrementByOne dan dari metode IncrementByTen dengan kategori BlazorSample.Components.Pages.Privacy.IncrementByTen.

Pages/Counter.razor:

@page "/counter"
@inject ILogger<Counter> Logger

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementByOne">Click me (+1)</button>
<button class="btn btn-primary" @onclick="IncrementByTen">Click me (+10)</button>

@code {
    private int currentCount = 0;

    private void IncrementByOne()
    {
        var logger = Logger.CreateLogger($"{typeof(Counter)}.IncrementByOne");
        Logger.LogInformation("Someone incremented the counter!");
        currentCount++;
    }

    private void IncrementByTen()
    {
        var logger = Logger.CreateLogger($"{typeof(Counter)}.IncrementByTen");
        Logger.LogInformation("Someone incremented the counter!");
        currentCount += 10;
    }
}

Pesan log:

BlazorSample.Components.Pages.Counter.IncrementByOne: Information: Someone incremented the counter!
BlazorSample.Components.Pages.Counter.IncrementByTen: Information: Someone incremented the counter!

Razor Dalam model kelas halaman Halaman yang menggunakan kategori kustom ("CustomCategory") untuk seluruh model halaman:

public class PrivacyModel(ILoggerFactory logger) : PageModel
{
    private readonly ILogger _logger = 
        logger.CreateLogger($"{typeof(PrivacyModel)}.CustomCategory");

    public void OnGet() =>
        _logger.LogInformation("Privacy page visited");
}

ID peristiwa log

Setiap pesan log dapat menentukan ID peristiwa. Contoh berikut membuat sekumpulan ID peristiwa kustom untuk digunakan oleh aplikasi. Perhatikan bagaimana ID berada dalam rentang 1.000 untuk operasi buat, baca, perbarui, dan hapus (CRUD), 3.000 untuk pengelogan pengujian, dan dalam rentang 4.000 untuk skenario yang tidak ditemukan:

public class LogEvent
{
    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;
}

Digunakan dalam Razor kode komponen, di mana ILogger<T> instans (Logger) disuntikkan:

• LogEvent.GetItem ID (1002) digunakan dengan pesan log informasi untuk mengambil item berdasarkan pengidentifikasinya (id).
• LogEvent.GetItemNotFound ID (4000) digunakan dengan pesan log peringatan jika item tidak ditemukan.

Logger.LogInformation(LogEvent.GetItem, "Getting item {Id}", id);

var todoItem = await TodoItemService.FindAsync(id);

if (todoItem == null)
{
    Logger.LogWarning(LogEvent.GetItemNotFound, "Get({Id}) NOT FOUND", id);

    return NotFound();
}

Penyedia pengelogan dapat menyimpan ID peristiwa dalam ID (memungkinkan pemfilteran pada ID), dalam pesan log, atau tidak sama sekali. PenyediaDebug tidak menampilkan ID peristiwa. Penyedia konsol menunjukkan ID peristiwa dalam tanda kurung setelah kategori:

info: BlazorSample.Components.Pages.Items[1002]
      Getting item 1
warn: BlazorSample.Components.Pages.Items[4000]
      Get(1) NOT FOUND

Tingkat log

Tabel berikut menjelaskan tingkat pencatatan log dari yang terendah hingga tertinggi dalam hal keparahan, nilai enum yang sesuai, dan metode ekstensi kenyamanan mereka.

LogLevel	Value	Method	Description
Trace	0	LogTrace	Berisi pesan paling terperinci. Pesan ini mungkin berisi data aplikasi yang sensitif. Pesan-pesan ini dinonaktifkan secara bawaan dan tidak boleh diaktifkan di lingkungan produksi.
Debug	1	LogDebug	Untuk debugging dan pengembangan. Gunakan dengan hati-hati dalam produksi karena tingginya volume pesan yang dicatat.
Information	2	LogInformation	Melacak alur umum aplikasi.
Warning	3	LogWarning	Untuk peristiwa yang tidak normal atau tidak terduga. Biasanya menyertakan kesalahan atau kondisi yang tidak menyebabkan aplikasi gagal.
Error	4	LogError	Biasanya digunakan untuk kesalahan dan pengecualian yang tidak tertangani. Pesan-pesan ini menunjukkan kegagalan dalam operasi atau permintaan saat ini, bukan kegagalan di seluruh aplikasi.
Critical	5	LogCritical	Untuk kegagalan yang memerlukan perhatian segera, seperti kehilangan data atau kehabisan ruang disk.
None	6	—	Menentukan bahwa kategori pengelogan tidak boleh menulis pesan.

Parameter pertama metode Log, LogLevel, menunjukkan tingkat keparahan log. Daripada memanggil Log(LogLevel, ...), sebagian besar pengembang memanggil LoggerExtensions metode. Misalnya, dua panggilan pengelogan berikut secara fungsional setara dan menghasilkan hal yang sama berdasarkan instans yang disuntikkan ILogger<T> (Logger) dalam Razor komponen:

Logger.Log(LogLevel.Information, LogEvent.TestItem, routeInfo);

Logger.LogInformation(LogEvent.TestItem, routeInfo);

Note

LogEvent.TestItem adalah ID peristiwa log.

Log pada tingkat yang sesuai untuk mengontrol berapa banyak output log yang ditulis ke media penyimpanan tertentu:

• Dalam produksi:
  • Pencatatan log pada tingkat Trace, Debug, atau Information menghasilkan pesan log terperinci dalam jumlah besar. Untuk mengontrol biaya dan tidak melebihi batas penyimpanan data, catat tingkat ini ke penyimpanan data bervoluter rendah volume tinggi. Pertimbangkan untuk membatasi tingkat ini ke kategori tertentu.
  • Pengelogan pada tingkat Warning hingga Critical biasanya menghasilkan sedikit pesan log.
    • Batas biaya dan penyimpanan biasanya tidak menjadi masalah.
    • Hanya sedikit log yang memberikan fleksibilitas lebih besar dalam memilih penyimpanan data.
• Dalam pengembangan:
  • Kami merekomendasikan level Information ("Default": "Information") untuk logging default dan level Warning untuk rakitan Microsoft ASP.NET Core ("Microsoft.AspNetCore": "Warning").
  • Tambahkan Trace dan Debug, atau Information pesan saat memecahkan masalah. Untuk membatasi output, hanya atur tingkat pengelogan ini untuk kategori yang sedang diselidiki.

Mengubah tingkat log di aplikasi yang sedang berjalan

API Pengelogan tidak menyertakan dukungan untuk mengubah tingkat log saat aplikasi sedang berjalan. Namun, beberapa penyedia konfigurasi mampu untuk memuat ulang konfigurasi, yang langsung berpengaruh pada konfigurasi pengelogan. Misalnya, Penyedia Konfigurasi File, memuat ulang konfigurasi pengelogan secara default. Jika konfigurasi diubah dalam kode saat aplikasi sedang berjalan, aplikasi dapat memanggil IConfigurationRoot.Reload untuk memperbarui konfigurasi pengelogan aplikasi.

Bagaimana aturan pemfilteran diterapkan

Saat objek ILogger<TCategoryName> dibuat, objek ILoggerFactory memilih satu aturan per penyedia untuk diterapkan ke pencatat tersebut. Semua pesan yang ditulis oleh instans ILogger difilter berdasarkan aturan yang dipilih. Aturan paling spesifik untuk setiap pasangan penyedia dan kategori dipilih dari aturan yang tersedia.

Algoritma berikut digunakan untuk setiap penyedia saat ILogger dibuat untuk kategori tertentu:

• Pilih semua aturan yang cocok dengan penyedia atau aliasnya. Jika tidak ditemukan kecocokan, pilih semua aturan yang penyedianya kosong.
• Dari hasil langkah sebelumnya, pilih aturan dengan awalan kategori yang cocok terpanjang. Jika tidak ada kecocokan yang ditemukan, pilih semua aturan yang tidak menentukan kategori.
• Jika beberapa aturan dipilih, ambil yang terakhir.
• Jika tidak ada aturan yang dipilih, gunakan MinimumLevel.

ILogger dan ILoggerFactory

Antarmuka ILogger<TCategoryName> dan implementasi ILoggerFactory disertakan dalam .NET SDK. Mereka juga tersedia dalam paket NuGet berikut:

• Antarmuka berada dalam Microsoft.Extensions.Logging.Abstractions paket NuGet.
• Implementasi default ada dalam Microsoft.Extensions.Logging paket NuGet.

Catat pengecualian

Metode logger memiliki beberapa overload yang menerima parameter exception:

try
{
   ...

   throw new Exception("Test exception");
}
catch (Exception ex)
{
    Logger.LogWarning(LogEvent.GetItemNotFound, ex, "Test exception at {DT}", 
        DateTime.UtcNow);
}

Pengelogan pengecualian sifatnya khusus untuk penyedia.

Tingkat log default

Jika tingkat log default tidak diatur secara eksplisit, tingkat log defaultnya adalah Information.

Jika tingkat log default tidak diatur dalam konfigurasi, maka dapat diatur dengan LoggingBuilderExtensions.SetMinimumLevel. Contoh berikut mengatur tingkat Warning sebagai tingkat logging default.

var builder = WebApplication.CreateBuilder();

builder.Logging.SetMinimumLevel(LogLevel.Warning);

Sebaiknya atur tingkat log default minimum dalam konfigurasi, bukan dalam kode C#.

Fungsi filter

Fungsi filter dipanggil untuk semua penyedia dan kategori yang tidak memiliki aturan yang ditetapkan untuk mereka berdasarkan konfigurasi atau kode. Contoh berikut menampilkan log konsol ketika kategori berisi Page atau Microsoft dan tingkat log adalah Information atau lebih tinggi:

var builder = WebApplication.CreateBuilder();

builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider is not null && category is not null)
    {
        return provider.Contains("ConsoleLoggerProvider")
            && (category.Contains("Page") || category.Contains("Microsoft"))
            && logLevel >= LogLevel.Information;
    }

    return false;
});

Sebaiknya tentukan tingkat log dalam konfigurasi dan bukan dalam kode dengan fungsi filter.

Kategori ASP.NET Core

Tabel berikut berisi beberapa kategori pengelogan yang digunakan oleh ASP.NET Core.

Category	Notes
Microsoft.AspNetCore	Diagnostik umum untuk ASP.NET Core.
Microsoft.AspNetCore.DataProtection	Kunci perlindungan data mana yang dipertimbangkan, ditemukan, dan digunakan.
Microsoft.AspNetCore.HostFiltering	Host diizinkan.
Microsoft.AspNetCore.Hosting	Waktu yang diperlukan untuk menyelesaikan permintaan HTTP dan jam berapa dimulainya. Rakitan startup hosting mana yang dimuat.
Microsoft.AspNetCore.Mvc	MVC dan diagnostik Razor. Pengikatan model, eksekusi filter, kompilasi tampilan, dan pemilihan tindakan.
Microsoft.AspNetCore.Routing	Informasi pencocokan rute.
Microsoft.AspNetCore.Server	Respons koneksi dimulai, berhenti, dan tetap aktif. Informasi sertifikat HTTPS.
Microsoft.AspNetCore.StaticFiles	File dilayani.

Untuk mempelajari lebih banyak kategori menggunakan pencatat Console , atur appsettings.Development.json dalam aplikasi pengujian:

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

Warning

Setel ulang konfigurasi pencatatan ke tingkat sebelumnya di appsettings.Development.json setelah mempelajari keluaran logger Console.

Untuk daftar kategori Kerangka Kerja Entitas, lihat Pengelogan Sederhana: Kategori pesan (EF Core dokumentasi).

Ruang lingkup log

Sebuah lingkup dapat mengelompokkan sekumpulan operasi logis. Pengelompokan ini dapat digunakan untuk melampirkan data yang sama ke setiap log yang dibuat sebagai bagian dari kumpulan. Misalnya, setiap log yang dibuat sebagai bagian dari pemrosesan transaksi dapat menyertakan ID transaksi.

Cakupan:

• Merupakan tipe IDisposable yang dikembalikan oleh metode BeginScope.
• Bertahan hingga dibuang.

Penyedia berikut mendukung cakupan:

• Console
• AzureAppServicesFile dan AzureAppServicesBlob

Gunakan scope dengan membungkus panggilan logger dalam blok using:

public async Task<TodoItem> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();

    using (Logger.BeginScope(new List<KeyValuePair<string, object>>
    {
        new("TransactionId", transactionId),
    }))
    {
        Logger.LogInformation(LogEvent.GetItem, "Getting item {Id}", id);

        todoItem = await TodoItemsService.FindAsync(id);

        if (todoItem == null)
        {
            Logger.LogWarning(LogEvent.GetItemNotFound, "Get({Id}) NOT FOUND", id);

            return NotFound();
        }
    }

    return todoItem;
}

Penyedia log bawaan

ASP.NET Core mencakup penyedia pengelogan berikut:

• Console
• Debug
• EventSource
• Windows EventLog

Penyedia pengelogan berikut disediakan oleh Microsoft, tetapi bukan sebagai bagian dari kerangka kerja bersama .NET. Mereka harus diinstal sebagai paket NuGet tambahan yang ditambahkan ke aplikasi.

• AzureAppServicesFile dan AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core tidak menyertakan penyedia pengelogan untuk menulis log ke file. Untuk menulis log ke file dari aplikasi ASP.NET Core, pertimbangkan untuk menggunakan penyedia pengelogan pihak ketiga.

Untuk informasi tentang pencatatan log stdout dan penelusuran kesalahan dengan ASP.NET Core Module, lihat Memecahkan masalah ASP.NET Core di Azure App Service dan IIS dan ASP.NET Core Module (ANCM) untuk IIS.

Console

Penyedia Console mencatat output ke konsol. Untuk informasi selengkapnya tentang menampilkan Console log dalam pengembangan, lihat bagian Output logging.

Debug

Penyedia Debug menulis output log dengan menggunakan kelas System.Diagnostics.Debug. Pemanggilan ke System.Diagnostics.Debug.WriteLine menulis ke penyedia Debug.

Di Linux, lokasi log penyedia Debug bergantung pada distribusi dan mungkin salah satu dari berikut ini:

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

EventSource

Penyedia EventSource menulis ke sumber peristiwa lintas platform dengan nama Microsoft-Extensions-Logging. Di Windows, penyedia menggunakan ETW.

pengerjaan alat dotnet-trace

dotnet-trace adalah alat global CLI lintas platform yang memungkinkan pengumpulan jejak .NET dari proses yang sedang berjalan. Alat ini mengumpulkan data penyedia Microsoft.Extensions.Logging.EventSource menggunakan LoggingEventSource.

Untuk petunjuk penginstalan, lihat dotnet-trace.

Gunakan alat dotnet-trace untuk mengumpulkan jejak dari aplikasi:

1. Jalankan aplikasi dengan perintah dotnet run.

2. Tentukan pengidentifikasi proses (PID) aplikasi .NET:

   dotnet-trace ps
   

   Temukan PID untuk proses yang memiliki nama yang sama dengan rakitan aplikasi.

3. Jalankan perintah dotnet-trace.

   Sintaks perintah umum:

   • {PID}: Pengidentifikasi proses
   • {KEYWORD}:Kata kunci
   • {PROVIDER LEVEL}: Tingkat penyedia
   • {LOGGER CATEGORY ...}: Kategori pencatat
   • {CATEGORY LEVEL ...}: Tingkat kategori

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

   Saat menggunakan shell perintah PowerShell, apit nilai --providers dalam tanda kutip tunggal ('):

   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}\"'
   

   Pada platform non-Windows, tambahkan opsi -f speedscope untuk mengubah format file jejak output menjadi speedscope.

   Tabel berikut mendefinisikan kata kunci ({KEYWORD} pengganti sementara).

   Keyword	Description
   1	Catat peristiwa meta tentang LoggingEventSource. Tidak mencatat peristiwa dari ILogger.
   2	Mengaktifkan peristiwa Message saat ILogger.Log() dipanggil. Memberikan informasi dengan cara terprogram (tidak diformat).
   4	Mengaktifkan peristiwa FormatMessage saat ILogger.Log() dipanggil. Menyediakan informasi versi string yang diformat.
   8	Mengaktifkan peristiwa MessageJson saat ILogger.Log() dipanggil. Menyediakan representasi JSON dari argumen.

   Tabel berikut menentukan tingkat penyedia.

   Tingkat Penyedia	Description
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   Penguraian untuk tingkat kategori dapat berupa string atau angka, seperti yang ditunjukkan dalam tabel berikut.

   Kategori bernama “Nilai”	Nilai numerik
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   Tingkat penyedia dan tingkat kategori:

   • Berada dalam urutan terbalik.
   • Tidak semua konstanta string identik.

   Jika tidak FilterSpecs ditentukan, EventSourceLogger implementasi mencoba mengonversi tingkat penyedia ke tingkat kategori dan menerapkannya ke semua kategori.

   Tingkat Penyedia	Tingkat Kategori
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Jika FilterSpecs disediakan, kategori apa pun yang disertakan dalam daftar menggunakan tingkat kategori yang dikodekan di sana, semua kategori lainnya difilter.

   Contoh berikut mengasumsikan:

   • Aplikasi sedang berjalan dan memanggil Logger.LogDebug("12345").
   • ID proses (PID) diatur melalui set PID=12345, di mana 12345 adalah PID aktual.

   Pertimbangkan perintah berikut:

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

   Perintah sebelumnya:

   • Merekam pesan debug.
   • Tidak menerapkan FilterSpecs.
   • Menentukan tingkat 5 yang memetakan kategori Debug.

   Pertimbangkan perintah berikut:

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

   Perintah sebelumnya:

   • Tidak mengambil pesan debug karena tingkat kategori 5 adalah Critical.
   • Menyediakan FilterSpecs.

   Perintah berikut mengambil pesan debug karena kategori tingkat 1 menentukan Debug:

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

   Perintah berikut menangkap pesan debug karena kategori menentukan Debug:

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

   FilterSpecs entri untuk kategori pencatat dan tingkat kategori mewakili kondisi pemfilteran log tambahan. Pisahkan entri FilterSpecs dengan karakter titik koma ;.

   Contoh penggunaan baris perintah Windows:

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

   Perintah sebelumnya mengaktifkan:

   • PenyediaEventSource untuk menghasilkan string berformat (4) untuk kesalahan (2).
   • Pengelogan Microsoft.AspNetCore.Hosting di tingkat pengelogan Information (4).

4. dotnet-trace Hentikan alat dengan menekan tombol Enter atau Ctrl+C.

   Jejak disimpan dengan nama trace.nettrace di folder tempat perintah dotnet-trace dijalankan.

5. Buka jejak dengan Perfview. Buka file trace.nettrace dan jelajahi peristiwa pelacakan.

Jika aplikasi tidak membangun host dengan WebApplication.CreateBuilder, tambahkan EventSource penyedia ke konfigurasi pengelogan aplikasi.

Untuk informasi selengkapnya, lihat:

• Pelacakan perangkat analisis performa (dotnet-trace) (dokumentasi .NET)
• Pelacakan utilitas analisis kinerja (dotnet-trace) (dotnet/diagnostics dokumentasi repositori GitHub)
• LoggingEventSource
• EventLevel
• Perfview untuk melihat EventSource pelacakan

Perfview

Gunakan utilitas PerfView untuk mengumpulkan dan melihat log. Ada alat lain untuk melihat log ETW, tetapi PerfView memberikan pengalaman terbaik untuk bekerja dengan peristiwa ETW yang dipancarkan oleh ASP.NET Core.

Untuk mengonfigurasi PerfView agar mengumpulkan peristiwa yang dicatat oleh penyedia ini, tambahkan string *Microsoft-Extensions-Logging ke daftar Penyedia Tambahan. Jangan lewatkan * pada awal string.

Windows EventLog

Penyedia Windows EventLog mengirim output log ke Log Peristiwa Windows. Tidak seperti penyedia lain, penyedia EventLog tidak mewarisi pengaturan bukan penyedia yang default. Jika pengaturan log EventLog tidak ditentukan, pengaturan defaultnya adalah LogLevel.Warning.

Untuk mencatat peristiwa yang lebih rendah dari LogLevel.Warning, atur tingkat log secara eksplisit. Contoh berikut mengatur tingkat log bawaan untuk log peristiwa ke LogLevel.Information:

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

Overload AddEventLog dapat meneruskan EventLogSettings. Jika null atau tidak ditentukan, pengaturan bawaan berikut akan digunakan:

• LogName: "Application"
• SourceName: ".NET Runtime"
• MachineName: Nama komputer lokal yang digunakan.

Kode berikut mengubah SourceName dari nilai default menjadi ".NET Runtime" "CustomLogs":

var builder = WebApplication.CreateBuilder();

builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "CustomLogs";
});

Saat aplikasi memanggil kelebihan beban dengan AddEventLog, instans EventLogSettingsEventLogLoggerProvider baru dibuat dengan pengaturan yang disediakan. Jika sudah ada instans yang EventLogLoggerProvider terdaftar, yang terjadi jika aplikasi tidak memanggil ClearProviders untuk menghapus semua ILoggerProvider instans, pengaturan baru tidak menggantikan yang sudah ada. Jika Anda ingin memastikan bahwa EventLogSettings digunakan, hubungi ClearProviders sebelum memanggil AddEventLog.

Azure App Service

Paket Microsoft.Extensions.Logging.AzureAppServices penyedia NuGet merekam log ke dalam file teks di dalam sistem file dari aplikasi Azure App Service dan ke penyimpanan blob pada akun Azure Storage. Penyedia hanya mencatat saat proyek berjalan di lingkungan Azure.

Paket penyedia tidak disertakan dalam kerangka kerja bersama. Untuk menggunakan penyedia, tambahkan paket penyedia ke proyek.

Untuk mengonfigurasi pengaturan penyedia, gunakan AzureFileLoggerOptions dan AzureBlobLoggerOptions, seperti yang ditunjukkan pada contoh berikut:

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

Saat disebarkan ke Azure App Service, aplikasi menggunakan pengaturan di bagian Log App Service pada halaman App Service di portal Azure. Saat pengaturan berikut diperbarui, perubahan akan langsung berlaku tanpa memerlukan mulai ulang atau penyebaran ulang aplikasi.

• Pencatatan Log Aplikasi (Sistem Berkas)
• Pencatatan Log Aplikasi (Blob)

Lokasi default untuk file log adalah D:\home\LogFiles\Application. Batas ukuran file default adalah 10 MB, dan jumlah maksimum default file yang dipertahankan adalah dua file.

Streaming log di Azure

Azure log streaming mendukung melihat aktivitas log secara real time dari:

• Server aplikasi
• Server web
• Pelacakan permintaan gagal

Untuk mengonfigurasi Azure log streaming:

• Buka halaman Log App Service dari halaman portal aplikasi.
• Atur Pengelogan Aplikasi (Filesystem) ke Aktif.
• Pilih Tingkat log. Pengaturan ini hanya berlaku untuk Azure log streaming.

Buka halaman Aliran Log untuk melihat log. Pesan log dicatat melalui antarmuka ILogger.

wawasan Azure Application

Application Insights adalah layanan yang memantau aplikasi web dan menyediakan alat untuk mengkueri dan menganalisis data telemetri. Jika menggunakan penyedia ini, Anda dapat membuat kueri dan menganalisis log menggunakan alat Application Insights.

Paket NuGet dari penyedia menulis log ke Azure Application Insights. Penyedia pengelogan disertakan sebagai dependensi dari Microsoft.ApplicationInsights.AspNetCore paket NuGet, yang merupakan paket yang menyediakan semua telemetri yang tersedia untuk ASP.NET Core. Jika Anda menggunakan Microsoft.ApplicationInsights.AspNetCore paket NuGet, Anda tidak diharuskan menginstal Microsoft.Extensions.Logging.ApplicationInsights paket penyedia.

Note

Paket Microsoft.ApplicationInsights.Web NuGet adalah untuk ASP.NET 4.x, bukan ASP.NET Core, dan tidak boleh digunakan dalam aplikasi ASP.NET Core.

Untuk informasi selengkapnya, lihat sumber daya berikut:

• Gambaran umum Application Insights
• Application Insights untuk aplikasi ASP.NET Core: Mulai di sini jika Anda ingin mengimplementasikan rangkaian lengkap dari telemetri Application Insights bersama dengan pengelogan.
• ApplicationInsightsLoggerProvider untuk log .NET ILogger: Mulai di sini jika Anda ingin menerapkan penyedia pengelogan tanpa telemetri Application Insights lainnya.
• Adaptor pengelogan Application Insights
• Tutorial interaktif Memasang, mengonfigurasi, dan menginisialisasi Application Insights SDK tutorial interaktif.

Penyedia pengelogan pihak ketiga

Kerangka kerja pengelogan pihak ketiga yang berfungsi dengan ASP.NET Core:

• elmah.io (repositori GitHub)
• Gelf (repositori GitHub)
• JSNLog (repositori GitHub)
• KissLog.net (repositori GitHub)
• Log4Net (repositori GitHub)
• NLog (repositori GitHub)
• PLogger (repositori GitHub)
• Sentry (repositori GitHub)
• Serilog (repositori GitHub)
• Stackdriver (repositori GitHub)

Beberapa kerangka kerja pihak ketiga dapat melakukan pengelogan semantik, yang juga dikenal sebagai pengelogan terstruktur.

Menggunakan kerangka kerja pihak ketiga mirip dengan menggunakan salah satu penyedia bawaan:

1. Tambahkan paket NuGet penyedia ke proyek.
2. Panggil metode ekstensi ILoggerFactory yang disediakan oleh kerangka kerja pengelogan.

Untuk informasi selengkapnya, lihat dokumentasi penyedia. Penyedia pengelogan pihak ketiga tidak dimiliki, dikelola, atau didukung oleh Microsoft.

Pengelogan aplikasi konsol non-host

Untuk pengelogan di aplikasi konsol tanpa Host Generik, lihat Pengelogan di C# dan .NET. Untuk contoh tambahan, lihat aplikasi sampel Tugas Latar Belakang, yang dicakup oleh tugas Latar Belakang dengan layanan yang dihosting di ASP.NET Core.

Tidak ada metode pencatat asinkron

Pengelogan harus dilakukan dengan sangat cepat sehingga tidak sebanding dengan biaya performa dari kode asinkron. Jika penyimpanan data log lambat, jangan menulis langsung ke sana. Pertimbangkan untuk menulis pesan log ke penyimpanan cepat pada awalnya, lalu pindahkan log ke penyimpanan data yang lebih lambat nanti. Misalnya, jangan menulis pesan log langsung ke penyimpanan data SQL Server dalam Log metode karena Log metodenya sinkron. Sebagai gantinya, secara sinkron menambahkan pesan log ke antrean dalam memori dan meminta pekerja latar belakang menarik pesan keluar dari antrean untuk mendorong data ke SQL Server secara asinkron. Untuk informasi lebih lanjut, lihat Panduan tentang cara mencatat ke antrean pesan untuk penyimpanan data yang lambat (dotnet/AspNetCore.Docs #11801).

Menerapkan aturan filter log dalam kode

Pendekatan yang disukai untuk mengatur aturan filter log adalah dengan konfigurasi aplikasi.

Contoh berikut menunjukkan cara mendaftarkan aturan filter dalam kode dengan memanggil AddFilter pada WebApplicationBuilder.Logging:

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

Dalam contoh sebelumnya:

• Filter pertama menentukan:

  • Aturan pemfilteran log untuk semua penyedia karena tidak ada penyedia spesifik yang dikonfigurasi.
  • Semua kategori dimulai dengan "System".
  • Tingkat log Debug dan lebih tinggi.

• PenyediaDebug (DebugLoggerProvider) menentukan:

  • Semua kategori dimulai dengan "Microsoft".
  • Tingkat log Information dan lebih tinggi.

• PenyediaConsole (ConsoleLoggerProvider) menentukan:

  • Semua kategori dimulai dengan "Microsoft".
  • Tingkat log Trace dan lebih tinggi.

Tentukan konteks pelacakan untuk ruang lingkup log

Pustaka pengelogan secara implisit membuat objek cakupan dengan ActivityTrackingOptions. Bidang berikut menunjukkan opsi (ActivityTrackingOptions):

• SpanId
• TraceId
• ParentId
• Baggage
• Tags

SpanId, TraceId, ParentId diaktifkan secara default.

Dalam contoh berikut, hanya SpanId dan TraceId yang ditentukan:

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(options =>
{
    options.IncludeScopes = true;
});

builder.Logging.Configure(options =>
{
    options.ActivityTrackingOptions = 
        ActivityTrackingOptions.SpanId | ActivityTrackingOptions.TraceId;
});

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Jika header permintaan HTTP spesifikasi W3C Trace Context diatur:

• ParentId Dalam cakupan log memperlihatkan parent-id dari header terikattraceparent.
• SpanId di cakupan log menunjukkan pembaruan parent-id untuk langkah/rentang keluar berikutnya.

Untuk informasi lebih lanjut, lihat Mengubah Bidang traceparent.

Membuat pencatat kustom

Untuk membuat pencatat kustom, lihat Mengimplementasikan penyedia pengelogan kustom di .NET.

Mencatat laporan bug

Ajukan laporan bug pengelogan dotnet/runtime di masalah repositori GitHub.

Kategori log umum

Bagian ini menjelaskan kategori log umum yang terlihat di log aplikasi ASP.NET Core. Berikut ini bukan daftar komprehensif.

Microsoft.AspNetCore: Log dari komponen kerangka kerja ASP.NET Core, seperti hosting, perutean, dan middleware.

Authentication

• Microsoft.AspNetCore.Authentication: Log dari middleware autentikasi dan layanan, termasuk penanganan skema autentikasi.
• Microsoft.AspNetCore.Authentication.Cookies: Log khusus untuk autentikasi berbasis cookie.
• Microsoft.AspNetCore.Authentication.JwtBearer: Log yang terkait dengan JWT autentikasi token pembawa.
• Microsoft.AspNetCore.Authentication.OpenIdConnect: Log mengenai proses autentikasi OpenID Connect.
• Microsoft.AspNetCore.Authentication.OAuth: Log yang terkait dengan alur autentikasi dan otorisasi OAuth.

Authorization

• Microsoft.AspNetCore.Authorization: Log yang terkait dengan operasi otorisasi, termasuk evaluasi kebijakan dan pengambilan keputusan.
• Microsoft.AspNetCore.Authorization.DefaultAuthorizationService: Catatan tentang default.

Konfigurasi

• Microsoft.Extensions.Configuration.Json: Log dari kelas yang mendapatkan data konfigurasi dari file JSON.
• Microsoft.Extensions.Configuration.UserSecrets: Log yang terkait dengan memuat data konfigurasi rahasia pengguna.

CORS

• Microsoft.AspNetCore.Cors: Log yang terkait dengan middleware Cross-Origin Resource Sharing (CORS) serta kebijakan dan evaluasinya.
• Microsoft.AspNetCore.Cors.Infrastructure: Log mengenai konfigurasi dan penerapan kebijakan CORS.

Perlindungan Data:

• Microsoft.AspNetCore.DataProtection: Log dari sistem perlindungan data, termasuk manajemen kunci, operasi enkripsi, dan kunci mana yang dipertimbangkan, ditemukan, dan digunakan.
• Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager: Log khusus untuk manajer kunci XML, termasuk penyimpanan dan pengambilan kunci.

Diagnostics

• Microsoft.AspNetCore.Diagnostics: Catatan log tentang diagnostik dan middleware penanganan kesalahan, termasuk penanganan pengecualian dan halaman kode status.
• Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware: Log khusus untuk pemrosesan middleware halaman pengecualian pengembang.
• Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware: Log yang terkait dengan penanganan pengecualian dan pembuatan respons kesalahan.
• Microsoft.AspNetCore.Diagnostics.StatusCodePageMiddleware: Log yang terkait dengan middleware halaman kode status dan penanganan respons.

Pemfilteran Host

• Microsoft.AspNetCore.HostFiltering: Host yang diizinkan dan ditolak oleh middleware pemfilter host.
• Microsoft.AspNetCore.HostFiltering.HostFilteringMiddleware: Log yang terkait dengan middleware pemfilteran host, termasuk host yang diizinkan dan yang ditolak.
• Microsoft.AspNetCore.HostFiltering.HostFilteringOptions: Log mengenai opsi untuk middleware pemfilteran host.

Hosting

• Microsoft.AspNetCore.Hosting.Lifetime: Log yang terkait dengan siklus hidup host web, termasuk memulai dan menghentikan peristiwa.
• Microsoft.AspNetCore.Hosting.Diagnostics: Mencatat informasi diagnostik, seperti pengaktifan dan pematian aplikasi.
• Microsoft.AspNetCore.Hosting.RequestDelegate: Log yang terkait dengan penanganan permintaan HTTP oleh alur aplikasi.
• Microsoft.AspNetCore.Hosting.Internal.WebHost: Log internal dari host web, berguna untuk men-debug masalah terkait host.
• Microsoft.AspNetCore.Hosting.Internal.HostedServiceExecutor: Log mengenai eksekusi layanan yang dihosting oleh host web.

HTTP

• Microsoft.AspNetCore.Http.ConnectionLogging: Terkait dengan koneksi HTTP, termasuk pembentukan dan penghentian koneksi.
• Microsoft.AspNetCore.Http.DefaultHttpContext: Log yang terkait dengan pembuatan dan penggunaan instans HttpContext.
• Microsoft.AspNetCore.Http.Endpoints.EndpointMiddleware: Catatan tentang perutean titik akhir dan eksekusi middleware.
• Microsoft.AspNetCore.Http.Response: Log yang terkait dengan pemrosesan respons HTTP.

HTTPS

• Microsoft.AspNetCore.HttpsPolicy: Log dari middleware pengalihan HTTPS, penegakan kebijakan, dan HTTP Strict-Transport-Security (HSTS).
• Microsoft.AspNetCore.HttpsPolicy.HstsMiddleware: Log khusus untuk pemrosesan middleware HTTP Strict-Transport-Security (HSTS).
• Microsoft.AspNetCore.HttpsPolicy.HttpsRedirectionMiddleware: Log yang terkait dengan eksekusi middleware pengalihan HTTPS.
• Microsoft.AspNetCore.HttpsPolicy.HstsOptions: Log mengenai konfigurasi dan penerapan kebijakan HSTS.

Identity

• Microsoft.AspNetCore.Identity: Log dari kerangka kerja ASP.NET Core Identity , termasuk manajemen pengguna dan operasi identitas.
• Microsoft.AspNetCore.Identity.RoleManager: Log yang terkait dengan operasi manajemen peran.
• Microsoft.AspNetCore.Identity.UserManager: Log mengenai aktivitas manajemen pengguna dan peristiwa siklus hidup.

Kestrel

• Microsoft.AspNetCore.Server.Kestrel: Log dari Kestrel server web, mencakup penanganan koneksi dan pemrosesan permintaan.
• Microsoft.AspNetCore.Server.Kestrel.Core: Log yang terkait dengan operasi inti Kestrel , seperti konfigurasi dan manajemen sumber daya.
• Microsoft.AspNetCore.Server.Kestrel.Transport: Log khusus untuk lapisan transportasi jaringan yang digunakan oleh Kestrel.

Penebangan kayu

• Microsoft.Extensions.Logging: Log dari API ekstensi pengelogan.
• Microsoft.Extensions.Logging.Console: Log khusus untuk pencatat log Konsol.

MVC

• Microsoft.AspNetCore.Mvc: Log umum dari komponen kerangka kerja MVC, termasuk pengendali dan eksekusi aksi.
• Microsoft.AspNetCore.Mvc.Infrastructure: Log yang terkait dengan infrastruktur dan layanan dukungan untuk MVC, seperti pengikatan model dan filter tindakan.
• Microsoft.AspNetCore.Mvc.ModelBinding: Log mengenai operasi pengikatan model dan validasi data.
• Microsoft.AspNetCore.Mvc.Filters: Log tentang eksekusi filter tindakan dan alur filter.
• Microsoft.AspNetCore.Mvc.Razor: Log khusus untuk perenderan dan kompilasi tampilan Razor.
• Microsoft.AspNetCore.Mvc.ViewFeatures: Log mengenai penyajian tampilan dan fitur terkait seperti komponen tampilan dan pembantu tag.

Pengaturan Rute

• Microsoft.AspNetCore.Routing.EndpointMiddleware: Log yang terkait dengan perutean permintaan HTTP ke titik akhir.
• Microsoft.AspNetCore.Routing.EndpointRoutingMiddleware: Log tentang permintaan penanganan middleware perutean titik akhir.
• Microsoft.AspNetCore.Routing.Matching.DataSourceDependentMatcher: Log mengenai pencocokan rute dan pemilihan titik akhir.
• Microsoft.AspNetCore.Routing.Matching.DfaMatcher: Log yang khusus berkaitan dengan pencocokan perutean DFA (Deterministic Finite Automaton).

SignalR

• Microsoft.AspNetCore.SignalR: Log dari SignalR kerangka kerja, termasuk koneksi hub dan penanganan pesan.
• Microsoft.AspNetCore.SignalR.Hub: Log khusus untuk pemanggilan hub dan pengiriman pesan.
• Microsoft.AspNetCore.SignalR.Transports: Log yang terkait dengan mekanisme transportasi yang digunakan oleh SignalR.

Berkas statis

• Microsoft.AspNetCore.StaticFiles: Catatan dari middleware berkas statis, termasuk penyajian berkas dan operasi cache.
• Microsoft.AspNetCore.StaticFiles.StaticFileMiddleware: Log yang terkait dengan eksekusi middleware file statis dan penanganan respons file.

Sumber daya tambahan

• ASP.NET Core Blazor pengelogan
• Meningkatkan performa pengelogan dengan generator sumber
• Di balik [LogProperties] dan generator kode sumber pencatatan log telemetri yang baru
• Microsoft.Extensions.Logging sumber referensi (dotnet/runtime) repositori GitHub
• Pencatatan log berperforma tinggi
• Melihat atau mengunduh kode sampel (cara mengunduh)