vibe-coding-college-specs/chapters/13-product-maintenance/01-lesson-observability-and-monitoring/spec.md

مشخصات درس‌نامه: مشاهده‌پذیری و مانیتورینگ منابع سرور (Observability & Monitoring)

• شناسه در سیلابس: L13.2
• فصل: فصل ۱۳: نگهداری محصول (Ch 13)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۶ دقیقه
• پیش‌نیازهای مستقیم: L13.1 (اهداف فصل سیزدهم)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): تفاوت میان «مانیتورینگ ساده» (آیا سرور بالاست؟) با «مشاهده‌پذیری عمیق» (چرا حافظه رم پر شده و کدام روت باعث کندی است؟) را شرح دهد.
• تحلیل/ارزیابی کند (Evaluate): چهار سیگنال طلایی پایداری نرم‌افزار (تأخیر Latency، ترافیک Traffic، نرخ خطا Errors، و درجه اشباع منابع Saturation) را در داشبوردهای ابری تحلیل کند.
• به‌کار ببندد (Apply): نمودارهای زنده‌ی مصرف حافظه (RAM)، پردازنده (CPU)، دیسک، و اتصالات فعال دیتابیس Supabase را در پنل‌های لیارا و ورسل بازرسی و مدیریت نماید.
• ایجاد کند (Create): راهکارهای برطرف‌سازی نشت حافظه (Memory Leaks) در روت‌های Next.js را با کمک ابزارهای بهینه‌سازی شناسایی کند.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. استعاره علائم حیاتی بیمار در اتاق مراقبت‌های ویژه (ICU):
   • پزشک تنها به زنده بودن بیمار نگاه نمی‌کند؛ فشار خون، ضربان قلب و اکسیژن خون را رصد می‌کند.
2. چهار سیگنال طلایی گوگل برای ارزیابی سلامت سیستم‌ها (Four Golden Signals):
   • ۱. تاخیر (Latency): مدت زمانی که طول می‌کشد تا سرور به درخواست کاربر پاسخ دهد (بررسی شاخص‌های p50 و p95).
   • ۲. ترافیک (Traffic): حجم تقاضا و تعداد درخواست‌های وارده در ثانیه/دقیقه.
   • ۳. نرخ خطا (Errors): درصد درخواست‌هایی که با کدهای خطای ۵۰۰ یا ۴۰۰ شکست می‌خورند در مقایسه با پاسخ‌های ۲۰۰ موفق.
   • ۴. درجه اشباع (Saturation): درصد مصرف منابع محدود سرور (رم، پردازنده، دیسک، تعداد اتصالات استخر دیتابیس).
3. رصد زنده منابع در کنسول پلتفرم ابری لیارا:
   • نمودارهای لحظه‌ای پردازنده (CPU) و رم (Memory) در داشبورد برنامه پورتفولیو.
   • تشخیص وضعیت کرش ناشی از کمبود رم (Out of Memory - OOM) و نحوه ارتقای اندازه پلن یا ری‌استارت کانتینر.
4. رصد متریک‌ها در داشبورد Vercel:
   • مشاهده درصد درخواست‌های کش‌شده در لبه (Edge Cache Hit Ratio) و تاخیر توابع سرورلس.
5. رصد شاخص‌های پایگاه داده در کنسول Supabase:
   • تعداد کانکشن‌های باز به PostgreSQL و اطمینان از بسته شدن مناسب اتصالات در Server Actions.
6. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): مفهوم شاخص صدک ۹۵ام (p95 Latency)؛ چرا بررسی «میانگین» گول‌زننده است و تاخیر کندترین ۵ درصد کاربران را پنهان می‌کند.
   • کال‌اوت سبز (<details class="green">): مشاهده نمودار مصرف رم لیارا در مقیاس مگابایت که برای پورتفولیو معمولاً زیر ۱۵۰ مگابایت بسیار پایدار است.
   • کال‌اوت قرمز (<details class="red">): خطر نشت حافظه (Memory Leak)؛ ذخیره آرایه‌های غول‌پیکر در متغیرهای سراسری خارج از توابع که سرور را وادار به ریستارت مداوم می‌کند.

آنچه نباید وارد آن شویم (Out-of-Scope):

