---
id: native-anr-freeze-debugging
title: ANR / Freeze — UI 블로킹 추적
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [native, anr, freeze, performance, vibe-coding]
tech_stack: { language: "Swift / Kotlin", applicable_to: ["iOS", "Android"] }
applied_in: []
aliases: [ANR, Application Not Responding, hang, main thread block, freeze]
---

# ANR / Freeze Debugging

> Android 5초 / iOS 250ms 이상 메인 스레드 블록 = 사용자 체감 freeze. Android = ANR dialog, iOS = Hang. 원인 = 동기 IO / 큰 JSON / Bitmap decode / 락 경합.

## 📖 핵심 개념
- ANR: Android — Activity 5s, Broadcast 10s, FG service 200s.
- Hang (iOS): MetricKit `MXHangDiagnostic` / Xcode Organizer.
- 원인: main thread 에서 disk / network / decode / DB.

## 💻 코드 패턴

### Android — StrictMode (개발용)
```kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            StrictMode.setThreadPolicy(
                StrictMode.ThreadPolicy.Builder()
                    .detectDiskReads()
                    .detectDiskWrites()
                    .detectNetwork()
                    .penaltyLog()
                    .penaltyDialog() // dev: 다이얼로그
                    .build()
            )
        }
    }
}
```

### Android — main thread → background
```kotlin
// ❌ main thread DB query
val users = db.userDao().getAll()

// ✅ Coroutine + Dispatchers.IO
viewModelScope.launch {
    val users = withContext(Dispatchers.IO) { db.userDao().getAll() }
    _state.value = _state.value.copy(users = users)
}
```

### iOS — Main Thread Checker
```
Xcode → Edit Scheme → Diagnostics → Main Thread Checker (default ON)
실행 중 main 에서 UIKit 외 무거운 작업 시 즉시 stack 출력.
```

### iOS — async 로 빼기
```swift
// ❌ main 에서 큰 file decode
let img = UIImage(contentsOfFile: path)

// ✅ background queue
Task.detached(priority: .userInitiated) {
    let img = UIImage(contentsOfFile: path)
    await MainActor.run { imageView.image = img }
}
```

### Android — ANR trace
```bash
adb pull /data/anr/traces.txt
# 또는 Logcat 에서 'ANR in com.app' 검색 → main thread stack 분석
```

### iOS — MetricKit
```swift
import MetricKit

class MetricsObserver: NSObject, MXMetricManagerSubscriber {
    func didReceive(_ payloads: [MXDiagnosticPayload]) {
        for p in payloads {
            for hang in (p.hangDiagnostics ?? []) {
                print("Hang \(hang.hangDuration): \(hang.callStackTree)")
            }
        }
    }
}

MXMetricManager.shared.add(observer)
```

### Lock 경합
```kotlin
// ❌ main thread synchronized 블록 → IO 가 들어가면 ANR
synchronized(cache) {
    cache.put(k, fetchFromNetwork()) // 네트워크 안에서 락 보유
}

// ✅ 락 안에서 short critical section 만
val v = fetchFromNetwork()
synchronized(cache) { cache.put(k, v) }
```

## 🤔 의사결정 기준
| 증상 | 도구 |
|---|---|
| 화면 5초 정지 | Android: ANR trace, iOS: Hang Diagnostic |
| 가끔 끊김 | StrictMode / Main Thread Checker |
| Scroll jank | Systrace / Instruments Time Profiler |
| 시작 느림 | App Startup tracing / Launch Time |
| Background → FG 정지 | onResume 무거움 — async 로 |

## ❌ 안티패턴
- **runBlocking on main**: 코루틴 의의 무효, 즉시 ANR.
- **main 에서 큰 JSON parse**: 1MB+ 면 hang.
- **synchronized 가 IO 보유**: 다른 스레드도 같이 멈춤.
- **main 에서 SharedPreferences.commit()**: synchronous disk write.
- **이미지 main decode**: Glide/Coil 로 background.
- **DB query 직접 Adapter 안**: Paging 또는 Room Flow.
- **dispatchSemaphore wait main**: 죽음.

## 🤖 LLM 활용 힌트
- 모든 IO / decode / parse → background.
- StrictMode + Main Thread Checker 항상 dev 켜기.

## 🔗 관련 문서
- [[Native_Memory_Profiling]]