Sentry چیست و چطور کار می‌کند

Sentry چیست و چطور کار می‌کند
در این مقاله می‌خوانید
  1. مسئله‌ای که حل می‌کند
  2. چطور کار می‌کند
  3. ۱. SDK نصب می‌شود
  4. ۲. قلاب‌ها نصب می‌شوند
  5. ۳. زمینه جمع می‌شود
  6. ۴. رویداد ارسال می‌شود
  7. ۵. سرور گروه‌بندی می‌کند
  8. ۶. Source map اعمال می‌شود
  9. مفاهیمی که باید بشناسید
  10. وقتی گروه‌بندی پیش‌فرض اشتباه می‌کند
  11. قابلیت‌های فراتر از خطا
  12. ردیابی کارایی و Session Replay در عمل
  13. چه داده‌ای جمع می‌کند
  14. سه اشتباه رایج در راه‌اندازی
  15. آپلود Source Map در عمل
  16. هزینه و مدل قیمت
  17. برای تیم ایرانی
  18. Self-hosted یا نسخهٔ ابری
  19. آیا Sentry برای شما مناسب است؟
  20. منابع و مطالعهٔ بیشتر

Sentry شناخته‌شده‌ترین ابزار رصد خطا در دنیاست و برای بسیاری از تیم‌ها مترادف خودِ مفهوم شده است. اگر تازه با این حوزه آشنا می‌شوید، فهمیدن اینکه Sentry چه می‌کند و چطور کار می‌کند، بهترین نقطهٔ شروع است — حتی اگر در نهایت ابزار دیگری انتخاب کنید.

مسئله‌ای که حل می‌کند

خطای سمت سرور در لاگ شما ثبت می‌شود. خطای سمت مرورگر نه — در دستگاه کاربر رخ می‌دهد و همان‌جا می‌ماند. اگر کاربر گزارش ندهد، شما هرگز نمی‌فهمید.

Sentry این شکاف را پر می‌کند: کتابخانه‌ای که در برنامهٔ شما اجرا می‌شود، خطاها را می‌گیرد و همراه با زمینه‌شان به سرور Sentry می‌فرستد.

چطور کار می‌کند

۱. SDK نصب می‌شود

Sentry.init({
  dsn: 'https://abc123@o0.ingest.sentry.io/456',
  release: 'my-app@1.4.2',
  tracesSampleRate: 0.1,
});

مقدار dsn آدرسی است که می‌گوید داده کجا برود و به کدام پروژه تعلق دارد. عمومی است و در کد فرانت‌اند قرار می‌گیرد؛ اجازهٔ نوشتن می‌دهد نه خواندن.

۲. قلاب‌ها نصب می‌شوند

SDK به رویدادهای سراسری گوش می‌دهد — خطاهای مدیریت‌نشده و Promiseهای رد شده — و توابعی مثل fetch را می‌پوشاند تا درخواست‌های ناموفق را هم ببیند.

۳. زمینه جمع می‌شود

هر رویداد فقط پیام خطا نیست؛ همراهش نسخهٔ انتشار، آدرس صفحه، مرورگر، و مهم‌تر از همه breadcrumb می‌آید: فهرستی از کارهایی که کاربر پیش از خطا انجام داد.

۴. رویداد ارسال می‌شود

به‌صورت ناهم‌زمان و در پس‌زمینه، تا کند شدن سایت را ایجاد نکند. اگر شبکه قطع باشد، در صف می‌ماند.

۵. سرور گروه‌بندی می‌کند

مهم‌ترین بخش. Sentry برای هر خطا یک «اثر انگشت» می‌سازد — بر پایهٔ نوع خطا، پیام و محل وقوع در stack — و همهٔ رویدادهای هم‌اثر را زیر یک Issue جمع می‌کند.

بدون این، یک خطا در صفحهٔ پربازدید ظرف یک روز ده‌ها هزار ردیف می‌سازد و داشبورد بی‌فایده می‌شود.

۶. Source map اعمال می‌شود

اگر نقشه‌ها را هنگام انتشار آپلود کرده باشید، Sentry موقعیت‌های کد فشرده را به فایل و خط اصلی ترجمه می‌کند.

