Pengelogan di .NET Core dan ASP.NET Core

Oleh Kirk Larkin, Juergen Gutsch, dan Rick Anderson

Topik ini menjelaskan pengelogan di .NET karena berlaku untuk aplikasi ASP.NET Core. Untuk informasi terperinci tentang pengelogan di .NET, lihat Pengelogan di .NET. Untuk informasi selengkapnya tentang pengelogan di Blazor aplikasi, lihat pengelogan ASP.NET CoreBlazor.

Penyedia pengelogan

Penyedia pengelogan menyimpan log, kecuali untuk Console penyedia yang menampilkan log. Misalnya, penyedia Azure Application Insights menyimpan log di Azure Application Insights. Beberapa penyedia dapat diaktifkan.

Templat aplikasi web ASP.NET Core default:

• Gunakan Host Generik.
• Panggil WebApplication.CreateBuilder, yang menambahkan penyedia pengelogan berikut:
  • Konsol
  • Debug
  • EventSource
  • EventLog: Hanya Windows

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

Kode sebelumnya menunjukkan file yang Program.cs dibuat dengan templat aplikasi web ASP.NET Core. Beberapa bagian berikutnya menyediakan sampel berdasarkan templat aplikasi web ASP.NET Core, yang menggunakan Host Generik.

Kode berikut mengambil alih kumpulan penyedia pengelogan default yang ditambahkan oleh 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();

Atau, kode pengelogan sebelumnya dapat ditulis sebagai berikut:

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

Untuk penyedia tambahan, lihat:

• Penyedia pengelogan bawaan
• Penyedia pengelogan pihak ketiga.

Membuat log

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

Lihat contoh berikut:

• Membuat pencatat, ILogger<AboutModel>, yang menggunakan kategori log dari nama jenis AboutModelyang sepenuhnya memenuhi syarat. Kategori log adalah string yang terkait dengan setiap log.
• LogInformation Panggilan untuk masuk ke tingkat .Information Tingkat Log menunjukkan tingkat keparahan peristiwa yang dicatat.

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

Tingkat dan kategori dijelaskan secara lebih rinci nanti dalam dokumen ini.

Untuk informasi tentang Blazor, lihat pengelogan ASP.NET CoreBlazor.

Mengonfigurasi pengelogan

Konfigurasi pengelogan appsettings.{ENVIRONMENT}.json umumnya disediakan oleh bagian Logging file, di mana {ENVIRONMENT} tempat penampung adalah lingkungan. File berikut appsettings.Development.json dihasilkan oleh templat aplikasi web ASP.NET Core:

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

Di ON sebelumnya JS:

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

Properti Logging dapat memiliki LogLevel properti penyedia log dan . LogLevel menentukan tingkat minimum yang akan dicatat untuk kategori yang dipilih. Dalam ON sebelumnya JS, Information dan Warning tingkat log ditentukan. LogLevel menunjukkan tingkat keparahan log dan berkisar antara 0 hingga 6:

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

LogLevel Ketika ditentukan, pengelogan diaktifkan untuk pesan pada tingkat yang ditentukan dan yang lebih tinggi. Dalam ON sebelumnya JS, Default kategori dicatat dan Information lebih tinggi. Misalnya, Informationpesan , Warning, Error, dan Critical dicatat. Jika tidak LogLevel ditentukan, pengelogan default ke Information tingkat . Untuk informasi selengkapnya, lihat Tingkat log.

Properti penyedia dapat menentukan LogLevel properti . LogLevel di bawah penyedia menentukan tingkat untuk mencatat penyedia tersebut, dan mengambil alih pengaturan log non-penyedia. Pertimbangkan file berikut appsettings.json :

{
  "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 dalam Logging.{PROVIDER NAME}.LogLevel mengesampingkan pengaturan di Logging.LogLevel, di mana {PROVIDER NAME} tempat penampung adalah nama penyedia. Dalam ON sebelumnya JS, Debug tingkat log default penyedia diatur ke Information:

Logging:Debug:LogLevel:Default:Information

Pengaturan sebelumnya menentukan Information tingkat log untuk setiap Logging:Debug: kategori kecuali Microsoft.Hosting. Saat kategori tertentu tercantum, kategori tertentu akan mengambil alih kategori default. Di ON sebelumnya JS, Logging:Debug:LogLevel kategori "Microsoft.Hosting" dan "Default" ambil alih pengaturan di Logging:LogLevel.

Tingkat log minimum dapat ditentukan untuk salah satu dari:

• Penyedia tertentu: Misalnya, Logging:EventSource:LogLevel:Default:Information
• Kategori tertentu: Misalnya, Logging:LogLevel:Microsoft:Warning
• Semua penyedia dan semua kategori: Logging:LogLevel:Default:Warning

Log apa pun di bawah tingkat minimum tidak:

• Diteruskan ke penyedia.
• Dicatat atau ditampilkan.

Untuk menekan 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 mereka diaktifkan. Untuk informasi selengkapnya, lihat cakupan log.

File berikut berisi appsettings.json 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 dalam Logging.{PROVIDER NAME}.LogLevel mengesampingkan pengaturan di Logging.LogLevel, di mana {PROVIDER NAME} tempat penampung adalah nama penyedia. Misalnya, tingkat dalam Debug.LogLevel.Default mengambil alih tingkat di LogLevel.Default.
• Setiap alias penyedia default digunakan. Setiap penyedia mendefinisikan alias yang dapat digunakan dalam konfigurasi sebagai pengganti nama jenis yang sepenuhnya memenuhi syarat. Alias penyedia bawaan adalah:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Log di Program.cs

Contoh berikut memanggil Builder.WebApplication.Logger masuk Program.cs dan 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 berikut memanggil AddConsole masuk Program.cs dan mencatat /Test titik akhir:

var builder = WebApplication.CreateBuilder(args);

var logger = LoggerFactory.Create(config =>
{
    config.AddConsole();
}).CreateLogger("Program");

var app = builder.Build();

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

app.MapGet("/Test", async context =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await context.Response.WriteAsync("Testing");
});

app.Run();

Contoh berikut memanggil AddSimpleConsole di Program.cs, menonaktifkan output warna, dan mencatat /Test titik akhir:

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);
});

var logger = loggerFactory.CreateLogger<Program>();

var app = builder.Build();

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

app.MapGet("/Test", async context =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await context.Response.WriteAsync("Testing");
});

app.Run();

Mengatur tingkat log menurut baris perintah, variabel lingkungan, dan konfigurasi lainnya

Tingkat log dapat diatur oleh salah satu penyedia konfigurasi.

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

• Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ adalah.
• Digantikan secara otomatis oleh :

Perintah berikut:

• Atur kunci Logging:LogLevel:Microsoft lingkungan ke nilai Information pada Windows.
• Uji pengaturan saat menggunakan aplikasi yang dibuat dengan templat aplikasi web ASP.NET Core. Perintah dotnet run harus dijalankan di direktori proyek setelah menggunakan set.

set Logging__LogLevel__Microsoft=Information
dotnet run

Pengaturan lingkungan sebelumnya:

• Hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat mereka diatur.
• Tidak dibaca oleh browser yang diluncurkan dengan Visual Studio.

Perintah setx berikut juga mengatur kunci dan nilai lingkungan di Windows. Tidak seperti set, setx pengaturan tetap ada. Sakelar /M mengatur variabel di lingkungan sistem. Jika /M tidak digunakan, variabel lingkungan pengguna diatur.

setx Logging__LogLevel__Microsoft Information /M

Pertimbangkan file berikut appsettings.json :

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

Perintah berikut mengatur konfigurasi sebelumnya di lingkungan:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

• Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
• Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya, lihat Aplikasi Azure: Mengambil alih konfigurasi aplikasi menggunakan Portal Microsoft Azure.

Untuk informasi selengkapnya tentang mengatur nilai konfigurasi ASP.NET Core menggunakan variabel lingkungan, lihat variabel lingkungan. Untuk informasi tentang menggunakan sumber konfigurasi lain, termasuk baris perintah, Azure Key Vault, Azure App Configuration, format file lainnya, dan lainnya, lihat Konfigurasi di ASP.NET Core.

