12 KiB
12 KiB
مشخصات درس‌نامه: ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با 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):
- نقطه کور پروداکشن: «کاربر چه کرد که این باگ رخ داد؟»:
- کاربر دکمه رزرو مشاوره را می‌زند، صفحه لودینگ گیر می‌کند، کاربر پنجره را می‌بندد و شما هرگز نمی‌فهمید چرا!
- لایه اول دیدبانی: لاگ‌های زنده سرور ابری (Server Runtime Logs):
- خواندن خروجی‌های استاندارد (
stdoutوstderr) در تب لاگ‌های لیارا و پنل ورسل. - تفکیک سطوح لاگ‌نویسی:
INFO،WARNوERROR.
- خواندن خروجی‌های استاندارد (
- لایه دوم دیدبانی: شکارچی باگ‌های زنده با Sentry:
- سنتری چیست؟ پلتفرم استاندارد جهانی برای ثبت، گروه‌بندی و تحلیل باگ‌های نرم‌افزار.
- ثبت جزئیات طلایی در هر گزارش خطا:
- ردپای دقیق توابع و شماره خط کد (Stack Trace).
- مدل دستگاه و سیستم‌عامل کاربر، مرورگر و موقعیت جغرافیایی.
- خرده‌نان‌ها یا تاریخچه اقدامات کاربر (Breadcrumbs): مثلاً «کاربر منو را باز کرد
\rightarrowروی دکمه کلیک کرد\rightarrowفیلد تلفن را پر کرد\rightarrowخطا رخ داد».
- راه‌اندازی فوق‌سریع سنتری در Next.js:
- اجرای ویزارد خودکار:
npx @sentry/wizard@latest -i nextjs. - اضافه شدن فایل‌های کانفیگ کلاینت، سرور و لبه به صورت خودکار توسط ویزارد.
- استفاده از
Sentry.captureException(error)داخل بلوک‌های حساسtry/catchدر Server Actions.
- اجرای ویزارد خودکار:
- روش دیباگ خطای پروداکشن با ترکیب گزارش Sentry و ایجنت هوش مصنوعی:
- کپی کردن گزارش سنتری و پرامپت طلایی برای کشف باگ‌های پنهان داده‌های خاص کاربران.
- کال‌اوت‌های آموزشی و هشدار کوئرا:
- کال‌اوت بنفش (
<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/ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
- تصویر کاور درس:
images/cover.png- موضوع: اسکنر تله‌گذار باگ با لوگوی سنتری که خطاهای مخفی کدهای زنده وب را به دام انداخته و در یک داشبورد شفاف نمایش می‌دهد.
- داشبورد بررسی لاگ‌های زنده در کنسول لیارا:
images/liara-app-runtime-logs.png- موضوع: اسکرین‌شات از تب «لاگ‌ها» در پنل لیارا با پیام‌های رنگی درخواست‌های HTTP و خطاهای سرور.
- کالبدشکافی یک گزارش خطا در پنل Sentry:
images/sentry-issue-details-anatomy.png- موضوع: اسکرین‌شات از صفحه یک خطا در سنتری با بخش‌های هایلایت‌شده: استک‌تریس، نام فایل، مشخصات سیستم کاربر و بخش Breadcrumbs.
- چرخه حل باگ پروداکشن با هوش مصنوعی:
images/sentry-ai-debugging-loop.png- موضوع: اینفوگرافیک: وقوع خطا در مرورگر کاربر
\rightarrowثبت در سنتری\rightarrowکپی خلاصه گزارش به ایجنت\rightarrowتولید پچ اصلاحی\rightarrowاستقرار سریع.
- موضوع: اینفوگرافیک: وقوع خطا در مرورگر کاربر
۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)
- تیتر اصلی:
# ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با Sentry و کنسول‌های ابری - مقدمه: وقتی کاربری در آن سوی دنیا با یک باگ مواجه می‌شود و بدون یک کلمه اعتراض سایت را می‌بندد، چگونه باگ او را در کسری از ثانیه روی مانیتور خود ببینیم؟
- جدول کاور درس
- استعاره جعبه سیاه هواپیما:
- ثبت تک‌تک حرکات خلبان و شرایط جوی تا در صورت بروز هر سانحه، علت ریشه‌ای بلافاصله مشخص شود.
- پایش لایه اول: خواندن لاگ‌های سرور در لیارا و Vercel:
- چطور لاگ‌های زنده ترمینال سرور را روی مرورگر رصد کنیم و سطوح لاگ‌ها را تفکیک نماییم.
- پایش لایه دوم: نصب و راه‌اندازی شکاری باگ‌های سنتری (Sentry):
- ساخت پروژه در sentry.io و اجرای ویزارد خودکار Next.js در ترمینال.
- کالبدشکافی گزارش باگ در سنتری: قدرت شگفت‌انگیز Breadcrumbs:
- دیدن گام‌های کاربر ثانیه‌هایی قبل از وقوع خطا (کلیک‌ها، ورودی‌ها، روت‌ها).
- به‌دام‌اندازی خطاهای پنهان در توابع حساس پورتفولیو:
- ایمن‌سازی روت‌های پرداخت زرین‌پال، ارسال پیامک و چت‌بات با
Sentry.captureException.
- ایمن‌سازی روت‌های پرداخت زرین‌پال، ارسال پیامک و چت‌بات با
- جعبه پرامپت طلایی: تحلیل گزارش خطای سنتری توسط ایجنت:
- پرامپت دقیق:
«من این گزارش خطا را از سنتری پروداکشن دریافت کرده‌ام: [کپی استک‌تریس و بردکرامب‌ها]. لطفاً ۱) علت بروز خطا را توضیح بده، ۲) مشخص کن این باگ تحت چه سناریوی نادری رخ داده است، و ۳) کد اصلاحی تاب‌آور (Defensive) به همراه تست اعتبارسنجی ارائه بده.»
- پرامپت دقیق:
- باکس نکته Quera (
<details class="violet">): ماجرای امنیت و حریم خصوصی داده‌ها در سنتری؛ خیالتان راحت باشد، توکن‌ها و اطلاعات کارت به صورت خودکار ستاره‌دار ([Filtered]) می‌شوند. - باکس هشدار Quera (
<details class="red">): لاگ‌های اضافه و حجیم در پروداکشن ننویسید؛ چاپ بیهوده هزاران خط در هر ثانیه به هدررفت منابع و هزینه سرور می‌انجامد. - باکس رضایت‌بخش Quera (
<details class="green">): ایجاد یک خطای عمدی آزمایشی در سایت و مشاهده ظاهر شدن آن در داشبورد سنتری در کمتر از ۳ ثانیه. - جمع‌بندی درس‌نامه: تجهیز کامل سیستم به جعبه سیاه عیب‌یابی؛ ورود به مبحث به‌روزرسانی‌های امنیتی و ارتقای دوره‌ای پکیج‌ها در درس بعدی.
۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- نقطه کور پروداکشن و ضرورت ثبت لاگ‌ها و ردگیری خطاها به روشنی تبیین شود.
- تفاوت میان لاگ‌های سرور (لیارا/ورسل) با سرویس‌های Error Tracking (سنتری) تشریح گردد.
- راه‌اندازی گام‌به‌گام سنتری در Next.js به همراه مفاهیم Breadcrumbs آموزش داده شود.
- پرامپت دیباگ خطای پروداکشن با استفاده از لاگ‌های سنتری ارائه شود.