مفاهیمی که باید بشناسید

Issue — گروهی از رویدادهای مشابه. واحد کاری شما همین است، نه تک‌تک رویدادها.

Event — یک بار رخ دادن.

Release — نسخه‌ای از کد. بدون این نمی‌دانید خطا از انتشار امروز است یا از نسخه‌ای که در کش کاربر مانده.

Environment — تفکیک production از staging.

Sampling — درصدی از رویدادها را می‌فرستید نه همه، برای کنترل هزینه. برای خطاها معمولاً صد درصد منطقی است؛ برای ردیابی کارایی نه.

وقتی گروه‌بندی پیش‌فرض اشتباه می‌کند

گروه‌بندی خودکار بیشتر وقت‌ها درست کار می‌کند، ولی دو حالت رایج هست که باید بشناسید.

یک باگ، چند Issue. یک مشکل واحد از چند مسیر مختلف کد رخ می‌دهد و چون stack هر بار فرق دارد، چند Issue جدا ساخته می‌شود. اولویت‌بندی سخت می‌شود، چون هیچ‌کدام به‌تنهایی بزرگ به نظر نمی‌رسد.

چند باگ، یک Issue. برعکسش وقتی است که همهٔ خطاها از یک نقطهٔ مشترک پرتاب می‌شوند؛ مثلاً تابع عمومی‌ای که همهٔ درخواست‌های API را می‌فرستد. خطای ۴۰۱، خطای ۵۰۰ و قطعی شبکه زیر یک Issue جمع می‌شوند.

راه‌حل هر دو، تعیین اثر انگشت به‌صورت دستی است:

Sentry.withScope(function (scope) {
  scope.setFingerprint(['api-request', String(err.status)]);
  Sentry.captureException(err);
});

با این کد، خطاهای API بر اساس کد وضعیت از هم جدا می‌شوند. اگر می‌خواهید گروه‌بندی پیش‌فرض را نگه دارید و فقط دقیق‌ترش کنید، مقدار '{{ default }}' را هم در آرایه بگذارید. همین قواعد را می‌شود بدون تغییر کد، در تنظیمات پروژه و به‌شکل Fingerprint Rules هم تعریف کرد.

قابلیت‌های فراتر از خطا

Sentry با گذر زمان از یک ابزار رصد خطا به مجموعه‌ای بزرگ‌تر تبدیل شده: ردیابی کارایی، Session Replay که تعامل کاربر را بازسازی می‌کند، و ویجت بازخورد کاربر.

این گستردگی هم قوت است و هم ضعف: تیم بزرگ همه‌شان را استفاده می‌کند، تیم دو نفره معمولاً از ده درصدش استفاده می‌کند و با پیچیدگی بقیه دست‌وپنجه نرم می‌کند.

ردیابی کارایی و Session Replay در عمل

هر دو در SDK مرورگر به‌شکل integration فعال می‌شوند و نرخ نمونه‌برداری جداگانه دارند:

Sentry.init({
  dsn: '...',
  release: 'my-app@1.4.2',
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  tracesSampleRate: 0.1,
  tracePropagationTargets: ['localhost', /^https:\/\/api\.example\.ir/],
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 1.0,
});

ردیابی کارایی بارگذاری صفحه و جابه‌جایی بین صفحات را به‌شکل تراکنش‌هایی از span ثبت می‌کند؛ هر درخواست شبکه و هر بخش کند یک span است. اگر بک‌اند هم SDK داشته باشد، یک درخواست را از کلیک کاربر تا کوئری پایگاه داده دنبال می‌کنید.

برای این اتصال، SDK به درخواست‌های خروجی هدرهای sentry-trace و baggage اضافه می‌کند و tracePropagationTargets تعیین می‌کند به کدام آدرس‌ها. اگر API روی دامنهٔ دیگری است، سرورش باید این دو هدر را در Access-Control-Allow-Headers بپذیرد؛ وگرنه درخواست‌ها با خطای CORS رد می‌شوند. این دامی است که بعد از فعال کردن tracing زیاد دیده می‌شود.

