107 lines
12 KiB
Markdown
107 lines
12 KiB
Markdown
# مشخصات درس‌نامه: ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با 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 آموزش داده شود.
|
||
- [ ] پرامپت دیباگ خطای پروداکشن با استفاده از لاگ‌های سنتری ارائه شود.
|