# فایل‌های دیباگ و نمادگشایی نیتیو

> https://docs.errora.org/products/debug-files

بیلد انتشار یک برنامهٔ موبایل یا نیتیو، نام‌ها را با خودش ندارد. کرش iOS یا NDK اندروید آدرس
دستورالعمل گزارش می‌دهد و برنامهٔ اندرویدی که با R8 مینیفای شده `a.b.c.d`. **فایل‌های دیباگ**
همان چیزی‌اند که این‌ها را به کد شما برمی‌گردانند — همتای نیتیو
[سورس‌مپ](/products/source-maps).

ارورا آن‌ها را هنگام دریافت و **پیش از گروه‌بندی** اعمال می‌کند، پس خطاها روی نام واقعی توابع
گروه می‌شوند که از بیلدی به بیلد دیگر ثابت می‌ماند.

## چه چیزهایی حل می‌شوند

- **فریم‌های نیتیو** (کرش‌های iOS و NDK اندروید) ← نام تابع، فایل و خط. نام‌های C++ و Swift
  دی‌منگل می‌شوند و فریم‌های inline‌شده به فریم‌های جداگانه باز می‌شوند.
- **فریم‌های جاوا/کاتلین** بیلد R8/ProGuard ← کلاس، متد، فایل و خط اصلی، همراه با بازشدن
  متدهای inline‌شده. **نام کلاس استثناهای** مبهم‌شده هم برگردانده می‌شود.
- **پروفایل‌ها**: فریم‌های پروفایل iOS با dSYM نمادگشایی می‌شوند و نام متدهای پروفایل اندروید از
  روی نگاشت ProGuard برگردانده می‌شود — نگاه کنید به [پروفایلینگ](/products/profiling).

## قالب‌های پشتیبانی‌شده

| قالب | پلتفرم | از کجا می‌آید |
| --- | --- | --- |
| 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` | یک [توکن دسترسی شخصی](/account/tokens) ارورا (`errora_pat_…`) |
| `SENTRY_ORG` | شناسهٔ متنی (slug) سازمان (از آدرس `/organizations/<slug>/…`) |
| `SENTRY_PROJECT` | شناسهٔ متنی پروژه |

همین مقادیر را می‌شود در `.sentryclirc` (`url`، `org`، `project`، `token`) یا بلوک `sentry {}`
در Gradle هم گذاشت. صاحب توکن باید در سازمان نقش **member** یا بالاتر داشته باشد.

### sentry-cli

```bash
# 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 پروگارد را خودش روی برنامه می‌زند. نگاه کنید به [اندروید](/platforms/android).
- **iOS** — یک فاز بیلد *Run Script* در Xcode که `sentry-cli debug-files upload` را اجرا
  می‌کند، یا اکشن `sentry_debug_files_upload` در fastlane. نگاه کنید به [iOS](/platforms/apple-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` هنگام بارگذاری | صاحب توکن عضو آن سازمان نیست |