Session Replay تغییرات صفحه و تعامل کاربر را ضبط می‌کند تا بعداً ببینید دقیقاً چه شد. با تنظیم بالا، ضبط فقط در حافظهٔ مرورگر می‌ماند و تنها وقتی خطایی رخ دهد ارسال می‌شود. به‌صورت پیش‌فرض همهٔ متن‌ها و ورودی‌ها پوشانده و رسانه‌ها مسدود می‌شوند؛ پیش از برداشتن این پوشش، به دادهٔ شخصی کاربرانتان فکر کنید.

چه داده‌ای جمع می‌کند

سؤالی که پیش از نصب باید بپرسید، مخصوصاً اگر کاربران ایرانی دارید.

SDK به‌صورت پیش‌فرض این‌ها را می‌فرستد: پیام و stack خطا، آدرس صفحه، اطلاعات مرورگر و سیستم‌عامل، نسخهٔ انتشار، و breadcrumbها — که شامل کلیک‌ها، جابه‌جایی بین صفحات و درخواست‌های شبکه است.

آنچه نمی‌فرستد مگر خودتان بخواهید: هویت کاربر، محتوای فرم‌ها، و کوکی‌ها.

ولی دو نقطهٔ نشت هست که باید حواستان باشد: آدرس صفحه اگر شناسه یا ایمیل در پارامترهایش باشد، و breadcrumbهای شبکه که آدرس درخواست‌ها را نگه می‌دارند. Sentry امکان پاک‌سازی پیش از ارسال دارد؛ استفاده از آن اختیاری است ولی نباید باشد.

سه اشتباه رایج در راه‌اندازی

۱. فراموش کردن release. بدون آن نمی‌دانید خطا از کدام نسخه است، source map درست اعمال نمی‌شود، و نمی‌فهمید اصلاح شما واقعاً کار کرده یا نه. این تنها فیلدی است که نباید از قلم بیفتد.

۲. نفرستادن source map. بسیاری از تیم‌ها SDK را نصب می‌کنند و آپلود نقشه‌ها را به بعد موکول می‌کنند. نتیجه ماه‌ها داده‌ای است که خوانده نمی‌شود.

۳. تنظیم نکردن فیلتر از روز اول. خطاهای افزونه‌های مرورگر و اسکریپت‌های شخص ثالث ظرف چند هفته چنان نسبتی از فهرست را می‌گیرند که تیم دیگر نگاهش نمی‌کند. Sentry گزینهٔ ignoreErrors و denyUrls دارد؛ همان اول تنظیمشان کنید.

آپلود Source Map در عمل

برای این کار Sentry ابزار خط فرمان sentry-cli و افزونه‌هایی برای باندلرها دارد، مثل @sentry/vite-plugin و @sentry/webpack-plugin. ساده‌ترین شروع، ویزارد رسمی است که تنظیمات لازم را به پروژه اضافه می‌کند:

npx @sentry/wizard@latest -i sourcemaps

روش فعلی Sentry بر پایهٔ Debug ID است: هنگام build یک شناسهٔ یکتا داخل هر فایل جاوااسکریپت و نقشهٔ متناظرش قرار می‌گیرد و Sentry آن دو را با همین شناسه به هم وصل می‌کند، نه با نام فایل. با این حال release را همچنان بفرستید؛ برای اینکه بدانید خطا از کدام انتشار است، لازمش دارید. توکن آپلود را هم فقط در متغیرهای محیطی CI نگه دارید، نه در مخزن کد.

هزینه و مدل قیمت

Sentry بر اساس تعداد رویداد قیمت‌گذاری می‌کند. پلن رایگان محدودی دارد و هزینهٔ پلن‌های پولی با حجم ماهانهٔ خطاها بالا می‌رود؛ قیمت به‌روز را در صفحهٔ قیمت خود Sentry ببینید. Session Replay و ردیابی کارایی سهمیه‌های جداگانه دارند.

