‏چطور یه لاگ ساختارمند بنویسیم

نویسنده که وقت زیادی رو با کاربرهای لاگ Sentry می‌گذرونه، می‌گه چیزی که یه لاگ رو ساختارمند می‌کنه صرفا چسبوندن یه شیء JSON دلخواه به پیام نیست؛ باید با لاگ‌ها مثل دادهٔ واقعی برنامه رفتار کنیم که بشه جست‌وجو، فیلتر و تجمیعشون کرد. مهم‌تر از خودِ قرارداد، اینه که یه الگو رو انتخاب کنی و ثابت بهش پایبند بمونی.

به گفتهٔ نویسنده، اسم رویداد باید ثابت و کم‌تنوع باشه و از الگوی domain.action پیروی کنه، مثل auth.login یا payment.capture. دادهٔ پویا مثل نام کاربر نباید بره تو پیام، چون هر ورود موفق یه رویداد متفاوت می‌سازه و جست‌وجو و هشدار رو سخت می‌کنه. یه نمونهٔ خوب این‌شکلیه:

logger.info('auth.login', {
  'auth.result': 'succeeded',
  'user.uuid': user.uuid,
  'user.plan.tier': user.plan.tier,
});

برای صفت‌ها هم همون سبک نقطه‌ای رو پیشنهاد می‌ده، ولی با یه نگاه متفاوت: اسم رویداد «کنش»‌ه و کلید صفت «بُعد». هر کلید مثل payment.failure.reason_code یه سوال آینده‌ست که داری جوابش رو ارزون می‌کنی. نویسنده تأکید می‌کنه مقدارها رو ساده نگه دار (رشته، عدد، بولین و آرایه‌ای از همینا) و از لاگ کردن شیءهای تو در تو یا آبجکت کاملِ request و response پرهیز کن.

یه توصیهٔ دیگه‌ش اینه که واحد رو تو اسم صفت عددی بیار؛ size مبهمه ولی size_bytes مفیده. نویسنده می‌گه بعد از این‌که الگو رو پیدا کردی، با یه linter (مثلا یه پلاگین شخصی ESLint) الگو رو نگه دار تا هم لاگ‌ها ثابت بمونن هم عامل‌های هوش مصنوعی بهتر کار کنن. آخرش یادآوری می‌کنه که linter شکل لاگ رو می‌گیره، ولی این‌که یه فیلد مهم جا افتاده یا نه، هنوز به قضاوت آدم نیاز داره.

نکات کلیدی:

• اسم رویداد ثابت و کم‌تنوع با الگوی domain.action
• کلیدهای صفت تخت و نقطه‌ای مثل payment.result
• مقدارها فقط ساده: رشته، عدد، بولین و آرایهٔ همینا
• واحد رو تو اسم صفت عددی بیار (size_bytes نه size)
• الگو رو با linter ثابت نگه دار