Stack Traceها — ابرووا تریس

ثبت خودکار stack trace برای exceptionهای مدیریت‌نشده، ثبت دستی، خطاهای async و کرش‌های نیتیو، با پشتیبانی از source map برای پلتفرم‌های وب.

stack trace ترتیب دقیق فراخوانی توابعی را که به خطا رسیده‌اند نشان می‌دهد: کجا خطا رخ داد، کد چطور به آنجا رسید و چه توابعی صدا زده شدند.

ثبت خودکار stack trace#

پیکربندی اضافه‌ای لازم نیست. ابرووا تریس stack trace را خودکار از این‌ها ثبت می‌کند:

exceptionهای مدیریت‌نشده (با captureUncaughtErrors: true)
ثبت دستی exception (با captureException())
خطاهای async (با initWithZone())
exceptionهای پلتفرم از کد نیتیو

dart

try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Operation failed',
    extra: {'user_id': 'user_123'},
  );
}

خواندن stack trace#

Exception: FormatException: Invalid input

at Parser.parse (lib/parser.dart:42:15) ← محل رخ دادن خطا

at DataService.process (lib/data_service.dart:108:8)

at HomeScreen.loadData (lib/screens/home.dart:55:12)

at _HomeScreenState.initState (lib/screens/home.dart:23:5)

خط اول: جایی که خطا رخ داده است
خطوط بعدی: call stack (کد چطور به آنجا رسیده)
مسیر فایل‌ها و شماره‌ی خطوط: برای پیدا کردن جای دقیق مشکل

stack trace در هر پلتفرم#

Flutter موبایل

stackهای کامل Dart با شماره‌ی خط و نام متدها

Flutter وب

stackهای خطای جاوااسکریپت همراه با اطلاعات مرورگر؛ برای خوانا شدن ممکن است source map لازم باشد

Flutter دسکتاپ

اطلاعات کامل debug با stackهای کامل و جزئیات پلتفرم

افزونه‌ی Chrome

اطلاعات context افزونه همراه با نسخه‌ی Chrome و context پس‌زمینه یا popup

افزودن context به stack trace#

dart

try {
  await processPayment(orderId, amount);
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Payment processing failed',
    extra: {
      'order_id': orderId,
      'amount': amount,
      'payment_method': paymentMethod,
    },
  );
}

stack trace کرش‌های نیتیو#

کرش‌های نیتیو در اجرای بعدی اپ شناسایی می‌شوند. وقتی کرش اپ را می‌بندد، اپ نمی‌تواند همان لحظه گزارش بدهد؛ برای همین ابرووا تریس کرش را هنگام اجرای دوباره پیدا می‌کند.

مهم. ثبت کرش نیتیو هنگام مقداردهی اولیه‌ی SDK (AbrovaTrace.initWithZone() یا AbrovaTrace.init()) نصب می‌شود و فراخوانی اضافه‌ای لازم نیست. AbrovaTrace.close() فقط داده‌های در انتظار را می‌فرستد و SDK را می‌بندد.

آپلود source map#

برای پلتفرم‌های وب (Next.js، Flutter Web) فایل‌های .map را آپلود کنید تا stack traceهای production به فایل‌ها و شماره‌ی خطوط اصلی کد شما برگردند.

کجا آپلود کنیم

کنسول ابرووا: در console.abrova.ir → پروژه‌ی شما → ابرووا تریس → Source map و symbol. نسخه‌ی release را تنظیم کنید و فایل‌های .map را (چند فایل با هم) آپلود کنید.
Abrova CLI: از build یا CI با abrova-trace sourcemaps upload آپلود کنید. آپلود source map را ببینید.
اپ دسکتاپ ابرووا هم وقتی منتشر شود همین امکان آپلود را خواهد داشت (به‌زودی).

نسخه‌ی release باید با فیلد release که هنگام init به SDK می‌دهید یکی باشد؛ بک‌اند از همین راه map درست را به هر خطا وصل می‌کند.

آپلود دست‌کم نقش member می‌خواهد؛ حذف فایل‌های آپلودشده نقش admin یا owner. نقش‌ها و دسترسی‌ها را ببینید.

Next.js

javascript

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

بعد از next build، فایل‌های .map را کنار chunkها در .next/static/chunks/ پیدا می‌کنید. در هر آپلود تا ۵۰۰ فایل .map پذیرفته می‌شود، پس می‌توانید همه را یک‌جا بیندازید (فایل‌هایی که .map نیستند نادیده گرفته می‌شوند).

Flutter Web

با source map فعال build بگیرید، سپس تنها فایل main.dart.js.map را آپلود کنید:

bash

flutter build web --source-maps

فایل map در build/web/main.dart.js.map قرار می‌گیرد.

Flutter Web: از traceهای بازگردانده‌شده چه انتظاری داشته باشیم.

dart2js (کامپایلری که Dart را به جاوااسکریپت تبدیل می‌کند) در buildهای --release به‌شدت inline می‌کند. بعضی frameها تمیز به فایل‌های .dart شما برمی‌گردند. بعضی دیگر به بخش‌های داخلی فریم‌ورک (js_helper.dart، dart:async) می‌رسند یا minified می‌مانند (a3v.$0)، چون فایل .map برای آن بایت‌های JS اصلاً نگاشتی ندارد.

این ویژگی خروجی dart2js است، نه مشکل resolver. از اول می‌گوییم چون بیشتر تیم‌ها در production به آن برمی‌خورند و فکر می‌کنند تنظیماتشان خراب است. خراب نیست.

جایی که ابرووا جلو می‌افتد context است. breadcrumbهای gesture را فعال کنید (AbrovaTrace.enableGestureBreadcrumbs()) تا هر مشکل ویجتی را که کاربر درست پیش از خطا لمس کرده نشان دهد، به‌همراه route، آخرین فراخوانی HTTP و هر breadcrumb سفارشی. همراه با trace نیمه‌بازگردانده‌شده، گزارش باگی قابل‌بازتولید خواهید داشت.

فقط برای QA / staging می‌توانید بهینه‌سازی کمتری را اجبار کنید تا traceهای کاملاً بازگردانده‌شده بگیرید:

bash

flutter build web --source-maps --dart2js-optimization=O1

حجم bundle حدود ۳۰٪ بیشتر می‌شود؛ برای staging مناسب است، برای production توصیه نمی‌شود.

بهترین روش‌ها#

همیشه stack trace را بفرستید

در ثبت دستی exception پارامتر stackTrace را بدهید

context معنادار اضافه کنید

شناسه‌ی کاربر، نام صفحه و داده‌های مرتبط را در فیلد extra بگذارید

از نسخه‌ی release استفاده کنید

نسخه‌ی release را تنظیم کنید تا خطاها را به deployها ربط دهید

همراه با breadcrumbها

breadcrumbها نشان می‌دهند کاربر چه کرد و stack trace نشان می‌دهد کد کجا شکست خورد

در محیط توسعه تست کنید

debug: true را فعال کنید تا در زمان توسعه stack traceها را در کنسول ببینید