Bagaimana aturan pemfilteran diterapkan

ILogger<TCategoryName> Saat objek dibuat, ILoggerFactory objek memilih satu aturan per penyedia untuk diterapkan ke pencatat tersebut. Semua pesan yang ILogger ditulis oleh instans difilter berdasarkan aturan yang dipilih. Aturan paling spesifik untuk setiap penyedia dan pasangan 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 ada kecocokan yang ditemukan, pilih semua aturan dengan penyedia kosong.
• Dari hasil langkah sebelumnya, pilih aturan dengan awalan kategori yang paling cocok. Jika tidak ada kecocokan yang ditemukan, pilih semua aturan yang tidak menentukan kategori.
• Jika beberapa aturan dipilih, ambil aturan terakhir .
• Jika tidak ada aturan yang dipilih, gunakan MinimumLevel.

Output pengelogan dari dotnet run dan Visual Studio

Log yang dibuat dengan penyedia pengelogan default ditampilkan:

• Di Visual Studio
  • Di jendela output Debug saat penelusuran kesalahan.
  • Di jendela ASP.NET Core Web Server.
• Di jendela konsol saat aplikasi dijalankan dengan dotnet run.

Log yang dimulai dengan kategori "Microsoft" berasal dari kode kerangka kerja ASP.NET Core. ASP.NET Core dan kode aplikasi menggunakan API pengelogan dan penyedia yang sama.

Kategori log

ILogger Saat objek dibuat, kategori ditentukan. Kategori tersebut disertakan dengan setiap pesan log yang dibuat oleh instans .ILogger String kategori bersifat arbitrer, tetapi konvensinya adalah menggunakan nama kelas. Misalnya, dalam pengontrol nama mungkin ."TodoApi.Controllers.TodoController" Aplikasi web ASP.NET Core digunakan ILogger<T> untuk mendapatkan ILogger instans yang secara otomatis menggunakan nama T jenis yang sepenuhnya memenuhi syarat sebagai kategori:

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

Untuk menentukan kategori secara eksplisit, panggil 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.");
    }

Panggilan CreateLogger dengan nama tetap dapat berguna saat digunakan dalam beberapa metode sehingga peristiwa dapat diatur berdasarkan kategori.

ILogger<T> setara dengan panggilan CreateLogger dengan nama jenis yang sepenuhnya memenuhi syarat dari T.

Tingkat log

Tabel berikut mencantumkan LogLevel nilai, metode ekstensi kenyamanan Log{LogLevel} , dan penggunaan yang disarankan:

LogLevel	Nilai	Metode	Deskripsi
Trace	0	LogTrace	Berisi pesan yang paling rinci. Pesan-pesan ini mungkin berisi data aplikasi sensitif. Pesan ini dinonaktifkan secara default dan tidak boleh diaktifkan dalam produksi.
Debug	1	LogDebug	Untuk penelusuran kesalahan dan pengembangan. Gunakan dengan hati-hati dalam produksi karena volume yang tinggi.
Information	2	LogInformation	Melacak alur umum aplikasi. Mungkin memiliki nilai jangka panjang.
Warning	3	LogWarning	Untuk peristiwa abnormal atau tidak terduga. Biasanya menyertakan kesalahan atau kondisi yang tidak menyebabkan aplikasi gagal.
Error	4	LogError	Untuk kesalahan dan pengecualian yang tidak dapat ditangani. Pesan-pesan ini menunjukkan kegagalan dalam operasi atau permintaan saat ini, bukan kegagalan di seluruh aplikasi.
Critical	5	LogCritical	Untuk kegagalan yang membutuhkan perhatian segera. Contoh: skenario kehilangan data, kehabisan ruang disk.
None	6		Menentukan bahwa kategori pengelogan tidak boleh menulis pesan.

Dalam tabel sebelumnya, LogLevel dicantumkan dari tingkat keparahan terendah hingga tertinggi.

Parameter Log pertama metode, LogLevel, menunjukkan tingkat keparahan log. Daripada memanggil Log(LogLevel, ...), sebagian besar pengembang memanggil Log{LOG LEVEL} metode ekstensi, di mana {LOG LEVEL} tempat penampung adalah tingkat log. Misalnya, dua panggilan pengelogan berikut secara fungsional setara dan menghasilkan log yang sama:

[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 adalah ID peristiwa. MyLogEvents adalah bagian dari aplikasi sampel dan ditampilkan di bagian ID peristiwa Log .

MyDisplayRouteInfo dan ToCtxString disediakan oleh paket Rick.Docs.Samples.RouteInfo NuGet. Metode menampilkan Controller dan Razor Page merutekan informasi.

Kode berikut membuat Information dan Warning mencatat:

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

Dalam kode sebelumnya, parameter pertama Log{LOG LEVEL} ,MyLogEvents.GetItem adalah ID peristiwa Log. Parameter kedua adalah templat pesan dengan tempat penampung untuk nilai argumen yang disediakan oleh parameter metode yang tersisa. Parameter metode dijelaskan di bagian templat pesan nanti dalam dokumen ini.

Panggil metode yang sesuai Log{LOG LEVEL} untuk mengontrol berapa banyak output log yang ditulis ke media penyimpanan tertentu. Contohnya:

• Dalam produksi:
  • Pengelogan di Trace tingkat atau Information menghasilkan pesan log terperinci dalam volume tinggi. Untuk mengontrol biaya dan tidak melebihi batas penyimpanan data, catat Trace dan Information tingkatkan pesan ke penyimpanan data bervolume tinggi dengan biaya rendah. Pertimbangkan untuk Trace membatasi dan Information untuk kategori tertentu.
  • Pengelogan melalui WarningCritical tingkat harus menghasilkan beberapa pesan log.
    • Biaya dan batas penyimpanan biasanya tidak menjadi perhatian.
    • Beberapa log memungkinkan lebih banyak fleksibilitas dalam pilihan penyimpanan data.
• Dalam pengembangan:
  • Atur ke Warning.
  • Tambahkan Trace pesan atau Information saat memecahkan masalah. Untuk membatasi output, atur Trace atau Information hanya untuk kategori yang sedang diselidiki.

ASP.NET Core menulis log untuk peristiwa kerangka kerja. Misalnya, pertimbangkan output log untuk:

• Aplikasi Razor Pages yang dibuat dengan templat ASP.NET Core.
• Pengelogan diatur ke Logging:Console:LogLevel:Microsoft:Information.
• Navigasi ke Privacy halaman:

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

Set Logging:Console:LogLevel:Microsoft:InformationON berikut JS:

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

ID peristiwa log

Setiap log dapat menentukan ID peristiwa. Aplikasi sampel menggunakan MyLogEvents kelas untuk menentukan ID peristiwa:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

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

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

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

    return ItemToDTO(todoItem);
}

ID peristiwa mengaitkan serangkaian peristiwa. Misalnya, semua log yang terkait dengan menampilkan daftar item di halaman mungkin 1001.

Penyedia pengelogan dapat menyimpan ID peristiwa di bidang ID, dalam pesan pengelogan, atau tidak sama sekali. Penyedia Debug tidak menampilkan ID peristiwa. Penyedia konsol menampilkan ID peristiwa dalam tanda kurung setelah kategori:

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

Beberapa penyedia pengelogan menyimpan ID peristiwa di bidang , yang memungkinkan pemfilteran pada ID.

Templat pesan log

Setiap API log menggunakan templat pesan. Templat pesan dapat berisi tempat penampung tempat argumen disediakan. Gunakan nama untuk tempat penampung, bukan angka.

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

Urutan parameter, bukan nama tempat penampungnya, menentukan parameter mana yang digunakan untuk menyediakan nilai tempat penampung dalam pesan log. Dalam kode berikut, nama parameter di luar urutan di tempat penampung templat pesan:

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

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

