آموزش مهاجرت از Sentry به دیدبان بدون از دست دادن خطاها
راهنمای مرحلهبهمرحله مهاجرت از Sentry به دیدبان؛ از اجرای همزمان و تنظیم release تا آپلود Source Map و نصب Agent سرور، بدون ایجاد نقطه کور در مانیتورینگ.
چرا مهاجرت باید مرحلهای باشد؟
خاموشکردن ناگهانی ابزار قبلی ممکن است بین دو سامانه یک نقطه کور ایجاد کند. روش امنتر این است که برای چند روز Sentry و دیدبان را همزمان اجرا کنید، کیفیت رخدادها را بسنجید و بعد مسیر قدیمی را کنار بگذارید.
پیش از شروع، این موارد را مشخص کنید:
محیطهای production و staging
نام اپلیکیشن و مالک فنی آن
قالب ثابت release، ترجیحاً Git commit SHA یا نسخه تصویر Docker
خطاها و هشدارهای مهمی که نباید از دست بروند
سیاست حذف یا ماسککردن دادههای حساس
مرحله اول: ساخت اپلیکیشن و اتصال SDK
در پنل دیدبان یک سازمان و اپلیکیشن بسازید و توکن SDK را فقط در متغیر محیطی امن نگه دارید. سپس SDK را در ورودی اصلی برنامه فعال کنید. مقدار release باید برای هر build تغییر کند و با نسخهای که در CI استفاده میشود دقیقاً یکسان باشد.
typeScript:
```ts Didban.init({ apiKey: process.env.DIDBAN_API_KEY, appName: 'checkout-web', config: { release: process.env.APP_RELEASE, }, }); ```
ابتدا این تغییر را در staging منتشر کنید و یک خطای کنترلشده بفرستید. پیام، stack trace، صفحه، مرورگر و breadcrumbهای قبل از خطا را در پنل بررسی کنید.
مرحله دوم: Source Map هر Release را آپلود کنید
کد production معمولاً minify میشود و stack trace به فایلهایی مانند `app.min.js:1` اشاره میکند. برای بازگشت به فایل و خط اصلی باید Source Map همان release در دیدبان قرار بگیرد.
در CI یک توکن محدود `source_maps:write` بسازید و بعد از build و پیش از deploy اجرا کنید:
```bash npx @getdidban/cli sourcemaps upload \ --directory dist \ --release "$GITHUB_SHA" \ --url-prefix /assets \ --delete-after-upload ```
گزینه حذف، فایلهای map را فقط بعد از موفقیت همه آپلودها پاک میکند؛ بنابراین Source Map وارد خروجی عمومی نمیشود. توکن CI را در Secretهای pipeline نگه دارید، نه داخل مخزن.
مرحله سوم: رخدادهای دو سامانه را مقایسه کنید
در یک بازه چندروزه چند نمونه واقعی را مقایسه کنید:
1. آیا تعداد خطاهای مهم نزدیک است؟ 2. آیا release و environment درست ثبت میشوند؟ 3. آیا Source Map فایل و خط اصلی را نشان میدهد؟ 4. آیا اطلاعات حساس حذف یا ماسک شدهاند؟ 5. آیا اعضای تیم به پروژه درست دسترسی دارند؟ 6. آیا اعلانهای موردنیاز به مقصد مناسب میرسند؟
هدف برابرکردن عدد خام رخدادها نیست؛ تفاوت در sampling، فیلتر و گروهبندی طبیعی است. مهم این است که خطاهای حیاتی و زمینه لازم برای رفع آنها از دست نرود.
مرحله چهارم: سرورهای backend را متصل کنید
برای سرویسهای Node.js، ASP.NET Core، workerها و APIها میتوانید Server Agent دیدبان را روی هر سرور نصب کنید. سرورها به سازمان متصل میشوند و متناسب با پلن میتوان بین چند سرور جابهجا شد.
برای خطاهای شبکه و سرور، دیدبان یک پنجره کوتاه و کمحجم از CPU، RAM و Load اطراف زمان خطا نگه میدارد. خط قرمز روی نمودار زمان رخداد را مشخص میکند تا همزمانی خطا با فشار منابع قابل بررسی باشد.
مرحله پنجم: جابهجایی نهایی
وقتی چند release بدون مشکل ثبت شد، ابتدا اعلانهای Sentry را کم کنید اما دریافت رخداد را برای یک بازه کوتاه نگه دارید. سپس ارسال رخداد به Sentry را متوقف کنید و داشبورد قدیمی را تا پایان دوره بازبینی فقطخواندنی نگه دارید.
در پایان، توکنهای بلااستفاده را لغو، مستندات داخلی تیم را بهروز و یک تست خطای کنترلشده در چکلیست هر انتشار اضافه کنید.
جمعبندی
مهاجرت خوب یک تعویض ناگهانی نیست؛ یک انتقال قابل اندازهگیری است. اجرای همزمان کوتاه، release یکسان، Source Map خودکار و بررسی رخداد واقعی باعث میشود دیدبان بدون از دست رفتن پوشش خطا وارد جریان توسعه تیم شود.