# مشخصات درس‌نامه: ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با Sentry و کنسول‌های ابری
- **شناسه در سیلابس:** `L13.4`
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
- **پیش‌نیازهای مستقیم:** `L13.3` (سامانه‌های پایش آپتایم و هشدارهای تلگرام)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** نقطه کور بزرگ محیط پروداکشن را بشناسد؛ جایی که بر خلاف لوکال، هیچ خطای قرمزی روی مانیتور شما چاپ نمی‌شود و کاربران در سکوت با خطا مواجه شده و سایت را ترک می‌کنند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ساختار سیستم ردگیری خطای حرفه‌ای **Sentry** و تفاوت لاگ‌های ساده کنسول (Server Logs در لیارا/ورسل) را با ثبت عمیق ردپا (Breadcrumbs) و استک‌تریس زنده ارزیابی کند.
- [ ] **به‌کار ببندد (Apply):** پکیج `@sentry/nextjs` را در پروژه پورتفولیو راه‌اندازی کرده و خطاهای ثبت‌نشده در کلاینت، سرور و تراکنش‌های زرین‌پال/پیامک را به صورت خودکار به دام بیندازد.
- [ ] **ایجاد کند (Create):** یک جریان دیباگ سریع با ایجنت بسازد که با دریافت گزارش تفصیلی خطای سنتری، ریشه باگ پروداکشن را در کمتر از ۱۰ دقیقه شناسایی و پچ امنیتی ارائه دهد.

---

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

### آنچه باید پوشش داده شود (In-Scope):
1. **نقطه کور پروداکشن: «کاربر چه کرد که این باگ رخ داد؟»:**
   * کاربر دکمه رزرو مشاوره را می‌زند، صفحه لودینگ گیر می‌کند، کاربر پنجره را می‌بندد و شما هرگز نمی‌فهمید چرا!
2. **لایه اول دیدبانی: لاگ‌های زنده سرور ابری (Server Runtime Logs):**
   * خواندن خروجی‌های استاندارد (`stdout` و `stderr`) در تب لاگ‌های لیارا و پنل ورسل.
   * تفکیک سطوح لاگ‌نویسی: `INFO`، `WARN` و `ERROR`.
3. **لایه دوم دیدبانی: شکارچی باگ‌های زنده با Sentry:**
   * سنتری چیست؟ پلتفرم استاندارد جهانی برای ثبت، گروه‌بندی و تحلیل باگ‌های نرم‌افزار.
   * ثبت جزئیات طلایی در هر گزارش خطا:
     - ردپای دقیق توابع و شماره خط کد (Stack Trace).
     - مدل دستگاه و سیستم‌عامل کاربر، مرورگر و موقعیت جغرافیایی.
     - خرده‌نان‌ها یا تاریخچه اقدامات کاربر (Breadcrumbs): مثلاً «کاربر منو را باز کرد $\rightarrow$ روی دکمه کلیک کرد $\rightarrow$ فیلد تلفن را پر کرد $\rightarrow$ خطا رخ داد».
4. **راه‌اندازی فوق‌سریع سنتری در Next.js:**
   * اجرای ویزارد خودکار: `npx @sentry/wizard@latest -i nextjs`.
   * اضافه شدن فایل‌های کانفیگ کلاینت، سرور و لبه به صورت خودکار توسط ویزارد.
   * استفاده از `Sentry.captureException(error)` داخل بلوک‌های حساس `try/catch` در Server Actions.
5. **روش دیباگ خطای پروداکشن با ترکیب گزارش Sentry و ایجنت هوش مصنوعی:**
   * کپی کردن گزارش سنتری و پرامپت طلایی برای کشف باگ‌های پنهان داده‌های خاص کاربران.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): مفهوم حریم خصوصی و فیلتر خودکار دیتای حساس (Data Scrubbing)؛ سنتری به صورت پیش‌فرض رمزها و اطلاعات کارت بانکی را از لاگ‌ها ماسک می‌کند.
   * کال‌اوت سبز (`<details class="green">`): سهمیه رایگان سخاوتمندانه ماهیانه ۵۰۰۰ خطا در پلن توسعه‌دهنده سنتری.
   * کال‌اوت قرمز (`<details class="red">`): پاک‌سازی کدهای `console.log("Password:", pass)` قبل از انتشار؛ هرگز اطلاعات محرمانه را در کنسول چاپ نکنید.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- مباحث Enterprise پرفورمنس ردیابی توزیع‌شده چندسروری (Distributed Tracing در مقیاس‌های میلیونی).
- نوشتن افزونه‌های اختصاصی C++ برای هسته سنتری.