Namun, parameter ditetapkan ke tempat penampung dalam urutan: apples, , pearsbananas. Pesan log mencerminkan urutan parameter:

Parameters: 1, 2, 3

Pendekatan ini memungkinkan penyedia pengelogan untuk menerapkan pengelogan semantik atau terstruktur. Argumen itu sendiri diteruskan ke sistem pengelogan, bukan hanya templat 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);

Misalnya, saat masuk ke Azure Table Storage:

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

Pengecualian log

Metode pencatat memiliki kelebihan beban yang mengambil parameter pengecualian:

[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 dan ToCtxString disediakan oleh paket Rick.Docs.Samples.RouteInfo NuGet. Metode menampilkan Controller dan Razor Page merutekan informasi.

Pengelogan pengecualian khusus untuk penyedia.

Tingkat log default

Jika tingkat log default tidak diatur, nilai tingkat log default adalah Information.

Misalnya, pertimbangkan aplikasi web berikut:

• Dibuat dengan templat aplikasi web ASP.NET.
• appsettings.json dan appsettings.Development.json dihapus atau diganti namanya.

Dengan penyiapan sebelumnya, menavigasi ke privasi atau halaman beranda menghasilkan banyak Tracepesan , Debug, dan Information dengan Microsoft dalam nama kategori.

Kode berikut menetapkan tingkat log default saat tingkat log default tidak diatur dalam konfigurasi:

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

Umumnya, tingkat log harus ditentukan dalam konfigurasi dan bukan kode.

Fungsi filter

Fungsi filter dipanggil untuk semua penyedia dan kategori yang tidak memiliki aturan yang ditetapkan untuknya berdasarkan konfigurasi atau kode:

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

Kode sebelumnya menampilkan log konsol saat kategori berisi Controller atau Microsoft dan tingkat Information log atau lebih tinggi.

Umumnya, tingkat log harus ditentukan dalam konfigurasi dan bukan kode.

kategori ASP.NET Core dan EF Core

Tabel berikut berisi beberapa kategori yang digunakan oleh ASP.NET Core dan Entity Framework Core, dengan catatan tentang log:

Kategori	Catatan
Microsoft.AspNetCore	Diagnostik Umum ASP.NET Core.
Microsoft.AspNetCore.DataProtection	Kunci mana yang dipertimbangkan, ditemukan, dan digunakan.
Microsoft.AspNetCore.HostFiltering	Host diizinkan.
Microsoft.AspNetCore.Hosting	Berapa lama waktu yang dibutuhkan permintaan HTTP untuk diselesaikan dan jam berapa permintaan tersebut dimulai. Rakitan startup hosting mana yang dimuat.
Microsoft.AspNetCore.Mvc	MVC dan Razor diagnostik. Pengikatan model, eksekusi filter, kompilasi tampilan, pemilihan tindakan.
Microsoft.AspNetCore.Routing	Merutekan informasi pencocokan.
Microsoft.AspNetCore.Server	Koneksi dimulai, berhenti, dan respons tetap hidup. Informasi sertifikat HTTPS.
Microsoft.AspNetCore.StaticFiles	File disajikan.
Microsoft.EntityFrameworkCore	Diagnostik Inti Kerangka Kerja Entitas Umum. Aktivitas dan konfigurasi database, deteksi perubahan, migrasi.

Untuk melihat kategori lainnya di jendela konsol, atur appsettings.Development.json ke yang berikut ini:

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

Cakupan log

Cakupan dapat mengelompokkan serangkaian operasi logis. Pengelompokan ini dapat digunakan untuk melampirkan data yang sama ke setiap log yang dibuat sebagai bagian dari set. Misalnya, setiap log yang dibuat sebagai bagian dari pemrosesan transaksi dapat menyertakan ID transaksi.

Cakupan:

• IDisposable Adalah jenis yang dikembalikan oleh BeginScope metode .
• Berlangsung sampai dibuang.

Penyedia berikut mendukung cakupan:

• Console
• AzureAppServicesFile dan AzureAppServicesBlob

Gunakan cakupan dengan membungkus panggilan pencatat dalam using blok:

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

Penyedia pengelogan bawaan

ASP.NET Core menyertakan penyedia pengelogan berikut sebagai bagian dari kerangka kerja bersama:

• Console
• Debug
• EventSource
• EventLog

Penyedia pengelogan berikut dikirim oleh Microsoft, tetapi bukan sebagai bagian dari kerangka kerja bersama. Mereka harus dipasang sebagai nuget tambahan.

• 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 stdout dan men-debug pengelogan dengan ASP.NET Core Module, lihat Memecahkan masalah ASP.NET Core pada Azure App Service dan IIS dan ASP.NET Core Module (ANCM) untuk IIS.

Konsol

Penyedia Console mencatat output ke konsol. Untuk informasi selengkapnya tentang melihat Console log dalam pengembangan, lihat Pengelogan output dari dotnet run dan Visual Studio.

Debug

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

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

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

Sumber Kejadian

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

alat pelacakan dotnet

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

Untuk petunjuk penginstalan, lihat dotnet-trace.

Gunakan alat dotnet trace untuk mengumpulkan jejak dari aplikasi:

1. Jalankan aplikasi dengan dotnet run perintah .

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

   dotnet trace ps
   

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

3. Jalankan perintah dotnet trace.

   Sintaks perintah umum:

   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, sertakan --providers nilai 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 -f speedscope opsi untuk mengubah format file pelacakan output menjadi speedscope.

   Tabel berikut mendefinisikan Kata Kunci:

   Kata kunci	Deskripsi
   1	Catat LoggingEventSourceperistiwa meta tentang . Tidak mencatat peristiwa dari ILogger.
   2	Message Mengaktifkan peristiwa saat ILogger.Log() dipanggil. Menyediakan informasi dengan cara terprogram (tidak diformat).
   4	FormatMessage Mengaktifkan peristiwa saat ILogger.Log() dipanggil. Menyediakan versi string informasi yang diformat.
   8	MessageJson Mengaktifkan peristiwa saat ILogger.Log() dipanggil. JSMenyediakan representasi ON dari argumen.

   Tabel berikut ini mencantumkan tingkat penyedia:

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

   Penguraian untuk tingkat kategori dapat berupa string atau angka:

   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.
   • Konstanta string tidak semuanya identik.

   Jika tidak ada FilterSpecs yang 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 lain difilter.

   Contoh berikut mengasumsikan:

   • Aplikasi sedang berjalan dan memanggil logger.LogDebug("12345").
   • ID proses (PID) telah 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:

   • Menangkap 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 kategori tingkat 5 adalah Critical.
   • FilterSpecsMenyediakan .

   Perintah berikut menangkap 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 {Logger Category} dan {Category Level} mewakili kondisi pemfilteran log tambahan. Pisahkan FilterSpecs entri dengan ; karakter titik koma.

   Contoh menggunakan shell perintah Windows:

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

   Perintah sebelumnya mengaktifkan:

   • Pencatat Sumber Peristiwa untuk menghasilkan string yang diformat (4) untuk kesalahan (2).
   • Microsoft.AspNetCore.Hosting pengelogan pada tingkat pengelogan Informational (4).

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

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

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

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

Untuk informasi selengkapnya, lihat:

• Pelacakan untuk utilitas analisis performa (dotnet-trace) (dokumentasi.NET Core)
• Melacak utilitas analisis performa (dotnet-trace) (dokumentasi repositori GitHub dotnet/diagnostik)
• LoggingEventSource
• EventLevel
• Perfview: Berguna untuk melihat jejak Sumber Peristiwa.

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 untuk mengumpulkan peristiwa yang dicatat oleh penyedia ini, tambahkan string *Microsoft-Extensions-Logging ke daftar Penyedia Tambahan . Jangan lewatkan * di awal string.

Windows EventLog

Penyedia EventLog mengirim output log ke Log Peristiwa Windows. Tidak seperti penyedia lain, EventLog penyedia tidak mewarisi pengaturan non-penyedia default. Jika EventLog pengaturan log tidak ditentukan, pengaturan tersebut default ke LogLevel.Warning.

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

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

AddEventLog kelebihan beban dapat melewati EventLogSettings. Jika null ditentukan atau tidak, pengaturan default berikut digunakan:

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

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

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

Azure App Service

Paket Microsoft.Extensions.Logging.AzureAppServices penyedia menulis log ke file teks dalam sistem file aplikasi Azure App Service dan penyimpanan blob di akun Azure Storage.

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 dalam 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 dari halaman App Service portal Azure. Saat pengaturan berikut diperbarui, perubahan segera berlaku tanpa memerlukan mulai ulang atau penyebaran ulang aplikasi.

• Pengelogan Aplikasi (Filesystem)
• Pengelogan Aplikasi (Blob)

Lokasi default untuk file log ada di D:\\home\\LogFiles\\Application folder , dan nama file default adalah diagnostics-yyyymmdd.txt. Batas ukuran file default adalah 10 MB, dan jumlah maksimum default file yang dipertahankan adalah 2. Nama blob default adalah {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Penyedia ini hanya mencatat ketika proyek berjalan di lingkungan Azure.

Streaming log Azure

Streaming log Azure mendukung penayangan aktivitas log secara real time dari:

• Server aplikasi
• Server web
• Pelacakan permintaan gagal

Untuk mengonfigurasi streaming log Azure:

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

Navigasi ke halaman Aliran Log untuk melihat log. Pesan yang dicatat dicatat dengan ILogger antarmuka.

Azure Application Insights

Paket Microsoft.Extensions.Logging.ApplicationInsights penyedia menulis log ke Azure Application Insights. Application Insights adalah layanan yang memantau aplikasi web dan menyediakan alat untuk mengkueri dan menganalisis data telemetri. Jika Anda menggunakan penyedia ini, Anda dapat mengkueri dan menganalisis log Anda dengan menggunakan alat Application Insights.

Penyedia pengelogan disertakan sebagai dependensi dari Microsoft.ApplicationInsights.AspNetCore, yang merupakan paket yang menyediakan semua telemetri yang tersedia untuk ASP.NET Core. Jika Anda menggunakan paket ini, Anda tidak perlu menginstal paket penyedia.

Paket Microsoft.ApplicationInsights.Web ini untuk ASP.NET 4.x, bukan ASP.NET Core.

Untuk informasi lebih lanjut, lihat sumber daya berikut ini:

• Ringkasan Application Insights
• Application Insights untuk aplikasi ASP.NET Core: Mulai di sini jika Anda ingin menerapkan berbagai telemetri Application Insights bersama dengan pengelogan.
• ApplicationInsightsLoggerProvider untuk log .NET Core ILogger: Mulai di sini jika Anda ingin menerapkan penyedia pengelogan tanpa telemetri Application Insights lainnya.
• Adaptor pengelogan Application Insights
• Menginstal, mengonfigurasi, dan menginisialisasi Application Insights SDK: Tutorial interaktif di situs Microsoft Learn.

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, juga dikenal sebagai pengelogan terstruktur.

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

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

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

Tidak ada metode pencatat asinkron

Pengelogan harus sangat cepat sehingga tidak sebanding dengan biaya performa kode asinkron. Jika penyimpanan data pengelogan lambat, jangan menulisnya secara langsung. Pertimbangkan untuk menulis pesan log ke penyimpanan cepat pada awalnya, lalu pindahkan ke penyimpanan lambat nanti. Misalnya, saat pengelogan ke SQL Server, jangan melakukannya langsung dalam Log metode , karena metodenya Log sinkron. Sebagai gantinya, tambahkan pesan log secara sinkron ke antrean dalam memori dan minta pekerja latar belakang menarik pesan keluar dari antrean untuk melakukan pekerjaan asinkron mendorong data ke SQL Server. Untuk informasi selengkapnya, lihat Panduan tentang cara masuk ke antrean pesan untuk penyimpanan data lambat (dotnet/AspNetCore.Docs #11801).

Mengubah tingkat log di aplikasi yang sedang berjalan

API Pengelogan tidak menyertakan skenario untuk mengubah tingkat log saat aplikasi sedang berjalan. Namun, beberapa penyedia konfigurasi mampu 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 berjalan, aplikasi dapat memanggil IConfigurationRoot.Reload untuk memperbarui konfigurasi pengelogan aplikasi.

ILogger dan ILoggerFactory

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

• Antarmuka berada di Microsoft.Extensions.Logging.Abstractions.
• Implementasi default ada di Microsoft.Extensions.Logging.

Menerapkan aturan filter log dalam kode

Pendekatan yang disukai untuk mengatur aturan filter log adalah dengan menggunakan Konfigurasi.

Contoh berikut menunjukkan cara mendaftarkan aturan filter dalam kode:

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)System menentukan kategori dan tingkat Debuglog . Filter diterapkan ke semua penyedia karena penyedia tertentu tidak dikonfigurasi.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) Menentukan:

• Penyedia Debug pengelogan.
• Tingkat Information log dan yang lebih tinggi.
• Semua kategori dimulai dengan "Microsoft".

Secara otomatis mencatat cakupan dengan SpanId, TraceId, ParentId, Baggage, dan Tags.

Pustaka pengelogan secara implisit membuat objek cakupan dengan SpanId, , TraceIdParentId,Baggage , dan Tags. Perilaku ini dikonfigurasi melalui 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;
      });
  });

