سطح‌های لاگ به زبان ساده: DEBUG، INFO، WARN، ERROR و FATAL.

سطح‌های لاگ وجود دارن تا بشه سیل پیام‌ها رو به چیزی تبدیل کرد که قابل جستجو، فیلتر و هشداردهی باشه. اگه درست استفاده بشن، می‌تونید محیط تولید رو روی INFO اجرا کنید و هنوز همون یه ERROR مهم رو پیدا کنید. اگه بی‌دقت استفاده بشن، همه‌ی پیام‌ها «info» هستن و هر جستجوی لاگ یه پروژه‌ی باستان‌شناسیه.

نکته‌های کلیدی

• سطح‌ها پیام‌ها رو بر اساس اهمیت مرتب می‌کنن: TRACE < DEBUG < INFO < WARN < ERROR < FATAL.
• محیط تولید معمولاً INFO و بالاتر رو لاگ می‌کنه؛ DEBUG موقتی روشن می‌شه.
• ERROR یعنی چیزی شکست خورده که یکی باید نگاهش کنه؛ نه یه وضعیت قابل انتظار.
• WARN برای «غیرمنتظره ولی مدیریت‌شده» است؛ اگه کسی هیچ‌وقت روی یه warning کاری نمی‌کنه، اون INFO است.
• روی نرخ ERROR/FATAL هشدار بدید، نه روی تک‌خط‌ها.

سطح‌ها

اسم‌ها بین زبان‌ها و کتابخانه‌ها کمی فرق می‌کنن (WARNING یا WARN، CRITICAL یا FATAL)، ولی ترتیب همه‌جا یکیه.

انتخاب سطح درست

بپرسید کی باید این پیام رو بخونه و کی:

• هیچ‌کس، مگر موقع عیب‌یابی: DEBUG.
• یه اپراتور که داره مرور می‌کنه چی شد: INFO.
• یکی، بالاخره، اگه تکرار بشه: WARN.
• یکی، به‌زودی: ERROR.
• یکی، همین الان، و سرویس قطعه: FATAL.

اشتباه‌های رایج

• لاگ کردن وضعیت‌های قابل انتظار به‌عنوان ERROR. کاربری که رمز اشتباه وارد می‌کنه خطای سیستم شما نیست؛ INFO است (یا یه متریک امنیتی).
• قورت دادن خطا به‌عنوان WARN. اگه عملیات شکست خورده و کاربر شکست رو دیده، ERROR است.
• DEBUG پیش‌فرض در محیط تولید. حجم و هزینه‌ی لاگ رو چند برابر می‌کنه و ممکنه داده‌ی حساس رو لو بده.
• لاگ کردن یه خطا در همه‌ی لایه‌ها. یه بار لاگش کنید، همون‌جایی که مدیریت می‌شه، با زمینه‌ی کامل.

هر خط چی باید داشته باشه؟

سطح به‌تنهایی کافی نیست. خط‌های مفید این‌ها رو دارن:

• زمان با منطقه‌ی زمانی (ترجیحاً UTC)،
• سطح،
• اسم سرویس یا ماژول،
• شناسه‌ی درخواست یا correlation ID که خط‌های یه درخواست رو به هم وصل کنه،
• پیام و فیلدهای کلیدی (شناسه‌ی کاربر، شناسه‌ی سفارش؛ هیچ‌وقت رمز یا توکن).

2026-10-18T09:14:03.211Z ERROR payments req=7f3c2a order=58114 msg="gateway timeout" duration_ms=10002

لاگ ساخت‌یافته (JSON) این فیلدها رو قابل جستجو می‌کنه؛ لاگ ساخت‌یافته رو ببینید.

سطح در هر محیط

سطح رو حین اجرا قابل تنظیم کنید (متغیر محیطی یا بارگذاری دوباره‌ی تنظیمات) تا بتونید موقع بررسی، جزئیات یه جزء رو بدون دیپلوی جدید بالا ببرید.

سطح‌ها و هشداردهی

برای هر خط ERROR کسی رو خبر نکنید؛ یه درخواست ناموفق بین هزاران درخواست رخداد نیست. روی این‌ها هشدار بدید:

• نرخ خطا (مثلاً بیشتر از ۱٪ درخواست‌ها در پنج دقیقه)،
• هر FATAL،
• خطاهای مشخصی که همیشه اقدام لازم دارن (بکاپ شکست خورد، تمدید گواهی شکست خورد).

لاگ‌ها می‌گن چرا چیزی خراب شد؛ مانیتورینگ آپتایم بیرونی، به‌طور مستقل، می‌گه کاربرها نمی‌تونن وارد بشن؛ حتی وقتی برنامه اون‌قدر خرابه که نمی‌تونه چیزی لاگ کنه.

پرسش‌های پرتکرار

• در محیط تولید INFO لاگ کنم یا DEBUG؟

  +

  INFO. DEBUG رو موقتی روشن کنید، ترجیحاً فقط برای جزئی که دارید بررسیش می‌کنید.

• اصلاً WARN به درد می‌خوره؟

  +

  بله، برای وضعیت‌هایی که مشکل رو پیش‌بینی می‌کنن: تلاش‌های دوباره، وابستگی‌های کند، منابعی که دارن تموم می‌شن. اگه کسی هیچ‌وقت warningها رو نگاه نمی‌کنه، اون‌ها رو به INFO تنزل بدید یا به متریک تبدیلشون کنید.

• لاگ‌ها رو چقدر نگه داریم؟

  +

  به هزینه و قوانین بستگی داره. یه تنظیم رایج لاگ‌های جزئی رو ۷ تا ۳۰ روز و متریک‌های تجمیعی رو خیلی بیشتر نگه می‌داره.