---

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

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Error Tracking | ردگیری و تله‌گذاری خطا | پایش، جمع‌آوری و گروه‌بندی خودکار خطاهای کلاینت و سرور به همراه زمینه وقوع حادثه |
| Sentry | پلتفرم سنتری | مطرح‌ترین سرویس مانیتورینگ خطا و مشاهده‌پذیری پایداری کد در برنامه‌های وب و موبایل |
| Breadcrumbs | ردپاها / خرده‌نان‌های اقدام | سلسله‌مراتب گام‌به‌گام اقداماتی که کاربر پیش از رخ دادن باگ در صفحه انجام داده است |
| Unhandled Exception | استثنای مدیریت‌نشده | خطایی غیرمنتظره در کد که در بلوک try/catch مهار نشده و موجب اختلال در اجرای برنامه می‌شود |
| Data Scrubbing | پاک‌سازی خودکار دیتای حساس | فیلتر کردن رمزهای عبور، شماره کارت و اطلاعات هویتی از گزارش‌های خطا برای حفظ حریم خصوصی |
| Structured Logging | لاگ‌نویسی ساختاریافته | ثبت پیام‌های سیستمی با فرمت منظم (مانند JSON) به همراه زمان دقیق و سطح اهمیت پیام |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** اسکنر تله‌گذار باگ با لوگوی سنتری که خطاهای مخفی کدهای زنده وب را به دام انداخته و در یک داشبورد شفاف نمایش می‌دهد.
2. **داشبورد بررسی لاگ‌های زنده در کنسول لیارا:** `images/liara-app-runtime-logs.png`
   * **موضوع:** اسکرین‌شات از تب «لاگ‌ها» در پنل لیارا با پیام‌های رنگی درخواست‌های HTTP و خطاهای سرور.
3. **کالبدشکافی یک گزارش خطا در پنل Sentry:** `images/sentry-issue-details-anatomy.png`
   * **موضوع:** اسکرین‌شات از صفحه یک خطا در سنتری با بخش‌های هایلایت‌شده: استک‌تریس، نام فایل، مشخصات سیستم کاربر و بخش Breadcrumbs.
4. **چرخه حل باگ پروداکشن با هوش مصنوعی:** `images/sentry-ai-debugging-loop.png`
   * **موضوع:** اینفوگرافیک: وقوع خطا در مرورگر کاربر $\rightarrow$ ثبت در سنتری $\rightarrow$ کپی خلاصه گزارش به ایجنت $\rightarrow$ تولید پچ اصلاحی $\rightarrow$ استقرار سریع.

---

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

1. **تیتر اصلی:** `# ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با Sentry و کنسول‌های ابری`
2. **مقدمه:** وقتی کاربری در آن سوی دنیا با یک باگ مواجه می‌شود و بدون یک کلمه اعتراض سایت را می‌بندد، چگونه باگ او را در کسری از ثانیه روی مانیتور خود ببینیم؟
3. **جدول کاور درس**
4. **استعاره جعبه سیاه هواپیما:**
   * ثبت تک‌تک حرکات خلبان و شرایط جوی تا در صورت بروز هر سانحه، علت ریشه‌ای بلافاصله مشخص شود.
5. **پایش لایه اول: خواندن لاگ‌های سرور در لیارا و Vercel:**
   * چطور لاگ‌های زنده ترمینال سرور را روی مرورگر رصد کنیم و سطوح لاگ‌ها را تفکیک نماییم.
6. **پایش لایه دوم: نصب و راه‌اندازی شکاری باگ‌های سنتری (Sentry):**
   * ساخت پروژه در sentry.io و اجرای ویزارد خودکار Next.js در ترمینال.
7. **کالبدشکافی گزارش باگ در سنتری: قدرت شگفت‌انگیز Breadcrumbs:**
   * دیدن گام‌های کاربر ثانیه‌هایی قبل از وقوع خطا (کلیک‌ها، ورودی‌ها، روت‌ها).
8. **به‌دام‌اندازی خطاهای پنهان در توابع حساس پورتفولیو:**
   * ایمن‌سازی روت‌های پرداخت زرین‌پال، ارسال پیامک و چت‌بات با `Sentry.captureException`.
9. **جعبه پرامپت طلایی: تحلیل گزارش خطای سنتری توسط ایجنت:**
   * پرامپت دقیق:
     > «من این گزارش خطا را از سنتری پروداکشن دریافت کرده‌ام: [کپی استک‌تریس و بردکرامب‌ها]. لطفاً ۱) علت بروز خطا را توضیح بده، ۲) مشخص کن این باگ تحت چه سناریوی نادری رخ داده است، و ۳) کد اصلاحی تاب‌آور (Defensive) به همراه تست اعتبارسنجی ارائه بده.»
10. **باکس نکته Quera (`<details class="violet">`):** ماجرای امنیت و حریم خصوصی داده‌ها در سنتری؛ خیالتان راحت باشد، توکن‌ها و اطلاعات کارت به صورت خودکار ستاره‌دار (`[Filtered]`) می‌شوند.
11. **باکس هشدار Quera (`<details class="red">`):** لاگ‌های اضافه و حجیم در پروداکشن ننویسید؛ چاپ بیهوده هزاران خط در هر ثانیه به هدررفت منابع و هزینه سرور می‌انجامد.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** ایجاد یک خطای عمدی آزمایشی در سایت و مشاهده ظاهر شدن آن در داشبورد سنتری در کمتر از ۳ ثانیه.
13. **جمع‌بندی درس‌نامه:** تجهیز کامل سیستم به جعبه سیاه عیب‌یابی؛ ورود به مبحث به‌روزرسانی‌های امنیتی و ارتقای دوره‌ای پکیج‌ها در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] نقطه کور پروداکشن و ضرورت ثبت لاگ‌ها و ردگیری خطاها به روشنی تبیین شود.
- [ ] تفاوت میان لاگ‌های سرور (لیارا/ورسل) با سرویس‌های Error Tracking (سنتری) تشریح گردد.
- [ ] راه‌اندازی گام‌به‌گام سنتری در Next.js به همراه مفاهیم Breadcrumbs آموزش داده شود.
- [ ] پرامپت دیباگ خطای پروداکشن با استفاده از لاگ‌های سنتری ارائه شود.