نکته‌ای که تیم‌ها را غافلگیر می‌کند: سهمیه با سرعت غیرمنتظره‌ای مصرف می‌شود. یک درخواست شبکه که هر چند ثانیه دوباره تلاش می‌کند، می‌تواند سهمیهٔ ماه را در چند روز خالی کند. برای همین تنظیم فیلتر و محدودسازی نرخ از روز اول اهمیت دارد.

برای تیم ایرانی

سه مانع عملی وجود دارد که ربطی به کیفیت محصول ندارد:

  • دسترسی. بدون تحریم‌شکن باز نمی‌شود — و ابزار رصدی که هر بار باز کردنش زحمت دارد، کمتر باز می‌شود.
  • پرداخت. کارت خارجی لازم است.
  • محل داده. دادهٔ کاربران شما روی سرورهای خارج از کشور می‌نشیند.

گزینه‌هایی که این موانع را حل می‌کنند وجود دارند: نسخهٔ میزبانی‌شده در ایران، نصب self-hosted، یا ابزارهای بومی. مقایسهٔ کاملشان را در مقالهٔ جداگانه‌ای آورده‌ایم.

Self-hosted یا نسخهٔ ابری

Sentry را می‌شود روی سرور خودتان هم نصب کرد. نسخهٔ رسمی self-hosted با Docker Compose راه‌اندازی می‌شود و کدش عمومی است. مجوز آن (Functional Source License) متن‌باز به معنای کلاسیک نیست، ولی استفاده در سازمان خودتان را مجاز می‌داند.

مزیتش روشن است: داده روی زیرساخت خودتان می‌ماند و پرداخت ارزی لازم نیست. ولی پیش از تصمیم، این‌ها را هم بدانید:

  • سنگین است. self-hosted مجموعه‌ای از سرویس‌هاست، از جمله PostgreSQL، Kafka، ClickHouse و Redis، و سرور با حافظه و دیسک قابل توجه می‌خواهد. حداقل منابع را در مستندات رسمی ببینید.
  • نگهداری با شماست. به‌روزرسانی، پشتیبان‌گیری و رسیدگی به دیسکِ پرشده کار تیم خودتان می‌شود.
  • دریافت ایمیج‌ها. نصب و ارتقا به ایمیج‌هایی از رجیستری‌های خارجی نیاز دارد که دسترسی به آن‌ها از داخل ایران ممکن است محدود باشد؛ از پیش برایش راه جایگزین در نظر بگیرید.
  • قابلیت‌ها کاملاً یکسان نیستند. تفاوت self-hosted با نسخهٔ ابری را در مستندات بررسی کنید.

قاعدهٔ عملی: اگر تیمتان از پیش سرویس‌های stateful را نگهداری می‌کند، self-hosted گزینهٔ جدی است. اگر نه، زمانی که صرف نگهداری‌اش می‌شود ممکن است از ارزش داده‌هایش بیشتر شود.

آیا Sentry برای شما مناسب است؟

بله، اگر: تیم مهندسی چند نفره دارید، به ردیابی کارایی و Session Replay نیاز دارید، و دسترسی و پرداخت برایتان حل شده است.

احتمالاً نه، اگر: تیم یک یا دو نفره‌اید و فقط می‌خواهید بدانید کجای سایتتان خراب است. در آن صورت ابزاری ساده‌تر با داشبورد فارسی، همان ارزش را با اصطکاک کمتر می‌دهد. مقایسهٔ ابزارهای رصد خطا برای تیم‌های ایرانی کمک می‌کند انتخاب کنید.

و یک نکتهٔ مهم فارغ از انتخاب: Sentry — و هر ابزار رصد خطای دیگری — فقط خطاهای فنی را می‌بیند. دکمه‌ای که کاربر پیدا نمی‌کند یا متنی که گیج‌کننده است، هیچ خطایی تولید نمی‌کنند. برای آن دسته به مسیر مستقیم دریافت بازخورد کاربر نیاز دارید، در کنار رصد خودکار.

منابع و مطالعهٔ بیشتر

باگ‌ماگ را رایگان امتحان کنید

خطاهای سایتتان را خودکار ثبت کنید و بگذارید کاربران با یک کلیک باگ گزارش دهند.

شروع رایگان