traceparent Jika header permintaan http diatur, ParentId dalam lingkup log menunjukkan W3C parent-id dari header dalam batas traceparent dan SpanId dalam cakupan log menunjukkan yang diperbarui parent-id untuk langkah/rentang keluar berikutnya. Untuk informasi selengkapnya, lihat Bermutasi Bidang traceparent.

Membuat pencatat kustom

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

Sumber Daya Tambahan:

• Sumber Microsoft.Extensions.Logging di GitHub
• Lihat atau unduh kode sampel (cara mengunduh).
• Pengelogan berkinerja tinggi dengan LoggerMessage di ASP.NET Core
• Bug pengelogan harus dibuat di repositori dotnet/runtime GitHub.
• pengelogan ASP.NET Core Blazor

Oleh Kirk Larkin, Juergen Gutsch, dan Rick Anderson

Topik ini menjelaskan pengelogan di .NET seperti yang berlaku untuk aplikasi ASP.NET Core. Untuk informasi terperinci tentang pengelogan di .NET, lihat Pengelogan di .NET. Untuk informasi selengkapnya tentang pengelogan di Blazor aplikasi, lihat pengelogan ASP.NET CoreBlazor.

Lihat atau unduh kode sampel (cara mengunduh).

Penyedia pengelogan

Penyedia pengelogan menyimpan log, kecuali penyedia Console yang menampilkan log. Misalnya, penyedia Azure Application Insights menyimpan log di Azure Application Insights. Beberapa penyedia dapat diaktifkan.

Templat aplikasi web ASP.NET Core default:

• Gunakan Host Generik.
• Panggil CreateDefaultBuilder, yang menambahkan penyedia pengelogan berikut:
  • Konsol
  • Debug
  • EventSource
  • EventLog: Hanya Windows

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

Kode sebelumnya menunjukkan kelas yang Program dibuat dengan templat aplikasi web ASP.NET Core. Beberapa bagian berikutnya menyediakan sampel berdasarkan templat aplikasi web ASP.NET Core, yang menggunakan Host Generik. Aplikasi konsol non-host dibahas nanti dalam dokumen ini.

Untuk mengambil alih kumpulan penyedia pengelogan default yang ditambahkan oleh Host.CreateDefaultBuilder, panggil ClearProviders dan tambahkan penyedia pengelogan yang diperlukan. Misalnya, kode berikut:

• ClearProviders Panggilan untuk menghapus semua ILoggerProvider instans dari penyusun.
• Menambahkan penyedia pengelogan Konsol .

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

Untuk penyedia tambahan, lihat:

