Một dòng log như $"User {userId} paid order {orderId} in {ms} ms" trông ổn cho đến khi bạn cần trả lời câu hỏi “đơn hàng nào chậm hơn 2 giây trong 24 giờ qua”. Lúc đó bạn phải regex một chuỗi text, và mọi thứ sụp đổ. Structured logging giải quyết đúng bài toán đó: mỗi sự kiện là dữ liệu có field, không phải một câu văn.
Mục lục
Cập nhật 2026
Serilog.AspNetCore10.0 — dòng tương ứng .NET 10. Cấu hình quaappsettings.jsonvàReadFrom.Serviceslà chuẩn hiện tại.CreateBootstrapLogger()thay cho mẫunew LoggerConfiguration().CreateLogger()cũ: nó tự thay thế logger khi host khởi động xong, không rò rỉ logger tạm.- Correlation giờ dựa trên W3C
TraceIdcủaActivity— cùng id với OpenTelemetry, không phải một header tự chế. - .NET 8 và .NET 9 hết hỗ trợ ngày 2026-11-10; ví dụ chạy trên .NET 10 LTS, C# 14.
Vì sao “structured” thắng string interpolation
Với MEL (Microsoft.Extensions.Logging), cả hai dòng dưới đây đều biên dịch được:
logger.LogInformation($"Order {orderId} paid by {customerId}");
logger.LogInformation("Order {OrderId} paid by {CustomerId}", orderId, customerId);
Dòng đầu tạo ra một chuỗi đã format; provider chỉ nhận được text. Dòng thứ hai giữ nguyên template và hai property OrderId, CustomerId — đây là thứ Serilog ghi vào sink. Khác biệt không nằm ở chỗ “đọc dễ hơn”, mà ở chỗ bạn query được:
OrderId = "A-1042"là một field, filter được trong Seq, Kibana hay Loki mà không cần parse.- Tên event ổn định: template là identity, nên dashboard không vỡ khi message đổi wording.
- Property có kiểu: số là số, boolean là boolean, không phải chuỗi “True”.
- Cardinality thấp: bạn biết trước tập field, nên index không phình vì mỗi message một hình dạng khác.
Quy tắc thực dụng: mọi giá trị động đi qua placeholder có tên. Chỉ dùng interpolation cho chuỗi tĩnh không có biến, và ngay cả khi đó cũng chẳng có lý do gì để dùng.
Bootstrap logger: đừng để mất log khởi động
Lỗi hay gặp là cấu hình Serilog sau builder.Build(). Khi đó mọi thứ xảy ra trong lúc DI container đang dựng — đọc config, mở kết nối, chạy migration — không có log.
// File: Program.cs
using Serilog;
using Serilog.Formatting.Compact;
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.Enrich.FromLogContext()
.WriteTo.Console(new RenderedCompactJsonFormatter())
.CreateBootstrapLogger();
try
{
var builder = WebApplication.CreateBuilder(args);
builder.Host.UseSerilog((context, services, config) => config
.ReadFrom.Configuration(context.Configuration)
.ReadFrom.Services(services)
.Enrich.FromLogContext()
.Enrich.With<ActivityTraceEnricher>());
var app = builder.Build();
app.UseSerilogRequestLogging();
app.MapControllers();
app.Run();
}
catch (Exception ex)
{
Log.Fatal(ex, "Host terminated unexpectedly");
}
finally
{
Log.CloseAndFlush();
}
CreateBootstrapLogger() tạo một logger tạm chỉ ghi ra console, rồi bị thay thế khi UseSerilog dựng logger thật từ config. Nhờ vậy log trong khoảng giữa vẫn tồn tại, và không có hai logger cùng ghi file.
Đừng bỏ Log.CloseAndFlush(). Với sink async, đây là lời gọi duy nhất đảm bảo event trong buffer được đẩy ra trước khi process thoát.
UseSerilogRequestLogging: một dòng cho mỗi request
Middleware này thay thế hàng loạt log thủ công kiểu “vào controller”, “ra controller”. Nó ghi đúng một event mỗi request, với method, path, status, elapsed — và bạn mở rộng bằng EnrichDiagnosticContext:
app.UseSerilogRequestLogging(options =>
{
options.MessageTemplate =
"HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms";
options.EnrichDiagnosticContext = (diagnostic, http) =>
{
diagnostic.Set("RequestHost", http.Request.Host.Value ?? "unknown");
diagnostic.Set("RequestScheme", http.Request.Scheme);
diagnostic.Set("UserId", http.User.FindFirst("sub")?.Value);
diagnostic.Set("ClientIp", http.Connection.RemoteIpAddress?.ToString());
};
});
Hai lưu ý về thứ tự: đặt middleware này sớm, ngay sau các middleware bạn muốn đo (exception handler, static files), nhưng trước routing nếu bạn muốn log cả request 404. Nếu đặt sau UseAuthorization, các request bị chặn sẽ không xuất hiện trong log.
Và đừng log lại trong controller những gì middleware đã log. Một request có ba dòng “start”, “end”, “done” là ba lần tăng chi phí và ba lần nhiễu khi truy vấn.
LogContext: ngữ cảnh theo scope, không theo tham số
Truyền orderId qua năm tầng service là việc bạn không nên làm. LogContext gắn property vào luồng xử lý hiện tại và tự bong ra khi dispose:
public async Task HandleAsync(Order order, CancellationToken ct)
{
using (LogContext.PushProperty("OrderId", order.Id))
using (LogContext.PushProperty("CustomerId", order.CustomerId))
{
_logger.LogInformation("Bắt đầu xử lý thanh toán");
await _payment.ChargeAsync(order, ct);
}
}
Mọi log phát sinh bên trong — kể cả log từ thư viện khác đi qua MEL — đều có OrderId. Điều kiện là Enrich.FromLogContext() phải được bật; thiếu nó, property bị bỏ im lặng.
Cảnh báo về async: LogContext dùng AsyncLocal, nên nó đi theo await đúng cách. Nhưng nếu bạn Task.Run mà không truyền state, hoặc chạy background job tách khỏi request, context sẽ không tự sang. Với IHostedService và queue consumer, hãy set property ở đầu mỗi message, không dựa vào scope của request.
Sinks: chọn đích theo môi trường, không theo sở thích
Console và file là mặc định cho dev; production nên ghi ra stdout và để hạ tầng thu gom, hoặc gửi trực tiếp tới backend log. Điều này quan trọng khi chạy container: file trong container là file tạm, mất khi pod restart, và không ai đọc được nếu không mount volume.
{
"Serilog": {
"Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File", "Serilog.Sinks.Seq" ],
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information",
"System": "Warning"
}
},
"WriteTo": [
{ "Name": "Console" },
{
"Name": "File",
"Args": {
"path": "logs/app-.log",
"rollingInterval": "Day",
"retainedFileCountLimit": 14,
"fileSizeLimitBytes": 52428800,
"rollOnFileSizeLimit": true
}
},
{ "Name": "Seq", "Args": { "serverUrl": "http://seq:5341" } }
],
"Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
"Properties": { "Application": "Evotek.Api" }
}
}
Bốn tham số của file sink đáng nhớ: rollingInterval (cắt theo ngày), fileSizeLimitBytes + rollOnFileSizeLimit (cắt theo dung lượng), retainedFileCountLimit (số file giữ lại). Thiếu bộ ba này, một buổi sáng debug là ổ đĩa đầy.
Nếu nhiều process cùng ghi một file, phải đặt "shared": true. Nhưng đó là giải pháp cho desktop app hoặc Windows service, không phải cho web scale-out — hai pod ghi chung một volume là kiến trúc sai, không phải vấn đề cấu hình sink.
Enrichers và traceId: nối log với trace
TraceId lấy từ Activity.Current là W3C trace context — cùng giá trị OpenTelemetry dùng cho span. Đó là sợi dây nối log với trace mà không cần tự sinh correlation id:
// File: Logging/ActivityTraceEnricher.cs
using System.Diagnostics;
using Serilog.Core;
using Serilog.Events;
public sealed class ActivityTraceEnricher : ILogEventEnricher
{
public void Enrich(LogEvent logEvent, ILogEventPropertyFactory factory)
{
if (Activity.Current is not { } activity) return;
logEvent.AddPropertyIfAbsent(
factory.CreateProperty("TraceId", activity.TraceId.ToString()));
logEvent.AddPropertyIfAbsent(
factory.CreateProperty("SpanId", activity.SpanId.ToString()));
}
}
ASP.NET Core tạo một Activity cho mỗi request, nên enricher này hoạt động ngay mà không cần thêm middleware. Nếu bạn dùng package Serilog.Enrichers.Span, nó làm đúng việc tương tự — chọn một trong hai, đừng bật cả hai.
Với OpenTelemetry, log có thể đi qua OTLP bằng Serilog.Sinks.OpenTelemetry, còn trace và metric do SDK OpenTelemetry .NET thu. Nguyên tắc: log không phải trace. Log trả lời “chuyện gì đã xảy ra”, trace trả lời “thời gian đi đâu”. Đừng cố dùng log để dựng waterfall latency; bạn sẽ cần hàng triệu dòng để thay một span.
Levels và sampling: giảm tải mà không mù
Mặc định Information cho application, Warning cho Microsoft và System. Nếu để Debug ở production, framework sẽ ghi hàng nghìn dòng mỗi phút về routing và DI — đó là nhiễu, không phải observability.
Khi cần debug tạm thời mà không redeploy, dùng LoggingLevelSwitch:
var levelSwitch = new LoggingLevelSwitch(LogEventLevel.Information);
Log.Logger = new LoggerConfiguration()
.MinimumLevel.ControlledBy(levelSwitch)
.WriteTo.Console()
.CreateLogger();
// Đổi mức từ một endpoint admin có bảo vệ:
levelSwitch.MinimumLevel = LogEventLevel.Debug;
Với log tần suất cao (theo từng item trong batch, theo từng frame), hãy log tổng hợp thay vì log từng phần tử. Nếu vẫn cần mẫu, dùng một filter đếm:
public sealed class SampleFilter(int everyN) : ILogEventFilter
{
private long _counter;
public bool IsEnabled(LogEvent logEvent) =>
logEvent.Level >= LogEventLevel.Warning
|| Interlocked.Increment(ref _counter) % everyN == 0;
}
// .Filter.With(new SampleFilter(100))
Sampling chỉ an toàn cho log chẩn đoán. Không bao giờ sample log audit, log thanh toán, hay log lỗi — mất một dòng trong số đó là mất bằng chứng.
PII: che ở tầng destructure, không ở tầng đọc log
Cách tốt nhất là không đưa PII vào log. Cách thứ hai là destructure có kiểm soát:
Log.Logger = new LoggerConfiguration()
.Destructure.ByTransforming<Customer>(c => new
{
c.Id,
Email = "***",
Phone = "***",
c.Country
})
.WriteTo.Console()
.CreateLogger();
ByTransforming chạy tại thời điểm ghi, trước khi event tới sink — nghĩa là bản gốc không bao giờ rời process. Nó bắt buộc phải dùng nếu bạn log object nghiệp vụ bằng {@Customer}.
Ba lỗi PII phổ biến nhất: log toàn bộ request body trong middleware, log query string (chứa token reset password), và log exception message từ provider DB (có thể chứa giá trị tham số). Với exception, log type + message + stack, đừng log ex.ToString() kèm data.
Async và file sink: lợi ích có điều kiện
Serilog.Sinks.Async đưa việc ghi sang một luồng nền có queue. Nó giảm latency của request, nhưng đổi lại:
- Mất log khi crash. Queue chưa flush thì event biến mất. Với log audit, đây là điều không chấp nhận được.
- Queue đầy thì block hoặc drop tùy
blockWhenFull. Mặc định drop — kiểm tra lại nếu bạn cần đảm bảo. - File sink vẫn là I/O. Async chỉ chuyển chi phí sang thread khác; nếu đĩa chậm, queue sẽ đầy.
Thứ tự đúng: .WriteTo.Async(a => a.File(...)) — bọc sink, không bọc cả logger. Và luôn có một sink đồng bộ (thường là console) để log lỗi khởi động vẫn thoát ra được.
Anti-pattern thường gặp
| Sai | Đúng | Lý do |
|---|---|---|
LogError("Payment failed", ex) |
LogError(ex, "Payment failed for {OrderId}", id) |
Exception phải là tham số đầu, nếu không stack trace mất |
Log rồi throw ở mỗi tầng |
Log một lần ở boundary | Một lỗi thành năm dòng log trùng |
{@Request} cho cả object |
Chỉ field cần thiết | Chi phí serialize + PII + log phình |
| Property là chuỗi động mỗi request | Property có tập giá trị hữu hạn | Cardinality cao làm index log nổ |
Tự viết wrapper quanh ILogger |
Dùng template trực tiếp | Wrapper phá message template và source context |
Hướng tới 2027
Serilog 10 và NLog 6 đều ổn định; OpenTelemetry là chuẩn cross-vendor cho trace/metric, còn log vẫn đi qua Serilog/NLog hoặc OTLP. .NET 11 GA tháng 11/2026 (STS) không đổi API logging. Việc đáng làm là chuẩn hóa tên property giữa các service trước khi số lượng service tăng — đổi tên field log sau đó là dự án riêng.
Checklist
- Dùng
CreateBootstrapLogger()+UseSerilog((ctx, svc, cfg) => ...), không cấu hình sauBuild(). - Bật
UseSerilogRequestLoggingmột lần, bỏ các log request thủ công. - Mọi giá trị động đi qua
{PropertyName}; không interpolation. Enrich.FromLogContext+LogContext.PushPropertycho id nghiệp vụ.- Thêm
TraceId/SpanIdtừActivity.Current, thống nhất với OpenTelemetry. - File sink có rolling + retention; container ghi ra stdout.
Destructure.ByTransformingcho mọi type có PII.
Đọc tiếp: cấu hình NLog cho quản lý log nâng cao để so sánh hai lựa chọn; Elasticsearch cho lập trình viên .NET nếu bạn muốn tập trung log vào một search backend; và vòng đời dịch vụ Scoped, Transient, Singleton vì logger trong DI cũng có lifetime.



