Với NLog, file cấu hình là sản phẩm. Bạn có thể sửa routing, format, rotation trên production mà không build lại — nhưng cũng chính vì thế mà một nlog.config copy từ blog cũ có thể ghi mỗi request thành năm dòng, không có trace id, và đầy file sau hai ngày. Bài này đi vào bốn thứ thực sự quyết định: target, layout, rule, và ngữ cảnh ASP.NET Core.
Mục lục
Cập nhật 2026
NLog.Web.AspNetCore6.2.2 trên NLog 6.x; tích hợp quabuilder.Host.UseNLog(), không cầnStartup.cs.ScopeContextthay choMappedDiagnosticsContext(MDC) vàNestedDiagnosticsContext(NDLC). Code cũ vẫn chạy, nhưng đó là API legacy.- Log có cấu trúc đi qua
JsonLayoutvớiincludeAllProperties; không cần tự nối chuỗi JSON. - Trace và metric thuộc về OpenTelemetry .NET SDK. NLog giữ phần log — đừng ép nó làm tracing.
Mô hình: logger → rule → target → layout
Bốn khái niệm, theo đúng thứ tự xử lý:
- Logger — đối tượng bạn gọi
Info,Warn,Error. Tên logger thường là tên class, lấy bằngLogManager.GetCurrentClassLogger()hoặc quaILogger<T>của MEL. - Rule — bộ lọc theo tên logger và level, chỉ định target nào nhận event. Đây là phần điều hướng, và là nơi mọi cấu hình sai bắt đầu.
- Target — đích ghi: file, console, database, network, mail.
- Layout — chuỗi format của target, ghép từ các layout renderer như
${longdate},${level},${message}.
Điều quan trọng: rule không lọc theo nội dung message. Nếu bạn cần “chỉ ghi lỗi liên quan đến thanh toán”, hãy dùng logger name (MyApp.Payments.*) hoặc WithProperty + filter, đừng regex message.
Tích hợp vào ASP.NET Core 10
// File: Program.cs
using NLog;
using NLog.Web;
var logger = LogManager.Setup()
.LoadConfigurationFromFile("nlog.config")
.GetCurrentClassLogger();
try
{
logger.Debug("Khởi tạo ứng dụng");
var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Host.UseNLog(); // chuyển MEL sang NLog
var app = builder.Build();
app.Run();
}
catch (Exception ex)
{
logger.Error(ex, "Ứng dụng dừng do lỗi khởi động");
throw;
}
finally
{
LogManager.Shutdown();
}
ClearProviders() là bắt buộc nếu bạn không muốn log bị ghi hai lần — một lần qua provider mặc định của MEL, một lần qua NLog. LogManager.Shutdown() trong finally đảm bảo các target async flush hết queue trước khi process thoát; thiếu nó, những dòng log cuối cùng trước khi crash sẽ biến mất.
Đừng gọi LogManager.GetCurrentClassLogger() trong mỗi class nữa nếu bạn đã dùng DI. Inject ILogger<T> và để NLog nhận event qua MEL — code sẽ test được bằng NullLogger, và không phụ thuộc static global.
nlog.config: bản tối thiểu nhưng đúng
<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
autoReload="true"
internalLogLevel="Warn"
internalLogFile="logs/nlog-internal.log">
<variable name="logDirectory" value="${basedir}/logs" />
<targets>
<target xsi:type="File" name="file"
fileName="${logDirectory}/app-${shortdate}.log"
layout="${longdate}|${level:uppercase=true}|${logger}|${message}|${exception:format=tostring}"
archiveAboveSize="52428800"
maxArchiveFiles="30"
keepFileOpen="true"
encoding="utf-8" />
<target xsi:type="Console" name="console"
layout="${longdate}|${level:uppercase=true}|${logger}|${message}" />
</targets>
<rules>
<logger name="*" minlevel="Info" writeTo="file,console" />
<logger name="Microsoft.*" maxlevel="Info" final="true" />
<logger name="System.*" maxlevel="Info" final="true" />
</rules>
</nlog>
Ba dòng cuối là mẹo quan trọng: một rule không có writeTo hoạt động như bộ lọc final — nó chặn event khớp điều kiện và không cho rơi xuống các rule sau. Nhờ vậy log hạ tầng của Microsoft.* và System.* không làm ngập file nghiệp vụ, mà bạn vẫn giữ được mức Warning/Error của chúng nếu thêm rule riêng ở trên.
autoReload="true" khiến NLog theo dõi file và nạp lại khi sửa. Trên container, điều này vô nghĩa vì image là immutable — nhưng trên VM hoặc Windows service, nó cho phép tăng level debug trong vài giây mà không restart.
internalLogFile là công cụ debug chính thức của NLog: khi config sai cú pháp hoặc target không ghi được, NLog nuốt lỗi và ứng dụng vẫn chạy. Bật internalLogLevel="Warn" ở staging, đừng để Trace trên production vì file nội bộ cũng phình.
XML hay code?
| Tiêu chí | XML (nlog.config) |
Code |
|---|---|---|
| Đổi cấu hình không cần deploy | Có (autoReload) |
Không |
| Type-safety, test được | Không | Có |
| Cấu hình phức tạp, nhiều target | Rõ ràng hơn | Dài và khó đọc |
| Biến theo môi trường | ${environment}, appsettings |
Đọc IConfiguration trực tiếp |
Thực tế phổ biến: XML cho cấu trúc, code cho những thứ cần tính toán. Nếu cấu hình bằng code, đăng ký qua LogManager.Setup().LoadConfiguration(...) hoặc tạo LoggingConfiguration và AddRule — đừng trộn hai nguồn cùng lúc, vì lần load sau sẽ ghi đè lần trước và bạn sẽ mất rule mà không thấy lỗi.
Log có cấu trúc: JsonLayout, không phải nối chuỗi
Nếu sink đích là Seq, Elasticsearch, Loki hay một collector OTLP, output phải là JSON hợp lệ. JsonLayout làm việc đó và mang theo mọi property của event:
<target xsi:type="Console" name="jsonConsole">
<layout xsi:type="JsonLayout" includeAllProperties="true">
<attribute name="time" layout="${longdate}" />
<attribute name="level" layout="${level:uppercase=true}" />
<attribute name="logger" layout="${logger}" />
<attribute name="message" layout="${message}" />
<attribute name="traceId" layout="${aspnet-traceidentifier}" />
<attribute name="exception" layout="${exception:format=tostring}" />
</layout>
</target>
includeAllProperties="true" là phần biến NLog thành structured logging thật: mọi thứ bạn đưa vào qua message placeholder hoặc WithProperty sẽ thành field JSON, không bị nhúng vào chuỗi.
// Cách 1: placeholder trong message template
_logger.Info("Đơn {OrderId} của khách {CustomerId} đã thanh toán {Amount}", orderId, customerId, amount);
// Cách 2: property theo logger, không đổi message
_logger.WithProperty("OrderId", orderId).Info("Bắt đầu xử lý thanh toán");
Nếu bạn đang dùng MEL ILogger (khuyến nghị), cách 1 là đủ — MEL truyền state dưới dạng structured values, NLog render chúng thành property. Với cách 2, property chỉ tồn tại trên event đó, không lan sang các log bên trong service như ScopeContext.
${aspnet-request-*}: ngữ cảnh request miễn phí
NLog.Web.AspNetCore cung cấp các layout renderer đọc trực tiếp từ HttpContext, không cần middleware tự viết:
| Renderer | Giá trị |
|---|---|
${aspnet-request-method} |
GET, POST, … |
${aspnet-request-url} |
URL đầy đủ, gồm query string |
${aspnet-request-ip} |
IP client (theo RemoteIpAddress) |
${aspnet-traceidentifier} |
HttpContext.TraceIdentifier — id nội bộ ASP.NET, không phải W3C trace id |
${aspnet-user-identity} |
Tên user đã xác thực |
${aspnet-session} |
Session id, nếu session được bật |
<target xsi:type="File" name="requestFile"
fileName="${logDirectory}/requests-${shortdate}.log"
layout="${longdate}|${level}|${aspnet-request-method} ${aspnet-request-url}|${aspnet-user-identity}|${aspnet-traceidentifier}|${message}" />
Hai cảnh báo. Thứ nhất, ${aspnet-request-url} chứa query string — nếu API của bạn nhận token trong query, bạn vừa ghi token ra file. Thứ hai, ${aspnet-traceidentifier} chỉ là correlation id của ASP.NET; khi bạn cần nối với OpenTelemetry, hãy dùng Activity.Current.TraceId (phần sau).
Và đừng log ${aspnet-request-url} cho mọi request ở mức Info nếu lưu lượng cao: mỗi request một dòng URL là cách nhanh nhất để file log chiếm GB mỗi ngày. Chỉ target riêng, chỉ khi cần.
ScopeContext: ngữ cảnh theo request, không theo tham số
Đây là thay thế đúng cho MDC/NDLC mà các bài cũ dạy:
// File: Middleware/CorrelationMiddleware.cs
using NLog;
public sealed class CorrelationMiddleware(RequestDelegate next)
{
public async Task InvokeAsync(HttpContext context)
{
using var scope = ScopeContext.PushProperty(
"RequestId", context.TraceIdentifier);
if (context.User.Identity?.IsAuthenticated == true)
ScopeContext.PushProperty("UserId", context.User.Identity.Name);
await next(context);
}
}
Layout đọc lại bằng ${scopeproperty:item=RequestId}. Scope đi theo AsyncLocal, nên nó sống qua await trong cùng request và tự bong khi dispose — không cần nhớ xóa tay như MDC.
<attribute name="requestId" layout="${scopeproperty:item=RequestId}" />
<attribute name="userId" layout="${scopeproperty:item=UserId}" />
Với background job hoặc consumer không có HttpContext, set scope ở đầu mỗi message xử lý. Đừng giả định scope của request còn sống khi task được queue lại.
Async target và rotation
<target xsi:type="AsyncWrapper" name="asyncFile"
overflowAction="Discard" queueLimit="10000"
batchSize="200" flushTimeout="5000">
<target xsi:type="File" name="fileTarget"
fileName="${logDirectory}/app-${shortdate}.log"
layout="${longdate}|${level:uppercase=true}|${logger}|${message}|${exception:format=tostring}"
archiveAboveSize="52428800"
maxArchiveFiles="30" />
</target>
AsyncWrapper đưa việc ghi sang thread riêng. Ba tham số quyết định hành vi khi quá tải: queueLimit (độ dài queue), overflowAction (Discard hoặc Block), flushTimeout (bao lâu thì đẩy batch). Mặc định Discard nghĩa là mất log khi queue đầy — chấp nhận được cho log debug, không chấp nhận được cho audit. Với log nghiệp vụ quan trọng, dùng Block và biết rằng bạn đang đổi latency lấy độ đầy đủ.
batchSize gộp nhiều event vào một lần ghi, giảm I/O. Các config cũ bọc thêm BufferingWrapper bên trong AsyncWrapper — mẫu đó không còn cần thiết, vì AsyncWrapper đã có batching. Nếu bạn thấy nó trong file cấu hình đang chạy, đó là dấu hiệu config chưa được rà lại.
Rotation: ${shortdate} trong fileName tạo file mới mỗi ngày; archiveAboveSize cắt file khi vượt 50 MB; maxArchiveFiles giới hạn số file giữ lại. Thiếu maxArchiveFiles, disk sẽ đầy — không phải “nếu” mà là “khi nào”.
NLog hay Serilog?
| Tiêu chí | NLog 6 | Serilog 10 |
|---|---|---|
| Cấu hình | XML/JSON, hot reload | Code + appsettings.json |
| Routing phức tạp | Rule rất mạnh (final, filters) |
Sub-logger + filters |
| Message template | Hỗ trợ, cú pháp riêng | Trọng tâm của thư viện |
| Hệ sink/target | Target đa dạng, có sẵn cho Windows/EventLog | Sink phong phú, cộng đồng lớn hơn |
| Ngữ cảnh request | ${aspnet-*} có sẵn |
Cần enricher/middleware |
Không có lựa chọn nào “đúng” tuyệt đối. Chọn NLog khi bạn cần routing phức tạp, cấu hình XML do ops quản lý, hoặc tích hợp Windows/EventLog. Chọn Serilog khi bạn muốn message template làm trung tâm và hệ sink hiện đại. Cả hai đều là provider của MEL, nên code ILogger không đổi.
Migration giữa hai bên là ánh xạ khái niệm, không phải viết lại log statement:
- Sink ↔ Target;
outputTemplate↔ Layout; Enricher ↔ LayoutRenderer. MinimumLevel/filters ↔ Rule (minlevel,maxlevel,final).LogContext↔ScopeContext;Destructure.ByTransforming↔ custom object renderer hoặcJsonLayoutvới attribute chọn lọc.
OpenTelemetry: log không phải trace
NLog không sinh span. Để có trace và metric, dùng OpenTelemetry .NET SDK (OpenTelemetry.Extensions.Hosting + exporter OTLP); NLog tiếp tục phụ trách log. Điều cần làm là gắn cùng một trace id vào cả hai:
// File: Logging/TraceIdRenderer.cs
using System.Diagnostics;
using System.Text;
using NLog;
using NLog.LayoutRenderers;
[LayoutRenderer("oteltraceid")]
public sealed class TraceIdRenderer : LayoutRenderer
{
protected override void Append(StringBuilder builder, LogEventInfo logEvent)
=> builder.Append(Activity.Current?.TraceId.ToString() ?? string.Empty);
}
// Đăng ký một lần khi khởi động:
// LayoutRenderer.Register<TraceIdRenderer>("oteltraceid");
Sau đó thêm <attribute name="traceId" layout="${oteltraceid}" /> vào JsonLayout. Giá trị này trùng với TraceId mà collector OTLP nhận, nên bạn nhảy từ một dòng log sang đúng trace trong Jaeger/Tempo mà không cần join theo timestamp.
Đừng dùng ${aspnet-traceidentifier} cho mục đích này — nó là id của ASP.NET, không được propagate qua HTTP và không khớp với span id.
Anti-pattern
- Rule
*ở mức Trace cho mọi target. Log framework sẽ chiếm 90% file; luôn đặtMicrosoft.*/System.*ở Warning. - Ghi cả request body. Vừa PII vừa dung lượng; nếu buộc phải debug, bật có thời hạn và chỉ cho một route.
- Target Database cho mọi log. Một INSERT mỗi event nghĩa là DB log chịu tải bằng chính ứng dụng; chỉ ghi Error/Fatal, và dùng AsyncWrapper.
- Trộn XML và code. Load sau ghi đè load trước; chọn một nguồn sự thật.
- Không đặt
maxArchiveFiles. Log đầy disk là sự cố production phổ biến hơn bạn nghĩ.
Hướng tới 2027
NLog 6 và Serilog 10 đều ổn định; OpenTelemetry là chuẩn cho trace/metric, và log ngày càng đi qua OTLP thay vì file cục bộ. .NET 11 GA tháng 11/2026 (STS), .NET 12 LTS năm 2027 — không có thay đổi API logging nào đáng lo. Việc nên làm trước là migrate khỏi .NET 8/9 (hết hỗ trợ 2026-11-10) và thống nhất tên property giữa các service.
Checklist
ClearProviders()+UseNLog(), vàLogManager.Shutdown()trongfinally.- Rule
finalchoMicrosoft.*/System.*ở Warning. JsonLayout includeAllPropertiescho mọi sink tập trung.AsyncWrappervớiqueueLimit/overflowActionđược chọn có ý thức.- File target có
maxArchiveFilesvàarchiveAboveSize. ScopeContextcho RequestId/UserId;Activity.Current.TraceIdcho correlation với OTel.- Rà PII trong layout trước khi bật target ra ngoài máy chủ.
Đọc tiếp: ghi log có cấu trúc với Serilog để so sánh trực tiếp; Elasticsearch cho lập trình viên .NET nếu log của bạn sẽ vào một search backend; và xây dựng RESTful API hiệu quả cho phần middleware và pipeline request.