• Penyedia pengelogan bawaan
• Penyedia pengelogan pihak ketiga.

Membuat log

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

Lihat contoh berikut:

• Membuat pencatat, ILogger<AboutModel>, yang menggunakan kategori log dari nama jenis AboutModelyang sepenuhnya memenuhi syarat. Kategori log adalah string yang terkait dengan setiap log.
• LogInformation Panggilan untuk masuk ke tingkat .Information Tingkat Log menunjukkan tingkat keparahan peristiwa yang dicatat.

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

Tingkat dan kategori dijelaskan secara lebih rinci nanti dalam dokumen ini.

Untuk informasi tentang Blazor, lihat pengelogan ASP.NET CoreBlazor.

Membuat log di Utama dan Startup menunjukkan cara membuat log masuk Main dan Startup.

Mengonfigurasi pengelogan

Konfigurasi pengelogan umumnya disediakan oleh bagian Loggingappsettings.{Environment}.json file. File berikut appsettings.Development.json dihasilkan oleh templat aplikasi web ASP.NET Core:

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

Di ON sebelumnya JS:

• Kategori "Default", "Microsoft", dan "Microsoft.Hosting.Lifetime" ditentukan.
• Kategori "Microsoft" ini berlaku untuk semua kategori yang dimulai dengan "Microsoft". Misalnya, pengaturan ini berlaku untuk "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategori .
• Kategori "Microsoft" mencatat pada tingkat Warning log dan yang lebih tinggi.
• Kategori "Microsoft.Hosting.Lifetime" ini lebih spesifik daripada "Microsoft" kategori, sehingga "Microsoft.Hosting.Lifetime" log kategori di tingkat log "Informasi" dan yang lebih tinggi.
• Penyedia log tertentu tidak ditentukan, jadi LogLevel berlaku untuk semua penyedia pengelogan yang diaktifkan kecuali untuk Windows EventLog.

Properti Logging dapat memiliki LogLevel properti penyedia log dan . LogLevel menentukan tingkat minimum yang akan dicatat untuk kategori yang dipilih. Dalam ON sebelumnya JS, Information dan Warning tingkat log ditentukan. LogLevel menunjukkan tingkat keparahan log dan berkisar antara 0 hingga 6:

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

LogLevel Ketika ditentukan, pengelogan diaktifkan untuk pesan pada tingkat yang ditentukan dan yang lebih tinggi. Dalam ON sebelumnya JS, Default kategori dicatat dan Information lebih tinggi. Misalnya, Informationpesan , Warning, Error, dan Critical dicatat. Jika tidak LogLevel ditentukan, pengelogan default ke Information tingkat . Untuk informasi selengkapnya, lihat Tingkat log.

Properti penyedia dapat menentukan LogLevel properti . LogLevel di bawah penyedia menentukan tingkat untuk mencatat penyedia tersebut, dan mengambil alih pengaturan log non-penyedia. Pertimbangkan file berikut appsettings.json :

{
  "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 dalam Logging.{providername}.LogLevel mengesampingkan pengaturan di Logging.LogLevel. Dalam ON sebelumnya JS, Debug tingkat log default penyedia diatur ke Information:

Logging:Debug:LogLevel:Default:Information

Pengaturan sebelumnya menentukan Information tingkat log untuk setiap Logging:Debug: kategori kecuali Microsoft.Hosting. Saat kategori tertentu tercantum, kategori tertentu akan mengambil alih kategori default. Di ON sebelumnya JS, Logging:Debug:LogLevel kategori "Microsoft.Hosting" dan "Default" ambil alih pengaturan di Logging:LogLevel

Tingkat log minimum dapat ditentukan untuk salah satu dari:

• Penyedia tertentu: Misalnya, Logging:EventSource:LogLevel:Default:Information
• Kategori tertentu: Misalnya, Logging:LogLevel:Microsoft:Warning
• Semua penyedia dan semua kategori: Logging:LogLevel:Default:Warning

Log apa pun di bawah tingkat minimum tidak:

• Diteruskan ke penyedia.
• Dicatat atau ditampilkan.

Untuk menekan 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 mereka diaktifkan. Untuk informasi selengkapnya, lihat cakupan log

File berikut berisi appsettings.json 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 dalam Logging.{providername}.LogLevel mengesampingkan pengaturan di Logging.LogLevel. Misalnya, tingkat dalam Debug.LogLevel.Default mengambil alih tingkat di LogLevel.Default.
• Setiap alias penyedia default digunakan. Setiap penyedia mendefinisikan alias yang dapat digunakan dalam konfigurasi sebagai pengganti nama jenis yang sepenuhnya memenuhi syarat. Alias penyedia bawaan adalah:
  • Konsol
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Mengatur tingkat log menurut baris perintah, variabel lingkungan, dan konfigurasi lainnya

Tingkat log dapat diatur oleh salah satu penyedia konfigurasi.

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

• Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ adalah.
• Digantikan secara otomatis oleh :

Perintah berikut:

• Atur kunci Logging:LogLevel:Microsoft lingkungan ke nilai Information pada Windows.
• Uji pengaturan saat menggunakan aplikasi yang dibuat dengan templat aplikasi web ASP.NET Core. Perintah dotnet run harus dijalankan di direktori proyek setelah menggunakan set.

set Logging__LogLevel__Microsoft=Information
dotnet run

Pengaturan lingkungan sebelumnya:

• Hanya diatur dalam proses yang diluncurkan dari jendela perintah tempat mereka diatur.
• Tidak dibaca oleh browser yang diluncurkan dengan Visual Studio.

Perintah setx berikut juga mengatur kunci lingkungan dan nilai pada Windows. Tidak seperti set, setx pengaturan tetap ada. Sakelar /M mengatur variabel di lingkungan sistem. Jika /M tidak digunakan, variabel lingkungan pengguna diatur.

setx Logging__LogLevel__Microsoft Information /M

Pertimbangkan file berikut appsettings.json :

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

Perintah berikut mengatur konfigurasi sebelumnya di lingkungan:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Pada Azure App Service, pilih Pengaturan aplikasi baru di halaman Konfigurasi Pengaturan>. Azure App Service pengaturan aplikasi adalah:

• Dienkripsi saat tidak aktif dan ditransmisikan melalui saluran terenkripsi.
• Diekspos sebagai variabel lingkungan.

Untuk informasi selengkapnya, lihat Aplikasi Azure: Mengambil alih konfigurasi aplikasi menggunakan Portal Microsoft Azure.

Untuk informasi selengkapnya tentang pengaturan ASP.NET Nilai konfigurasi inti menggunakan variabel lingkungan, lihat variabel lingkungan. Untuk informasi tentang menggunakan sumber konfigurasi lain, termasuk baris perintah, Azure Key Vault, Azure App Configuration, format file lainnya, dan lainnya, lihat Konfigurasi di ASP.NET Core.

Bagaimana aturan pemfilteran diterapkan

ILogger<TCategoryName> Saat objek dibuat, ILoggerFactory objek memilih satu aturan per penyedia untuk diterapkan ke pencatat tersebut. Semua pesan yang ILogger ditulis oleh instans difilter berdasarkan aturan yang dipilih. Aturan paling spesifik untuk setiap penyedia dan pasangan 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 ada kecocokan yang ditemukan, pilih semua aturan dengan penyedia kosong.
• Dari hasil langkah sebelumnya, pilih aturan dengan awalan kategori pencocokan terpanjang. Jika tidak ada kecocokan yang ditemukan, pilih semua aturan yang tidak menentukan kategori.
• Jika beberapa aturan dipilih, ambil aturan terakhir .
• Jika tidak ada aturan yang dipilih, gunakan MinimumLevel.

Output pengelogan dari dotnet run dan Visual Studio

Log yang dibuat dengan penyedia pengelogan default ditampilkan:

• Di Visual Studio
  • Di jendela Output debug saat men-debug.
  • Di jendela ASP.NET Core Web Server.
• Di jendela konsol saat aplikasi dijalankan dengan dotnet run.

Log yang dimulai dengan kategori "Microsoft" berasal dari kode kerangka kerja ASP.NET Core. ASP.NET Core dan kode aplikasi menggunakan API pengelogan dan penyedia yang sama.

Kategori log

ILogger Saat objek dibuat, kategori ditentukan. Kategori tersebut disertakan dengan setiap pesan log yang dibuat oleh instans tersebut.ILogger String kategori bersifat arbitrer, tetapi konvensinya adalah menggunakan nama kelas. Misalnya, dalam pengontrol nama mungkin "TodoApi.Controllers.TodoController". Aplikasi web ASP.NET Core digunakan ILogger<T> untuk secara otomatis mendapatkan ILogger instans yang menggunakan nama T jenis yang sepenuhnya memenuhi syarat sebagai kategori:

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

Untuk menentukan kategori secara eksplisit, panggil 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.");
    }

