فایل‌های دیباگ و نمادگشایی نیتیو
بیلد انتشار یک برنامهٔ موبایل یا نیتیو، نام‌ها را با خودش ندارد. کرش iOS یا NDK اندروید آدرس
دستورالعمل گزارش می‌دهد و برنامهٔ اندرویدی که با R8 مینیفای شده a.b.c.d. فایل‌های دیباگ
همان چیزی‌اند که این‌ها را به کد شما برمی‌گردانند — همتای نیتیو
سورس‌مپ.
ارورا آن‌ها را هنگام دریافت و پیش از گروه‌بندی اعمال می‌کند، پس خطاها روی نام واقعی توابع گروه می‌شوند که از بیلدی به بیلد دیگر ثابت می‌ماند.
چه چیزهایی حل می‌شوند
- فریم‌های نیتیو (کرش‌های iOS و NDK اندروید) ← نام تابع، فایل و خط. نام‌های C++ و Swift دی‌منگل می‌شوند و فریم‌های inlineشده به فریم‌های جداگانه باز می‌شوند.
- فریم‌های جاوا/کاتلین بیلد R8/ProGuard ← کلاس، متد، فایل و خط اصلی، همراه با بازشدن متدهای inlineشده. نام کلاس استثناهای مبهم‌شده هم برگردانده می‌شود.
- پروفایل‌ها: فریم‌های پروفایل iOS با dSYM نمادگشایی می‌شوند و نام متدهای پروفایل اندروید از روی نگاشت ProGuard برگردانده می‌شود — نگاه کنید به پروفایلینگ.
قالب‌های پشتیبانی‌شده
| قالب | پلتفرم | از کجا می‌آید |
|---|---|---|
| dSYM (Mach-O DWARF) | iOS، macOS | Xcode، با Debug Information Format = DWARF with dSYM File |
ELF (.so stripنشده) | NDK اندروید، لینوکس | کتابخانه‌های میانی و stripنشدهٔ بیلد NDK |
Breakpad (.sym) | هر برنامهٔ نیتیو | dump_syms |
| PDB | ویندوز | لینکر MSVC |
فایل mapping.txt از ProGuard/R8 | اندروید (جاوا/کاتلین) | app/build/outputs/mapping/<variant>/mapping.txt |
فایل چطور تطبیق داده می‌شود
هر فایل با یک شناسهٔ دیباگ (debug id) شناخته می‌شود، نه با نام یا نسخه:
- فایل‌های نیتیو شناسه را درون خود باینری دارند (UUID در Mach-O، build id در ELF، امضای PDB، شناسهٔ ماژول Breakpad). SDK شناسهٔ دیباگ همهٔ ایمیج‌های بارگذاری‌شده در پروسهٔ کرش‌کرده را گزارش می‌دهد و آدرس هر فریم با فایلی که همان شناسه را دارد حل می‌شود.
- نگاشت‌های ProGuard با یک UUID تطبیق داده می‌شوند که پلاگین Gradle روی برنامه می‌زند و SDK همراه هر رویداد گزارشش می‌کند.
پس فایل باید از همان بیلدی باشد که کرش کرده. بیلد دوبارهٔ همان کامیت، شناسه‌های دیباگ تازه می‌سازد و کرش‌های قبلی با فایل‌های جدید جور نمی‌شوند.
بارگذاری
از ابزارهای رسمی Sentry بدون تغییر استفاده کنید — ارورا همان نقاط بارگذاری‌ای را پیاده کرده که
sentry-cli با آن‌ها حرف می‌زند. فقط با چهار تنظیم آن را به ارورا وصل کنید:
| تنظیم | مقدار |
|---|---|
SENTRY_URL | https://<your-errora-host> |
SENTRY_AUTH_TOKEN | یک توکن دسترسی شخصی ارورا (errora_pat_…) |
SENTRY_ORG | شناسهٔ متنی (slug) سازمان (از آدرس /organizations/<slug>/…) |
SENTRY_PROJECT | شناسهٔ متنی پروژه |
همین مقادیر را می‌شود در .sentryclirc (url، org، project، token) یا بلوک sentry {}
در Gradle هم گذاشت. صاحب توکن باید در سازمان نقش member یا بالاتر داشته باشد.
sentry-cli
# dSYM، ELF، Breakpad و PDB — یک فایل یا یک پوشه بدهید
sentry-cli debug-files upload path/to/build/
# نگاشت ProGuard/R8
sentry-cli upload-proguard --uuid <uuid> app/build/outputs/mapping/release/mapping.txt
به تفکیک پلتفرم
- اندروید — پلاگین Gradle سنتری در هر بیلد انتشار، نگاشت و سیمبل‌های NDK را بارگذاری می‌کند و UUID پروگارد را خودش روی برنامه می‌زند. نگاه کنید به اندروید.
- iOS — یک فاز بیلد Run Script در Xcode که
sentry-cli debug-files uploadرا اجرا می‌کند، یا اکشنsentry_debug_files_uploadدر fastlane. نگاه کنید به iOS.
از مرورگر
در تنظیمات ← فایل‌های دیباگ می‌توانید فایل را دستی بارگذاری کنید و فایل‌های موجود را ببینید، دانلود یا حذف کنید. فایل‌های نیتیو شناسهٔ دیباگ خودشان را دارند. برای نگاشت ProGuard، فیلد اختیاری شناسهٔ دیباگ را با UUIDی پر کنید که برنامه‌تان گزارش می‌کند تا نگاشت با رویدادهایش جور شود.
خواندن خطایی که فایل دیباگ ندارد
فریمی که فایل دیباگش نیست نگه داشته می‌شود، نه حذف، و به‌عنوان نمادگشایی‌نشده علامت می‌خورد. صفحهٔ خطا شناسه‌های دیباگ گمشده را — همراه با ایمیج یا نگاشتی که هرکدام به آن تعلق دارد — فهرست می‌کند تا دقیقاً بدانید کدام فایل را باید بارگذاری کنید.
فایل‌های دیباگ فقط روی رویدادهایی اثر دارند که بعد از بارگذاری می‌رسند: فایل را بارگذاری کنید و منتظر رخداد بعدی بمانید.
خودمیزبانی
| تنظیم | پیش‌فرض | معنی |
|---|---|---|
DEBUG_FILES_STORAGE | filesystem | filesystem فایل‌ها را روی دیسک در DEBUG_FILES_ROOT نگه می‌دارد؛ s3 در یک باکت سازگار با S3 |
DEBUG_FILES_ROOT | backend/var/debug-files | محل فایل‌ها در حالت filesystem. اگر ورکرهای دریافت روی چند میزبان اجرا می‌شوند، باید یک حجم اشتراکی باشد — یا از s3 استفاده کنید |
DEBUG_FILES_S3_BUCKET، DEBUG_FILES_S3_ENDPOINT_URL، DEBUG_FILES_S3_REGION | — | باکت ذخیره‌سازی در حالت s3 (هر سرویس سازگار با S3) |
DEBUG_FILES_S3_ACCESS_KEY، DEBUG_FILES_S3_SECRET_KEY | — | کلیدهای دسترسی آن — در یک secret نگه دارید |
DEBUG_FILES_S3_PREFIX | debug-files | پیشوند کلیدها در باکت |
DEBUG_FILES_CACHE_DIR | پوشهٔ موقت سیستم | در حالت s3 هر ورکر فایل‌هایی را که با آن‌ها نمادگشایی می‌کند این‌جا نگه می‌دارد (بدون نیاز به حجم) |
DEBUG_FILES_CACHE_MAX_BYTES | ۲ گیگابایت | اندازهٔ این کش؛ فایل‌هایی که مدت‌ها استفاده نشده‌اند اول حذف می‌شوند |
DEBUG_FILE_UPLOAD_MAX_BYTES | ۵۰۰ مگابایت | سقف حجم هر بارگذاری از مرورگر |
در حالت s3 ورکرها بی‌حالت‌اند: چیزی لازم نیست mount شود و پادِ جایگزین، فایل‌های لازم را در اولین
استفاده دوباره دانلود می‌کند.
تکه‌های بارگذاری که sentry-cli جا می‌گذارد هر شب پاک‌سازی می‌شوند.
محدودیت‌ها
- مینی‌دامپ‌ها (Breakpad، Crashpad، sentry-native) مثل سنتری روی سرور پشته‌کاوی
(stack-walk) می‌شوند، با ابزار
minidump-stackwalkاز rust-minidump (در ایمیج Docker هست؛ برای ایمیج سفارشیMINIDUMP_STACKWALKرا تنظیم کنید). فایل‌های دیباگ باینری‌ها را بارگذاری کنید تا پشته‌کاوی از اطلاعات unwind آن‌ها استفاده کند؛ بدون آن‌ها به frame pointer و جست‌وجوی پشته برمی‌گردد و هر فریم نشان می‌دهد چطور پیدا شده (context،cfi،fp،scan). - نام‌های Swift با کتابخانهٔ زمان اجرای Swift (
libswiftCore) دی‌منگل می‌شوند که در ایمیج Docker وجود دارد؛ ایمیجی که بدون آن ساخته شود نمادهای Swift را منگل‌شده ($s7MyApp…) نشان می‌دهد. C++ همیشه دی‌منگل می‌شود. - فریم‌های بدون شمارهٔ خط (پروفایل‌های اندروید) مثل سنتری حل می‌شوند: اگر فریم امضای متد را داشته باشد با نوع پارامترها، وگرنه با نام — پس نام مبهم‌شده‌ای که به چند متد با پارامترهای یکسان اشاره کند همان‌طور می‌ماند.
عیب‌یابی
| نشانه | علت / راه‌حل |
|---|---|
فریم‌ها هنوز آدرس یا a.b.c هستند | فایل همان بیلد بارگذاری نشده — شناسهٔ دیباگ گمشده در صفحهٔ خطا را با فایل‌های دیباگ مقایسه کنید |
| فایل در فهرست هست ولی جور نمی‌شود | از بیلد دیگری است (همان نسخه، دوباره ساخته‌شده) — از همان جابی بارگذاری کنید که باینری منتشرشده را ساخته |
| فریم‌های NDK حل نمی‌شوند | فایل‌های .so stripشده را بارگذاری کرده‌اید — نسخهٔ stripنشده را از فایل‌های میانی بیلد بفرستید |
| نگاشت ProGuard دستی هیچ‌وقت جور نمی‌شود | شناسهٔ دیباگش همان UUIDی نیست که برنامه گزارش می‌کند |
sentry-cli به sentry.io بارگذاری می‌کند | SENTRY_URL / url تنظیم نشده |
پاسخ 403 هنگام بارگذاری | صاحب توکن عضو آن سازمان نیست |