Logging و Structured Logging

.NET 10 | ILogger، Event Context و Observability

Logging باید رخدادهای قابل جست‌وجو و دارای Context تولید کند، نه رشته‌های پراکنده. Structured Logging با Template و Propertyهای نام‌دار امکان Filter، Aggregation و همبستگی رخدادها را فراهم می‌کند.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

Logging باید رخدادهای قابل جست‌وجو و دارای Context تولید کند، نه رشته‌های پراکنده. Structured Logging با Template و Propertyهای نام‌دار امکان Filter، Aggregation و همبستگی رخدادها را فراهم می‌کند.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

Logger نوعدار در Service تزریق می‌شود. پیام‌ها از Template ثابت و Valueهای جدا استفاده می‌کنند. Secret، Token، Password و Payload حساس نباید در Log ثبت شوند.

_logger.LogInformation(
    "Creating product {Sku} in category {CategoryId}",
    request.Sku,
    request.CategoryId);

_logger.LogWarning(
    "Product {ProductId} not found. TraceId: {TraceId}",
    id,
    httpContext.TraceIdentifier);

3. سناریوی اجرایی

در یک Request ایجاد Product، شروع عملیات، نتیجه قابل توجه و خطا ثبت می‌شود. Logهای داخل Loop بزرگ به Summary تبدیل می‌شوند تا حجم و هزینه Logging کنترل شود.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

using (_logger.BeginScope(new Dictionary<string, object>
{
    ["Operation"] = "CreateProduct",
    ["RequestId"] = requestId
}))
{
    _logger.LogInformation("Operation started");
    // ...
}

4. اصول طراحی و نگهداری

پیاده‌سازی قابل نگهداری تنها به درست کار کردن در مسیر موفق محدود نیست. مرزهای مسئولیت، قابلیت مشاهده، امنیت، رفتار در خطا و امکان توسعه تدریجی باید هم‌زمان بررسی شوند.

• Template ثابت و Propertyهای معنادار استفاده شود.
• PII و Secret پیش از Logging شناسایی شوند.
• Debug/Trace برای جزئیات زیاد و Information برای رخدادهای عملیاتی استفاده شود.
• Metric و Trace جای Log را نمی‌گیرند؛ هرکدام نقش جدا دارند.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• String interpolation به‌جای Structured Template.
• Log کردن Object کامل Request بدون بررسی Propertyها.
• ثبت Information برای هر Item در Batch بزرگ.
• پیام «Something went wrong» بدون Context.

6. چک‌لیست نهایی فصل

• Levelهای Logging معنی مشخص دارند.
• Logها Structured و قابل جست‌وجو هستند.
• Secretها از Log حذف شده‌اند.
• TraceId یا Correlation در رخدادهای مهم قابل مشاهده است.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.