Panggilan CreateLogger dengan nama tetap dapat berguna saat digunakan dalam beberapa metode sehingga peristiwa dapat diatur berdasarkan kategori.

ILogger<T> setara dengan panggilan CreateLogger dengan nama jenis yang sepenuhnya memenuhi syarat dari T.

Tingkat log

Tabel berikut ini mencantumkan LogLevel nilai, metode ekstensi kenyamanan Log{LogLevel} , dan penggunaan yang disarankan:

LogLevel	Nilai	Metode	Deskripsi
Lacak	0	LogTrace	Berisi pesan yang paling rinci. Pesan-pesan ini mungkin berisi data aplikasi sensitif. Pesan-pesan ini dinonaktifkan secara default dan tidak boleh diaktifkan dalam produksi.
Debug	1	LogDebug	Untuk penelusuran kesalahan dan pengembangan. Gunakan dengan hati-hati dalam produksi karena volume yang tinggi.
Informasi	2	LogInformation	Melacak alur umum aplikasi. Mungkin memiliki nilai jangka panjang.
Peringatan	3	LogWarning	Untuk peristiwa abnormal atau tak terduga. Biasanya menyertakan kesalahan atau kondisi yang tidak menyebabkan aplikasi gagal.
Kesalahan	4	LogError	Untuk kesalahan dan pengecualian yang tidak dapat ditangani. Pesan-pesan ini menunjukkan kegagalan dalam operasi atau permintaan saat ini, bukan kegagalan di seluruh aplikasi.
Kritis	5	LogCritical	Untuk kegagalan yang membutuhkan perhatian segera. Contoh: skenario kehilangan data, kehabisan ruang disk.
Tidak ada	6		Menentukan bahwa kategori pengelogan tidak boleh menulis pesan apa pun.

Dalam tabel sebelumnya, LogLevel dicantumkan dari tingkat keparahan terendah hingga tertinggi.

Parameter pertama metode Log , LogLevel, menunjukkan tingkat keparahan log. Daripada memanggil Log(LogLevel, ...), sebagian besar pengembang memanggil metode ekstensi Log{LogLevel} . Metode Log{LogLevel} ekstensi memanggil metode Log dan menentukan LogLevel. Misalnya, dua panggilan pengelogan berikut secara fungsional setara dan menghasilkan log yang sama:

[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 adalah ID peristiwa. MyLogEvents adalah bagian dari aplikasi sampel dan ditampilkan di bagian ID peristiwa Log .

MyDisplayRouteInfo dan ToCtxString disediakan oleh paket Rick.Docs.Samples.RouteInfo NuGet. Metode menampilkan Controller dan Razor Page merutekan informasi.

Kode berikut membuat Information dan Warning mencatat:

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

Dalam kode sebelumnya, parameter pertama Log{LogLevel} ,MyLogEvents.GetItem adalah ID peristiwa Log. Parameter kedua adalah templat pesan dengan tempat penampung untuk nilai argumen yang disediakan oleh parameter metode yang tersisa. Parameter metode dijelaskan di bagian templat pesan nanti dalam dokumen ini.

Panggil metode yang sesuai Log{LogLevel} untuk mengontrol berapa banyak output log yang ditulis ke media penyimpanan tertentu. Contohnya:

• Dalam produksi:
  • Pengelogan di Trace tingkat atau Information menghasilkan pesan log terperinci dalam volume tinggi. Untuk mengontrol biaya dan tidak melebihi batas penyimpanan data, catat Trace dan Information tingkat pesan ke penyimpanan data bervolume tinggi dengan biaya rendah. Pertimbangkan untuk membatasi Trace dan Information untuk kategori tertentu.
  • Pengelogan melalui WarningCritical tingkat harus menghasilkan beberapa pesan log.
    • Biaya dan batas penyimpanan biasanya tidak menjadi perhatian.
    • Beberapa log memungkinkan lebih banyak fleksibilitas dalam pilihan penyimpanan data.
• Dalam pengembangan:
  • Atur ke Warning.
  • Tambahkan Trace pesan atau Information saat memecahkan masalah. Untuk membatasi output, atur Trace atau Information hanya untuk kategori yang sedang diselidiki.

ASP.NET Core menulis log untuk peristiwa kerangka kerja. Misalnya, pertimbangkan output log untuk:

• Aplikasi Razor Pages dibuat dengan templat ASP.NET Core.
• Pengelogan diatur ke Logging:Console:LogLevel:Microsoft:Information
• Navigasi ke Privacy halaman:

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

Set Logging:Console:LogLevel:Microsoft:InformationON berikut JS:

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

ID peristiwa log

Setiap log dapat menentukan ID peristiwa. Aplikasi sampel menggunakan MyLogEvents kelas untuk menentukan ID peristiwa:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

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

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

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

    return ItemToDTO(todoItem);
}

ID peristiwa mengaitkan serangkaian peristiwa. Misalnya, semua log yang terkait dengan menampilkan daftar item di halaman mungkin 1001.

Penyedia pengelogan dapat menyimpan ID peristiwa di bidang ID, dalam pesan pengelogan, atau tidak sama sekali. Penyedia Debug tidak menampilkan ID peristiwa. Penyedia konsol menampilkan ID peristiwa dalam tanda kurung siku setelah kategori:

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

Beberapa penyedia pengelogan menyimpan ID peristiwa di bidang , yang memungkinkan pemfilteran pada ID.

Templat pesan log

Setiap API log menggunakan templat pesan. Templat pesan dapat berisi tempat penampung yang argumennya disediakan. Gunakan nama untuk tempat penampung, bukan angka.

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

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 templat pesan:

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

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

Namun, parameter ditetapkan ke tempat penampung dalam urutan: apples, , pearsbananas. Pesan log mencerminkan urutan parameter:

Parameters: 1, 2, 3

Pendekatan ini memungkinkan penyedia pengelogan untuk menerapkan pengelogan semantik atau terstruktur. Argumen itu sendiri diteruskan ke sistem pengelogan, bukan hanya templat 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);

Misalnya, saat masuk ke Azure Table Storage:

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

Pengecualian log

Metode pencatat memiliki kelebihan beban yang mengambil parameter pengecualian:

