---
id: native-crash-reporting
title: Native Crash Reporting — Crashlytics / Sentry
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [native, crash, sentry, crashlytics, vibe-coding]
tech_stack: { language: "Swift / Kotlin", applicable_to: ["iOS", "Android"] }
applied_in: []
aliases: [Crashlytics, Sentry, dSYM, ProGuard mapping, breadcrumbs]
---

# Native Crash Reporting

> Prod crash 추적의 표준 = **Firebase Crashlytics 또는 Sentry**. dSYM(iOS)/mapping(Android) 업로드 필수. Symbol 없는 stack 은 쓸모없음. Breadcrumbs + user identifier + custom keys 가 디버깅 무기.

## 📖 핵심 개념
- Symbolication: hex address → 함수명. dSYM/mapping 필요.
- Non-fatal: handled exception 도 보고.
- Breadcrumbs: 충돌 직전 N 이벤트.
- ANR (Android): Crashlytics 자동 보고.

## 💻 코드 패턴

### iOS — Crashlytics
```ruby
# Podfile
pod 'FirebaseCrashlytics'
```

```swift
import FirebaseCrashlytics

// 사용자 식별
Crashlytics.crashlytics().setUserID(user.id)
Crashlytics.crashlytics().setCustomValue(plan, forKey: "subscription")

// 로그 (breadcrumb)
Crashlytics.crashlytics().log("Tapped checkout")

// non-fatal
Crashlytics.crashlytics().record(error: NSError(domain: "App", code: 42))
```

dSYM upload (Build Phase):
```
"${PODS_ROOT}/FirebaseCrashlytics/run"
# Input Files: $(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH), ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
```

### Android — Crashlytics
```kotlin
// build.gradle
plugins {
    id 'com.google.gms.google-services'
    id 'com.google.firebase.crashlytics'
}

dependencies {
    implementation("com.google.firebase:firebase-crashlytics-ktx")
    implementation("com.google.firebase:firebase-analytics-ktx")
}
```

```kotlin
val crashlytics = FirebaseCrashlytics.getInstance()
crashlytics.setUserId(user.id)
crashlytics.setCustomKey("subscription", "pro")
crashlytics.log("opened CartActivity")

// non-fatal
try { risky() } catch (e: Exception) { crashlytics.recordException(e) }
```

ProGuard mapping 자동 업로드 (gradle plugin 처리).

### Sentry (cross-platform)
```swift
import Sentry

SentrySDK.start { o in
    o.dsn = "https://...@sentry.io/0"
    o.tracesSampleRate = 0.1
    o.debug = false
}

SentrySDK.setUser(User(userId: user.id))
SentrySDK.capture(error: error)
```

```kotlin
SentryAndroid.init(context) { o ->
    o.dsn = "https://...@sentry.io/0"
    o.tracesSampleRate = 0.1
}

Sentry.captureException(e)
Sentry.addBreadcrumb(Breadcrumb().apply { message = "checkout tapped" })
```

### React Native — @sentry/react-native
```ts
import * as Sentry from '@sentry/react-native';

Sentry.init({ dsn: '...', tracesSampleRate: 0.1 });
Sentry.captureException(error);
```

### Custom log line strategy
```swift
// 단순 log 보다 key=value 로
Crashlytics.crashlytics().log("nav route=cart user=\(user.id) cartCount=\(items.count)")
```

## 🤔 의사결정 기준
| 필요 | 추천 |
|---|---|
| Firebase 이미 사용 | Crashlytics (무료) |
| Self-hosted / 풍부한 분석 | Sentry |
| Crash + Performance 통합 | Sentry / Firebase Performance |
| ReactNative 한 SDK | Sentry RN |
| Symbol 자동 업로드 | Sentry CLI / Crashlytics gradle plugin |

## ❌ 안티패턴
- **dSYM 업로드 누락**: 의미 없는 stack.
- **Proguard mapping 안 올림**: Android 도 동일.
- **PII 그대로 user log**: GDPR / CCPA 위반.
- **breadcrumb 너무 많음**: noise. 의미 있는 이벤트만.
- **`fatalError(...)` 무절제**: prod 사용자에 보임.
- **catch 후 swallow**: 보고도 안 함, 디버깅 불가. 최소 record.
- **debug build 도 SDK 활성**: noise.

## 🤖 LLM 활용 힌트
- userID + custom key + log + recordException 4종.
- dSYM/mapping 자동 업로드 setup 우선.

## 🔗 관련 문서