iOS

ارورا بدون هیچ تغییری با SDK رسمی Sentry برای Cocoa کار می‌کند. SDK کرش‌ها را روی خود دستگاه ثبت می‌کند، هنگ برنامه و خاتمهٔ اجباری watchdog را گزارش می‌دهد و sentry-cli فایل‌های dSYM را بارگذاری می‌کند تا ارورا آدرس‌های کرش را به نام تابع، فایل و خط تبدیل کند.

پروژه را با پلتفرم iOS بسازید تا پنل نمونه‌کدهای درست را نشان دهد.

نصب

Swift Package Manager — در Xcode از منوی File → Add Package Dependencies… این آدرس را اضافه کنید:

https://github.com/getsentry/sentry-cocoa

CocoaPods:

# Podfile
pod 'Sentry'

مقداردهی اولیه

SDK را هرچه زودتر شروع کنید — در application(_:didFinishLaunchingWithOptions:) یا در init() مربوط به App در SwiftUI:

import Sentry

SentrySDK.start { options in
    options.dsn = "https://<public_key>@<your-errora-host>/<project_id>"
    options.environment = "production"

    options.tracesSampleRate = 0.2             // ردیابی کارایی

    options.configureProfiling = {             // پروفایلینگ
        $0.sessionSampleRate = 1.0
        $0.lifecycle = .trace
    }

    options.attachScreenshot = true            // اسکرین‌شات هنگام خطا
    options.attachViewHierarchy = true         // سلسله‌مراتب ویوها هنگام خطا

    options.sessionReplay.onErrorSampleRate = 1.0
    options.sessionReplay.sessionSampleRate = 0.1

    options.enableAppHangTracking = true       // پیش‌فرض: روشن
    options.appHangTimeoutInterval = 2         // ثانیه
}

نسخه‌های قدیمی‌تر SDK به‌جای configureProfiling از options.profilesSampleRate = 1.0 استفاده می‌کنند؛ ارورا خروجی هر دو را می‌پذیرد.

گزینه‌هایی که ارزش روشن‌کردن دارند

گزینه	چه چیزی در ارورا می‌گیرید
tracesSampleRate	کارایی: شروع برنامه، UIViewController و اسپن‌های شبکه
configureProfiling / profilesSampleRate	پروفایلینگ، نمادگشایی‌شده با dSYMهای شما
attachScreenshot	اسکرین‌شاتی که همراه هر خطا ذخیره و در صفحهٔ خطا پیش‌نمایش می‌شود
attachViewHierarchy	درخت ویوها در لحظهٔ خطا، که در صفحهٔ خطا به شکل درخت نمایش داده می‌شود
sessionReplay.*SampleRate	بازپخش نشست موبایل
enableAppHangTracking	هنگ‌های برنامه مثل خطای معمولی می‌رسند و مثل هر خطای دیگری گروه می‌شوند و هشدار می‌دهند
enableAutoSessionTracking	نشست‌ها برای سلامت نسخه — پیش‌فرض روشن

لازم نیست نسخه (release) را تعیین کنید: SDK خودش <bundleId>@<version>+<build> را می‌گذارد و سلامت نسخه روی همین رشته کار می‌کند.

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

بارگذاری dSYM

گزارش کرش فقط آدرس دستورالعمل‌ها را دارد. ارورا پیش از گروه‌بندی آن‌ها را با dSYMی نمادگشایی می‌کند که شناسهٔ دیباگش (UUID فایل Mach-O) با هر ایمیج بارگذاری‌شده جور باشد — نگاه کنید به فایل‌های دیباگ.

۱. تولید dSYM

در Build Settings تارگت، Debug Information Format را روی DWARF with dSYM File بگذارید — دست‌کم برای پیکربندی Release.

۲. تنظیم sentry-cli

sentry-cli را نصب کنید (brew install getsentry/tools/sentry-cli) و آدرس ارورا را به آن بدهید. یا با متغیرهای محیطی:

export SENTRY_URL=https://<your-errora-host>
export SENTRY_AUTH_TOKEN=errora_pat_…
export SENTRY_ORG=<organization-slug>
export SENTRY_PROJECT=<project-slug>

…یا با یک فایل .sentryclirc کنار پروژه (توکن را وارد git نکنید):

[defaults]
url = https://<your-errora-host>
org = <organization-slug>
project = <project-slug>

[auth]
token = errora_pat_…

توکن، یک توکن دسترسی شخصی ارورا است که صاحبش در سازمان نقش member یا بالاتر دارد. شناسهٔ متنی (slug) سازمان همان است که در آدرس داشبورد می‌بینید (/organizations/<slug>/…).

۳. افزودن فاز بیلد در Xcode

Build Phases → + → New Run Script Phase را بعد از Compile Sources اضافه کنید:

if [[ "$(uname -m)" == arm64 ]]; then
  export PATH="/opt/homebrew/bin:$PATH"
fi

if which sentry-cli >/dev/null; then
  ERROR=$(sentry-cli debug-files upload "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
  if [ ! $? -eq 0 ]; then
    echo "warning: sentry-cli - $ERROR"
  fi
else
  echo "warning: sentry-cli not installed"
fi

این مسیر را به Input Files همین فاز اضافه کنید تا Xcode آن را بعد از ساخته‌شدن dSYM اجرا کند (و با sandbox اسکریپت‌های کاربر هم کار کند):

${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}

یا با fastlane

lane :upload_symbols do
  sentry_debug_files_upload(
    url: "https://<your-errora-host>",
    auth_token: ENV["SENTRY_AUTH_TOKEN"],
    org_slug: "<organization-slug>",
    project_slug: "<project-slug>",
  )
end

آن را بعد از build_app (یا gym) اجرا کنید تا dSYMهای بیلد روی دیسک باشند.

فایل دیباگ را می‌توانید دستی و از مرورگر هم بارگذاری کنید: تنظیمات ← فایل‌های دیباگ.

بررسی نهایی

پیکربندی Release را بسازید، برنامه را بدون دیباگر متصل اجرا کنید (دیباگر کرش‌ها را می‌بلعد) و بعد:

SentrySDK.capture(error: NSError(domain: "errora.smoke-test", code: 1))
// یا یک کرش واقعی:
SentrySDK.crash()

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

عیب‌یابی

نشانه	علت / راه‌حل
فریم‌ها فقط آدرس دارند	dSYM آن بیلد بارگذاری نشده — لاگ بیلد و فایل‌های دیباگ را بررسی کنید
نمادهای Swift شبیه $s7MyApp… هستند	ایمیج ارورا Swift را با کتابخانهٔ زمان اجرای همراهش دی‌منگل می‌کند؛ ایمیج سفارشی به libswiftCore.so نیاز دارد — فایل‌های دیباگ را ببینید
بعد از SentrySDK.crash() کرشی نمی‌رسد	دیباگر وصل بوده یا برنامه دوباره باز نشده
بارگذاری با 401 شکست می‌خورد	توکن اشتباه یا باطل‌شده است، یا SENTRY_URL تنظیم نشده (sentry-cli پیش‌فرض به sentry.io می‌فرستد)
دادهٔ سلامت نسخه نمی‌آید	enableAutoSessionTracking خاموش شده است