[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 dan ToCtxString disediakan oleh paket Rick.Docs.Samples.RouteInfo NuGet. Metode menampilkan Controller dan Razor Page merutekan informasi.

Pengelogan pengecualian khusus untuk penyedia.

Tingkat log default

Jika tingkat log default tidak diatur, nilai tingkat log default adalah Information.

Misalnya, pertimbangkan aplikasi web berikut:

• Dibuat dengan templat aplikasi web ASP.NET.
• appsettings.json dan appsettings.Development.json dihapus atau diganti namanya.

Dengan penyiapan sebelumnya, menavigasi ke privasi atau halaman beranda menghasilkan banyak Tracepesan , Debug, dan Information dengan Microsoft dalam nama kategori.

Kode berikut mengatur tingkat log default saat tingkat log default tidak diatur dalam konfigurasi:

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

Umumnya, tingkat log harus ditentukan dalam konfigurasi dan bukan kode.

Fungsi filter

Fungsi filter dipanggil untuk semua penyedia dan kategori yang tidak memiliki aturan yang ditetapkan untuk mereka berdasarkan konfigurasi atau kode:

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

Kode sebelumnya menampilkan log konsol saat kategori berisi Controller atau Microsoft dan tingkat Information log atau lebih tinggi.

Umumnya, tingkat log harus ditentukan dalam konfigurasi dan bukan kode.

ASP.NET kategori Core dan EF Core

Tabel berikut berisi beberapa kategori yang digunakan oleh ASP.NET Core dan Entity Framework Core, dengan catatan tentang log:

Kategori	Catatan
Microsoft.AspNetCore	Diagnostik Umum ASP.NET Core.
Microsoft.AspNetCore.DataProtection	Kunci mana yang dipertimbangkan, ditemukan, dan digunakan.
Microsoft.AspNetCore.HostFiltering	Host diizinkan.
Microsoft.AspNetCore.Hosting	Berapa lama waktu yang dibutuhkan permintaan HTTP untuk diselesaikan dan jam berapa mereka dimulai. Rakitan startup hosting mana yang dimuat.
Microsoft.AspNetCore.Mvc	MVC dan Razor diagnostik. Pengikatan model, eksekusi filter, kompilasi tampilan, pemilihan tindakan.
Microsoft.AspNetCore.Routing	Merutekan informasi pencocokan.
Microsoft.AspNetCore.Server	Koneksi dimulai, berhenti, dan respons tetap hidup. Informasi sertifikat HTTPS.
Microsoft.AspNetCore.StaticFiles	File disajikan.
Microsoft.EntityFrameworkCore	Diagnostik Inti Kerangka Kerja Entitas Umum. Aktivitas dan konfigurasi database, deteksi perubahan, migrasi.

Untuk melihat kategori lainnya di jendela konsol, atur appsettings.Development.json ke yang berikut ini:

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

Cakupan log

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

Cakupan:

• IDisposable Adalah jenis yang dikembalikan oleh BeginScope metode .
• Berlangsung sampai dibuang.

Penyedia berikut mendukung cakupan:

• Console
• AzureAppServicesFile dan AzureAppServicesBlob

Gunakan cakupan dengan membungkus panggilan pencatat using dalam blok:

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

Penyedia pengelogan bawaan

ASP.NET Core menyertakan penyedia pengelogan berikut sebagai bagian dari kerangka kerja bersama:

• Konsol
• Debug
• EventSource
• EventLog

Penyedia pengelogan berikut dikirim oleh Microsoft, tetapi bukan sebagai bagian dari kerangka kerja bersama. Mereka harus diinstal sebagai nuget tambahan.

• 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 stdout dan men-debug pengelogan dengan Modul ASP.NET Core, lihat Memecahkan masalah ASP.NET Core pada Azure App Service dan IIS dan ASP.NET Core Module (ANCM) untuk IIS.

Konsol

Penyedia Console mencatat output ke konsol. Untuk informasi selengkapnya tentang melihat Console log dalam pengembangan, lihat Pengelogan output dari dotnet run dan Visual Studio.

Debug

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

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

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

Sumber Kejadian

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

alat pelacakan dotnet

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

Lihat dotnet-trace untuk instruksi penginstalan.

Gunakan alat pelacakan dotnet untuk mengumpulkan jejak dari aplikasi:

1. Jalankan aplikasi dengan dotnet run perintah .

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

   dotnet trace ps
   

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

3. Jalankan perintah dotnet trace.

   Sintaks perintah umum:

   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, sertakan --providers nilai 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 -f speedscope opsi untuk mengubah format file pelacakan output menjadi speedscope.

   Tabel berikut mendefinisikan Kata Kunci:

   Kata kunci	Deskripsi
   1	Catat LoggingEventSourceperistiwa meta tentang . Tidak mencatat peristiwa dari ILogger.
   2	Message Mengaktifkan peristiwa saat ILogger.Log() dipanggil. Menyediakan informasi dengan cara terprogram (tidak diformat).
   4	FormatMessage Mengaktifkan peristiwa saat ILogger.Log() dipanggil. Menyediakan versi string informasi yang diformat.
   8	MessageJson Mengaktifkan peristiwa saat ILogger.Log() dipanggil. JSMenyediakan representasi ON dari argumen.

   Tabel berikut mencantumkan tingkat penyedia:

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

   Penguraian untuk tingkat kategori dapat berupa string atau angka:

   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.
   • Konstanta string tidak semuanya identik.

   Jika tidak FilterSpecs ditentukan maka 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) telah diatur melalui set PID=12345, di mana 12345 adalah PID yang sebenarnya.

   Pertimbangkan perintah berikut:

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

   Perintah sebelumnya:

   • Mengambil 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 menangkap pesan debug karena kategori tingkat 5 adalah Critical.
   • FilterSpecsMenyediakan .

   Perintah berikut menangkap 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 {Logger Category} dan {Category Level} mewakili kondisi pemfilteran log tambahan. Pisahkan FilterSpecs entri dengan ; karakter titik koma.

   Contoh menggunakan shell perintah Windows:

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

   Perintah sebelumnya mengaktifkan:

   • Pencatat Sumber Kejadian untuk menghasilkan string yang diformat (4) untuk kesalahan (2).
   • Microsoft.AspNetCore.Hosting pengelogan pada tingkat pengelogan Informational (4).

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

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

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

Jika aplikasi tidak membangun host dengan CreateDefaultBuilder, tambahkan penyedia Sumber Kejadian ke konfigurasi pengelogan aplikasi.

Untuk informasi selengkapnya, lihat:

• Lacak untuk utilitas analisis performa (dotnet-trace) (dokumentasi.NET Core)
• Melacak utilitas analisis performa (dotnet-trace) (dokumentasi repositori GitHub dotnet/diagnostik)
• Kelas LoggingEventSource (Browser.NET API)
• EventLevel
• Sumber referensi LoggingEventSource (3.0): Untuk mendapatkan sumber referensi untuk versi yang berbeda, ubah cabang ke release/{Version}, di mana {Version} adalah versi ASP.NET Core yang diinginkan.
• Perfview: Berguna untuk melihat jejak Sumber Peristiwa.

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 untuk mengumpulkan peristiwa yang dicatat oleh penyedia ini, tambahkan string *Microsoft-Extensions-Logging ke daftar Penyedia Tambahan . Jangan lewatkan * di awal string.

Windows EventLog

Penyedia EventLog mengirim output log ke Log Peristiwa Windows. Tidak seperti penyedia lain, EventLog penyedia tidak mewarisi pengaturan non-penyedia default. Jika EventLog pengaturan log tidak ditentukan, pengaturan tersebut default ke LogLevel.Warning.

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

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

Kelebihan beban AddEventLog dapat melewati EventLogSettings. Jika null ditentukan atau tidak, pengaturan default berikut digunakan:

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

Kode berikut mengubah SourceName dari nilai default menjadi ".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

Paket penyedia Microsoft.Extensions.Logging.AzureAppServices menulis log ke file teks dalam sistem file aplikasi Azure App Service dan penyimpanan blob di akun Azure Storage.

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 dalam contoh berikut:

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

Saat disebarkan ke Azure App Service, aplikasi menggunakan pengaturan di bagian log App Service dari halaman App Service portal Azure. Saat pengaturan berikut diperbarui, perubahan segera berlaku tanpa memerlukan mulai ulang atau penyebaran ulang aplikasi.

• Pengelogan Aplikasi (Filesystem)
• Pengelogan Aplikasi (Blob)