• نصب سیستم‌های پیچیده پایش کلاستری Prometheus و Grafana.
• تنظیمات شبکه SDN دیتاسنترها.

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Golden Signals	سیگنال‌های طلایی سلامت	چهار معیار کلیدی سنجش عملکرد و قابلیت اطمینان سیستم‌های نرم‌افزاری تحت شبکه
Latency (p95)	تاخیر صدک نود و پنج	حداکثر زمانی که طول می‌کشد تا ۹۵٪ کاربران پاسخ درخواست خود را دریافت کنند
Saturation	اشباع منابع	میزان پر بودن یا نزدیک شدن ظرفیت پردازنده، حافظه یا شبکه به سقف ۱۰۰ درصدی
Memory Leak	نشت حافظه	باگی که در آن حافظه اشغال‌شده پس از اتمام کار آزاد نشده و سرور را به سمت کرش OOM می‌برد
OOM (Out of Memory)	خطای اتمام حافظه	وضعیتی که سیستم‌عامل به دلیل پر شدن ۱۰۰٪ رم، فرآیند اجرای برنامه را اجباراً متوقف می‌کند
Connection Pooling	استخر اتصالات دیتابیس	مدیریت اشتراکی کانکشن‌های پایگاه داده برای جلوگیری از باز شدن صدها اتصال همزمان سنگین

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: مانیتورهای نئونی مدرن با نمودارهای ضربان قلب دیجیتال، مصرف رم و پردازنده و عقربه‌های سرعت لود صفحات.
2. چهار سیگنال طلایی سلامت سیستم: images/four-golden-signals-infographic.png
   • موضوع: اینفوگرافیک ۴ گانه: تاخیر (کرنومتر)، ترافیک (موج ورودی)، خطا (آیکون ارور قرمز)، و اشباع (گیج نشانگر رم و سی‌پی‌یو).
3. نمودارهای مصرف منابع در داشبورد لیارا: images/liara-metrics-graphs.png
   • موضوع: اسکرین‌شات از پنل پایش لیارا با خطوط نمودار مصرف رم و پردازنده بر حسب درصد و مگابایت در طول ۲۴ ساعت.
4. داشبورد متریک‌های پایگاه داده Supabase: images/supabase-database-metrics.png
   • موضوع: اسکرین‌شات از بخش Database Metrics در سوپابیس با نمودار کانکشن‌های فعال و فضای اشغال‌شده دیسک.

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # مشاهده‌پذیری و مانیتورینگ منابع سرور (Observability & Monitoring)
2. مقدمه: سایت بالا آمد؛ اما چگونه مثل یک پزشک متخصص، ضربان قلب و علائم حیاتی سرور خود را از راه دور رصد کنیم؟
3. جدول کاور درس
4. استعاره رانندگی با سرعت ۲۰۰ کیلومتر با داشبورد خاموش!
   • اگر عقربه بنزین، دمای آب و سرعت‌سنج نباشد، هر لحظه منتظر انفجار موتور باشید.
5. معرفی ۴ سیگنال طلایی گوگل برای سنجش پایداری وب:
   • تاخیر (Latency)، ترافیک (Traffic)، خطاها (Errors)، و اشباع منابع (Saturation).
6. خوانش نمودارهای مصرف در پلتفرم ابری لیارا:
   • بررسی رم و پردازنده؛ چه موقع سرور زیر بار کم می‌آورد و نیاز به افزایش پلن دارد؟
7. کالبدشکافی خطای مرگبار Out of Memory (OOM):
   • چرا رم سرور پر می‌شود و چطور با کدهای استاندارد از نشت حافظه جلوگیری کنیم؟
8. پایش اتصالات پایگاه داده در Supabase:
   • مفهوم Connection Pooling و جلوگیری از قفل شدن دیتابیس توسط اکشن‌های سرور.
9. باکس نکته Quera (<details class="violet">): جادوی شاخص صدک ۹۵ام (p95)؛ چرا میانگین‌ها دروغ می‌گویند و تاخیر افراد با اینترنت ضعیف را پنهان می‌کنند.
10. باکس هشدار Quera (<details class="red">): هرگز فایل‌های بزرگ یا استریم‌های ویدیویی را بدون کش روی سرور اصلی پردازش نکنید؛ فشار آنی پردازنده مساوی با قطع سایت خواهد بود.
11. باکس رضایت‌بخش Quera (<details class="green">): تماشای نمودارهای آرام و سبز مصرف منابع پورتفولیو پس از استقرار موفق و پایدار.
12. جمع‌بندی درس‌نامه: تسلط بر پایش منابع سرور؛ ورود به مبحث حیاتی هشدارهای زنده و سیستم اعلان آپتایم ۲۴ ساعته در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• تمایز میان Monitoring سطحی و Observability عمیق تبیین شود.
• سیگنال‌های چهارگانه طلایی به همراه شاخص‌های آماری نظیر p95 تشریح گردند.
• نحوه خواندن داشبوردهای مصرف منابع در لیارا و ورسل آموزش داده شود.
• مفهوم خطای OOM و روش‌های پیشگیری از نشت حافظه لحاظ گردد.