Lokasi default untuk file log ada di folder D:\home\LogFiles\Application , dan nama file default diagnostics-yyyymmdd.txt. Batas ukuran file default adalah 10 MB, dan jumlah maksimum default file yang dipertahankan adalah 2. Nama blob default adalah {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Penyedia ini hanya mencatat ketika proyek berjalan di lingkungan Azure.

Streaming log Azure

Streaming log Azure mendukung penayangan aktivitas log secara real time dari:

• Server aplikasi
• Server web
• Pelacakan permintaan gagal

Untuk mengonfigurasi streaming log Azure:

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

Navigasi ke halaman Aliran Log untuk melihat log. Pesan yang dicatat dicatat dengan ILogger antarmuka.

Azure Application Insights

Paket penyedia Microsoft.Extensions.Logging.ApplicationInsights menulis log ke Azure Application Insights. Application Insights adalah layanan yang memantau aplikasi web dan menyediakan alat untuk mengkueri dan menganalisis data telemetri. Jika Anda menggunakan penyedia ini, Anda dapat mengkueri dan menganalisis log Anda dengan menggunakan alat Application Insights.

Penyedia pengelogan disertakan sebagai dependensi Microsoft.ApplicationInsights.AspNetCore, yang merupakan paket yang menyediakan semua telemetri yang tersedia untuk ASP.NET Core. Jika Anda menggunakan paket ini, Anda tidak perlu menginstal paket penyedia.

Paket Microsoft.ApplicationInsights.Web adalah untuk ASP.NET 4.x, bukan ASP.NET Core.

Untuk informasi lebih lanjut, lihat sumber daya berikut ini:

• Ringkasan Application Insights
• Application Insights untuk aplikasi ASP.NET Core - Mulai di sini jika Anda ingin menerapkan berbagai telemetri Application Insights bersama dengan pengelogan.
• ApplicationInsightsLoggerProvider untuk log .NET Core ILogger - Mulai di sini jika Anda ingin menerapkan penyedia pengelogan tanpa telemetri Application Insights lainnya.
• Adaptor pengelogan Application Insights.
• Menginstal, mengonfigurasi, dan menginisialisasi Application Insights SDK - Tutorial interaktif di situs Microsoft Learn.

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, juga dikenal sebagai pengelogan terstruktur.

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

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

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

Aplikasi konsol non-host

Untuk contoh cara menggunakan Host Generik di aplikasi konsol non-web, lihat Program.cs file aplikasi sampel Tugas Latar Belakang (Tugas latar belakang dengan layanan yang dihosting di ASP.NET Core).

Kode pengelogan untuk aplikasi tanpa Host Generik berbeda dalam cara penyedia ditambahkan dan pencatat dibuat.

Penyedia pengelogan

Di aplikasi konsol non-host, panggil metode ekstensi penyedia Add{provider name} saat membuat 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");
    }
}

Membuat log

Untuk membuat log, gunakan ILogger<TCategoryName> objek . LoggerFactory Gunakan untuk membuat ILogger.

Contoh berikut membuat pencatat dengan LoggingConsoleApp.Program sebagai kategori.

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

Dalam contoh berikut, pencatat digunakan untuk membuat log sebagai Information tingkat. Tingkat Log menunjukkan tingkat keparahan peristiwa yang dicatat.

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

Tingkat dan kategori dijelaskan secara lebih rinci dalam dokumen ini.

Log selama konstruksi host

Pengelogan selama konstruksi host tidak didukung secara langsung. Namun, pencatat terpisah dapat digunakan. Dalam contoh berikut, pencatat Serilog digunakan untuk masuk CreateHostBuilder. AddSerilog menggunakan konfigurasi statis yang ditentukan dalam 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();
        }
    }
}

Mengonfigurasi layanan yang bergantung pada ILogger

Injeksi konstruktor pencatat berfungsi Startup dalam versi ASP.NET Core yang lebih lama karena kontainer DI terpisah dibuat untuk Web Host. Untuk informasi tentang mengapa hanya satu kontainer yang dibuat untuk Host Generik, lihat pengumuman perubahan yang melanggar.

Untuk mengonfigurasi layanan yang bergantung pada ILogger<T>, gunakan injeksi konstruktor atau berikan metode pabrik. Pendekatan metode pabrik direkomendasikan hanya jika tidak ada opsi lain. Misalnya, pertimbangkan layanan yang memerlukan instans yang ILogger<T> disediakan oleh 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 };
    });
}

Kode yang disorot sebelumnya adalah Func<T,TResult> yang berjalan pertama kalinya kontainer DI perlu membuat instans MyService. Anda dapat mengakses salah satu layanan terdaftar dengan cara ini.

Membuat log di Utama

Kode berikut masuk Main dengan mendapatkan ILogger instans dari DI setelah membangun host:

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

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

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

Membuat log di Startup

Kode berikut menulis log di 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();
    });
}

Menulis log sebelum penyelesaian penyiapan kontainer DI dalam Startup.ConfigureServices metode tidak didukung:

• Injeksi pencatat ke Startup konstruktor tidak didukung.
• Injeksi pencatat ke Startup.ConfigureServices dalam tanda tangan metode tidak didukung

Alasan pembatasan ini adalah bahwa pengelogan tergantung pada DI dan pada konfigurasi, yang pada gilirannya tergantung pada DI. Kontainer DI tidak disiapkan hingga ConfigureServices selesai.

Untuk informasi tentang mengonfigurasi layanan yang bergantung pada ILogger<T> atau mengapa injeksi konstruktor pencatat berfungsi Startup di versi sebelumnya, lihat Mengonfigurasi layanan yang bergantung pada ILogger

Tidak ada metode pencatat asinkron

Pengelogan harus sangat cepat sehingga tidak sebanding dengan biaya performa kode asinkron. Jika penyimpanan data pengelogan lambat, jangan menulisnya secara langsung. Pertimbangkan untuk menulis pesan log ke penyimpanan cepat pada awalnya, lalu pindahkan ke penyimpanan lambat nanti. Misalnya, saat pengelogan ke SQL Server, jangan melakukannya secara langsung dalam Log metode , karena metodenya Log sinkron. Sebagai gantinya, tambahkan pesan log secara sinkron ke antrean dalam memori dan minta pekerja latar belakang menarik pesan keluar dari antrean untuk melakukan pekerjaan asinkron mendorong data ke SQL Server. Untuk informasi selengkapnya, lihat masalah GitHub ini .

Mengubah tingkat log di aplikasi yang sedang berjalan

API Pengelogan tidak menyertakan skenario untuk mengubah tingkat log saat aplikasi sedang berjalan. Namun, beberapa penyedia konfigurasi mampu 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 berjalan, aplikasi dapat memanggil IConfigurationRoot.Reload untuk memperbarui konfigurasi pengelogan aplikasi.

ILogger dan ILoggerFactory

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

• Antarmuka berada di Microsoft.Extensions.Logging.Abstractions.
• Implementasi default ada di Microsoft.Extensions.Logging.

Menerapkan aturan filter log dalam kode

Pendekatan yang disukai untuk mengatur aturan filter log adalah dengan menggunakan Konfigurasi.

Contoh berikut menunjukkan cara mendaftarkan aturan filter dalam kode:

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)System menentukan kategori dan tingkat Debuglog . Filter diterapkan ke semua penyedia karena penyedia tertentu tidak dikonfigurasi.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) Menentukan:

• Penyedia Debug pengelogan.
• Tingkat log dan yang Information lebih tinggi.
• Semua kategori dimulai dengan "Microsoft".

Secara otomatis mencatat cakupan dengan SpanId, TraceId, dan ParentId

Pustaka pengelogan secara implisit membuat objek cakupan dengan SpanId, TraceId, dan ParentId. Perilaku ini dikonfigurasi melalui ActivityTrackingOptions.

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

traceparent Jika header permintaan http diatur, ParentId dalam lingkup log menunjukkan W3C parent-id dari header terikat traceparent dan SpanId dalam cakupan log memperlihatkan yang diperbarui parent-id untuk langkah/rentang terikat berikutnya. Untuk informasi selengkapnya, lihat Bermutasi Bidang traceparent.

Membuat pencatat kustom

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

Sumber Daya Tambahan:

• Pengelogan berkinerja tinggi dengan LoggerMessage di ASP.NET Core
• Bug pengelogan harus dibuat di repositori github.com/dotnet/runtime/ .
• pengelogan ASP.NET Core Blazor