React Native iOS stack 복원: crash 주소와 dSYM을 어떻게 연결하는가

30초 요약

dSYM(Debug Symbol, 디버그 심볼)은 build의 기계 코드 주소를 함수·원본 파일·줄에 연결하는 정보 묶음이다. UUID(Universally Unique Identifier, 범용 고유 식별자)는 여기서 한 실행 파일 build와 dSYM을 잇는 값이다.

iOS native crash의 주소를 읽으려면 frame 한 줄만 보지 않는다. crash 보고서의 Binary Images에서 그 주소가 속한 실행 파일의 다음 네 값을 찾는다.

바이너리 이름      앱 실행 파일과 포함된 별도 라이브러리 중 어느 것인가
CPU(Central Processing Unit, 중앙 처리 장치) 구조
                   arm64 또는 crash 보고서가 기록한 실제 구조
load address       실행 중 그 바이너리가 메모리에 놓이기 시작한 주소
build UUID         실행 파일과 dSYM이 같은 build인지 잇는 값

dSYM은 build 뒤 분리해 둔 함수·원본 파일·줄 대응 정보다. Xcode가 전체 crash 보고서와 같은 UUID의 dSYM을 찾으면 자동으로 주소를 복원할 수 있다. 명령줄의 atos는 같은 dSYM 내부 파일, CPU 구조, load address와 frame 주소를 직접 받는다.

반복해서 기억할 문장은 이것이다.

Binary Images의 UUID로 dSYM을 먼저 고르고, 같은 행의 구조와 load address로 주소를 복원한다.

이 글을 관통하는 상황: 같은 주소가 다른 함수처럼 보였다

Mach-O는 iOS·macOS 앱과 포함 라이브러리가 사용하는 Apple 플랫폼 실행 파일 형식이다. xcarchive는 Xcode가 한 배포 build의 앱 실행 파일과 dSYM 등을 함께 보관하는 폴더 묶음이다.

먼저 뒤에서 직접 만들 학습용 Mach-O build 417의 기록을 보자. 이 값은 UUID 선택 실패를 재현하는 로컬 fixture이며 실제 iOS 사용자 crash 증거가 아니다.

4   SymbolFixture   0x0000000100000460  0x100000000 + 1120
 
Binary Images:
0x100000000 - 0x100003fff SymbolFixture arm64
  <UUID_417> .../build-417/SymbolFixture

파일 이름만 보고 build 418의 dSYM을 고르면 주소는 profileOpen (SymbolFixture.c:9)처럼 그럴듯한 다른 함수로 나온다. 그러나 build 418 dSYM UUID는 UUID_418이어서 crash 보고서의 UUID_417과 달랐다.

build 417 실행 파일과 dSYM은 둘 다 UUID_417이었고, 같은 주소는 requirePositiveTotal (SymbolFixture.c:14)로 복원됐다. 실제 iOS build에서는 같은 판정을 Apple crash 보고서와 xcarchive로 다시 닫아야 한다.

이 글의 질문은 하나다.

iOS crash의 기계 코드 주소를 정확한 함수와 원본 파일·줄로 어떻게 되돌리는가?

UUID가 다르면 주소 복원을 시작하지 않는다

framework는 앱에 포함돼 별도 라이브러리 코드를 담는 실행 파일이고, app extension은 공유 화면·알림 처리처럼 앱 기능 일부를 별도 실행하는 확장 파일이다. 각각 자체 기계 코드 이미지와 dSYM을 가질 수 있다.

UUID는 여기서 앱 전체 이름이 아니라 한 기계 코드 이미지 build를 가리킨다. 앱 build 번호가 같아도 다시 build한 파일의 UUID가 다르면 후보에서 제외한다.

crash Binary Images UUID
          │
          ├─ 앱 실행 파일 UUID와 같음
          └─ dSYM 내부 파일 UUID와 같음
                         ↓
                  주소 복원 시작 가능

dwarfdump --uuid는 Mach-O 실행 파일이나 dSYM의 UUID를 읽는다. UUID가 다르면 atos가 어떤 이름을 출력하더라도 그 crash의 복원 증거로 사용하지 않는다.

다른 dSYM도 그럴듯한 함수 이름을 만들 수 있다

작은 실험으로 UUID gate가 필요한 이유를 확인한다. 이 실험은 macOS arm64와 Xcode 26.2에서 직접 실행했다. iOS 앱을 build하거나 crash시키지 않고, 두 macOS Mach-O 실행 파일과 dSYM으로 dwarfdump와 atos의 입력·출력 모양만 검증한다.

이 명령 실험은 Xcode가 필요한 macOS 전용이다. 앱 저장소 밖의 빈 연습 디렉터리로 이동한 뒤 폴더를 만든다.

mkdir -p ios-symbol-fixture

편집기로 다음 파일을 저장하고 test -f ios-symbol-fixture/SymbolFixture.c가 성공하는지 확인한다.

이 코드는 BUILD_NUMBER가 417이면 requirePositiveTotal, 418이면 profileOpen을 build에 넣는다. #if는 build할 때 정의한 숫자에 따라 둘 중 한 코드만 고르는 C 전처리 조건이고, noinline은 이 실험에서 함수를 호출 위치에 합치지 않고 별도 함수로 남기라는 표시다.

ios-symbol-fixture/SymbolFixture.c

#include <stdio.h>
#include <stdlib.h>
 
#ifndef BUILD_NUMBER
#define BUILD_NUMBER 0
#endif
 
#if BUILD_NUMBER == 418
__attribute__((noinline)) int profileOpen(int total) {
  return total + BUILD_NUMBER;
}
#define SELECTED_FUNCTION profileOpen
#else
__attribute__((noinline)) int requirePositiveTotal(int total) {
  if (total <= 0) {
    abort();
  }
  return total + BUILD_NUMBER;
}
#define SELECTED_FUNCTION requirePositiveTotal
#endif
 
int main(void) {
  printf("%d\n", SELECTED_FUNCTION(12900));
  return 0;
}

터미널에서 연습 폴더의 상위 디렉터리로 이동한다. xcrun은 현재 선택한 Xcode에서 명령 도구를 찾고, uname -m은 이 Mac의 CPU 구조를 arm64 또는 x86_64처럼 출력한다. 그 값을 두 build와 뒤의 atos에 같이 사용한다.

clang은 C 원본을 기계 코드로 바꾸는 compiler다. -g는 줄 복원용 정보를 만들고, -O0은 이 실험에서 최적화를 끄며, -D는 BUILD_NUMBER 값을 정한다. -c는 아직 실행 파일로 연결하지 않고 중간 기계 코드 파일인 .o까지만 만든다. dsymutil은 그 build의 디버그 정보를 dSYM으로 모으므로, .o를 남겨 둔 상태에서 실행해야 이 실험의 원본 줄 정보를 읽을 수 있다.

mkdir -p ios-symbol-fixture/build-417 ios-symbol-fixture/build-418
FIXTURE_ARCH="$(uname -m)"
 
xcrun clang -arch "$FIXTURE_ARCH" -g -O0 -DBUILD_NUMBER=417 \
  -c ios-symbol-fixture/SymbolFixture.c \
  -o ios-symbol-fixture/build-417/SymbolFixture.o
xcrun clang -arch "$FIXTURE_ARCH" ios-symbol-fixture/build-417/SymbolFixture.o \
  -o ios-symbol-fixture/build-417/SymbolFixture
xcrun dsymutil ios-symbol-fixture/build-417/SymbolFixture \
  -o ios-symbol-fixture/build-417/SymbolFixture.app.dSYM
 
xcrun clang -arch "$FIXTURE_ARCH" -g -O0 -DBUILD_NUMBER=418 \
  -c ios-symbol-fixture/SymbolFixture.c \
  -o ios-symbol-fixture/build-418/SymbolFixture.o
xcrun clang -arch "$FIXTURE_ARCH" ios-symbol-fixture/build-418/SymbolFixture.o \
  -o ios-symbol-fixture/build-418/SymbolFixture
xcrun dsymutil ios-symbol-fixture/build-418/SymbolFixture \
  -o ios-symbol-fixture/build-418/SymbolFixture.app.dSYM

각 build의 실행 파일과 dSYM UUID를 확인한다.

xcrun dwarfdump --uuid ios-symbol-fixture/build-417/SymbolFixture
xcrun dwarfdump --uuid ios-symbol-fixture/build-417/SymbolFixture.app.dSYM
xcrun dwarfdump --uuid ios-symbol-fixture/build-418/SymbolFixture
xcrun dwarfdump --uuid ios-symbol-fixture/build-418/SymbolFixture.app.dSYM

Xcode 26.2 검증에서는 다음 관계가 나왔다. UUID 문자열은 같은 source를 다시 build해도 새로 생길 수 있으므로 독자는 자신의 출력값을 UUID_417과 UUID_418 자리에 기록한다.

build 417 binary  UUID_417
build 417 dSYM    UUID_417
build 418 binary  UUID_418
build 418 dSYM    UUID_418
UUID_417 != UUID_418

nm은 실행 파일 안의 함수와 주소를 읽고, grep은 그중 원하는 함수 행만 남긴다. otool은 Mach-O의 구간 정보를 읽고, awk는 그중 __TEXT 시작 주소 행만 남긴다. 이 fixture에서 __TEXT vmaddr는 실행 파일의 load address이고, nm의 함수 주소는 복원할 frame address다. build 417 값은 다음처럼 확인했다.

xcrun nm -n ios-symbol-fixture/build-417/SymbolFixture | grep requirePositiveTotal
xcrun otool -l ios-symbol-fixture/build-417/SymbolFixture |
  awk '/segname __TEXT/{found=1} found && /vmaddr/{print; exit}'

0000000100000460 T _requirePositiveTotal
__TEXT vmaddr 0x0000000100000000

독자의 출력 주소가 다르면 아래 -l에는 실제 __TEXT vmaddr, 마지막 인자에는 실제 함수 주소를 넣는다. -arch는 위에서 기록한 CPU 구조, -o는 dSYM 안의 디버그 정보 파일, -l은 load address를 뜻한다.

먼저 같은 주소를 잘못된 build 418 dSYM으로 읽는다.

xcrun atos -arch "$FIXTURE_ARCH" \
  -o ios-symbol-fixture/build-418/SymbolFixture.app.dSYM/Contents/Resources/DWARF/SymbolFixture \
  -l 0x100000000 0x100000460

profileOpen (in SymbolFixture) (SymbolFixture.c:9)

명령은 성공하고 함수·줄도 그럴듯하지만 crash build와 UUID가 다른 오답이다. build 417 dSYM으로 바꾼다.

xcrun atos -arch "$FIXTURE_ARCH" \
  -o ios-symbol-fixture/build-417/SymbolFixture.app.dSYM/Contents/Resources/DWARF/SymbolFixture \
  -l 0x100000000 0x100000460

requirePositiveTotal (in SymbolFixture) (SymbolFixture.c:14)

위 주소와 두 출력은 Xcode 26.2가 설치된 arm64 Mac에서 검증했다. 다른 CPU 구조에서는 자신의 FIXTURE_ARCH, nm 주소와 __TEXT vmaddr를 사용하고, UUID 일치 관계와 두 함수·줄 결과를 확인한다.

공개 build마다 xcarchive와 dSYM을 함께 보관한다

실제 React Native iOS 앱에서는 ios/ReceiptApp.xcworkspace처럼 iOS 네이티브 라이브러리 의존성과 앱 project를 함께 여는 workspace 파일을 Xcode로 연다. run destination은 어느 Apple 기기 계열용으로 build할지 고르는 항목이다. iPhone·iPad 실기기 계열의 배포 destination과 배포할 scheme을 고른 뒤 Product > Archive를 실행한다. scheme은 어떤 target·build 설정을 함께 만들지 정한 이름이고, target은 한 앱 실행 파일이나 framework를 만드는 대상이다.

DWARF는 함수·원본 파일·줄 대응을 저장하는 디버그 정보 형식이다. dSYM 안의 Contents/Resources/DWARF/ 디렉터리에는 실행 파일 이름과 같은 DWARF 정보 파일이 있다.

Archive 안의 대표 경로는 다음 모양이다.

ReceiptApp.xcarchive/
├── Products/Applications/ReceiptApp.app/ReceiptApp
└── dSYMs/ReceiptApp.app.dSYM/Contents/Resources/DWARF/ReceiptApp

framework와 app extension이 있으면 각각의 실행 파일과 dSYM도 함께 보관한다. Xcode의 Build Settings에서 배포 build가 디버그 정보를 dSYM으로 만드는지 확인하고, TestFlight·App Store 배포 때 app symbols 업로드를 유지하면 Apple이 crash 보고서에 함수·줄을 붙이는 데 사용할 수 있다.

보관 기록에는 최소 다음 값을 함께 둔다.

앱 version / build number / source commit
xcarchive path / 보존 저장소에서 다시 찾는 고유 ID
앱 실행 파일 UUID / 앱 dSYM UUID
포함 framework·extension 실행 파일 UUID / 각 dSYM UUID
Xcode version / build configuration / distribution destination

새 Archive가 이전 xcarchive를 대신하지 않는다. 현재 배포 build는 팀이 만든 archive와 dSYM 보관 계약으로 닫는다.

실제 iOS crash는 Binary Images 네 값으로 닫는다

잘린 제3자 stack 한 줄이 아니라 Apple 운영체제가 만든 전체 crash 보고서를 확보한다. Xcode의 Crashes organizer, 연결한 기기의 Devices and Simulators, 또는 기기 설정 > 개인정보 보호 및 보안 > 분석 및 향상 > 분석 데이터에서 가져올 수 있다. 전체 보고서에는 crashed thread와 Binary Images가 있어야 한다.

예를 들어 다음 frame을 복원한다고 하자.

4   ReceiptApp   0x00000001022df754  0x1022c0000 + 128852
 
Binary Images:
0x1022c0000 - 0x1022effff ReceiptApp arm64
  <9cc89c5e55163f4ab40c5821e99f05c6> .../ReceiptApp.app/ReceiptApp

이 한 행에서 다음 값을 기록한다.

binary name    ReceiptApp
architecture   arm64
load address   0x1022c0000
build UUID     9cc89c5e55163f4ab40c5821e99f05c6
frame address  0x00000001022df754

iOS Binary Images의 32자리 UUID를 비교·검색할 때는 같은 바이트를 대문자 8-4-4-4-12 형식인 9CC89C5E-5516-3F4A-B40C-5821E99F05C6으로 정규화한다. 하이픈과 대소문자 표현이 달라도 정규화한 UUID 바이트가 같아야 같은 build다.

터미널에서 ReceiptApp.xcarchive가 있는 디렉터리로 이동한다. 실행 파일과 dSYM 내부 DWARF 파일 경로를 변수 하나씩 고정해 UUID 확인과 atos에서 그대로 재사용한다.

APP_BINARY="ReceiptApp.xcarchive/Products/Applications/ReceiptApp.app/ReceiptApp"
DSYM_DWARF="ReceiptApp.xcarchive/dSYMs/ReceiptApp.app.dSYM/Contents/Resources/DWARF/ReceiptApp"
 
xcrun dwarfdump --uuid "$APP_BINARY"
xcrun dwarfdump --uuid "$DSYM_DWARF"

두 출력과 정규화한 crash UUID가 모두 같아야 한다. macOS Spotlight가 dSYM을 색인했다면 Apple 공식 쿼리로 UUID가 같은 후보를 찾을 수도 있다.

mdfind "com_apple_xcode_dsym_uuids == 9CC89C5E-5516-3F4A-B40C-5821E99F05C6"

Xcode 전체 복원을 우선하고 atos로 한 frame을 확인한다

Xcode의 Devices and Simulators에서 Device Logs를 열고 .crash 보고서를 목록에 끌어 놓는다. Apple 공식 절차는 이 import에 .crash 확장자를 요구한다. 앱 frame이 주소로 남으면 해당 build의 xcarchive가 이 Mac에 있는지, 실행 파일·dSYM·crash UUID가 같은지, framework dSYM이 따로 필요한지 먼저 확인한다.

한 frame을 명령줄에서 확인할 때는 Apple 공식 식을 그대로 적용한다.

xcrun atos \
  -arch arm64 \
  -o "$DSYM_DWARF" \
  -l 0x1022c0000 \
  0x00000001022df754

CheckoutCoordinator.finish(_:) (in ReceiptApp) (CheckoutCoordinator.swift:84)

이 마지막 함수·줄은 제품 Archive로 실제 실행했을 때만 증거가 된다. 이 글의 로컬 Mach-O fixture가 CheckoutCoordinator.swift:84를 만들었다고 주장하지 않는다. 시스템 framework frame이 남으면 crash의 운영체제 버전·CPU 구조와 맞는 시스템 symbols도 필요할 수 있다.

framework와 app extension도 UUID별로 분리한다

앱 하나의 crash 보고서에 다음 이미지가 함께 있을 수 있다.

ReceiptApp
ReceiptPayments.framework
ReceiptShareExtension
UIKitCore

주 앱 dSYM 하나로 모든 주소를 복원하지 않는다. Binary Images에서 frame이 속한 바이너리 이름과 UUID를 찾고, 그 실행 파일의 dSYM을 고른다. 제3자 framework dSYM이 없다면 vendor에게 해당 공개 build의 symbols를 요청한다. 시스템 framework는 crash의 운영체제 release와 CPU 구조에 맞는 Apple symbols가 필요하다.

복원된 frame을 전체 crash 보고서와 다시 읽는다

함수·줄이 보이면 다음 표로 원본 사건과 대조한다.

build        version·build number·commit·Archive가 보고서와 맞는가
binary       앱·framework·extension 중 frame이 속한 이름을 골랐는가
identity     crash·실행 파일·dSYM UUID가 모두 같은가
address      CPU 구조·load address·frame address가 같은 Binary Images 행에서 왔는가
thread       실제 crashed thread와 호출 순서를 보존했는가
exception    exception type·termination reason·진단 message가 무엇인가
source       공개 build commit의 실제 파일·줄인가
reproduce    같은 입력·기기 조건에서 같은 crash 범주가 생기는가

inline은 compiler가 함수 호출을 별도 호출로 남기지 않고 호출한 위치에 합치는 최적화다. 이 최적화 때문에 여러 source 위치가 한 frame에 연결될 수 있다. 심볼이 붙은 첫 앱 frame은 조사 시작점일 뿐이며, crash 원인은 그보다 앞선 상태나 다른 thread의 동작일 수 있다. 전체 보고서를 잘라내지 않고 원본과 복원본을 함께 보관한다.

crash 보고서에는 경로·기기·사용 상황 같은 민감 정보가 들어갈 수 있다. 필요한 보고서와 symbols만 제한된 진단 저장소에 두고, 인증값·결제 정보·사용자 입력을 별도 로그로 덧붙이지 않는다.

pull request에서 달라져야 할 행동

공개 iOS build의 stack 복원 pull request에는 다음이 있어야 한다.

원본 보고서      Apple 전체 crash 보고서와 crashed thread 보존
build 연결       version·build number·commit·xcarchive 고정
UUID             crash·binary·dSYM 세 값 일치 기록
주소 입력        binary name·architecture·load address·frame address 기록
도구 결과        Xcode 자동 복원 또는 atos 명령·출력 보존
분리             app·framework·extension dSYM을 각각 선택
원인 검증        exception·호출 순서·공개 build 소스·재현과 대조
보안             crash·archive·dSYM 접근·보존·삭제 정책 기록

검토자는 다음을 확인한다.

• 앱 버전 이름만 보고 dSYM을 고르지 않는가?
• crash·binary·dSYM UUID를 모두 비교했는가?
• 다른 Binary Images 행의 load address나 CPU 구조를 섞지 않는가?
• .dSYM 바깥 묶음이 아니라 그 안의 DWARF 파일을 atos -o에 전달했는가?
• 주 앱 dSYM으로 제3자 framework 주소까지 복원하려 하지 않는가?
• 새 Archive가 과거 공개 build dSYM을 대신한다고 가정하지 않는가?
• 주소가 함수·줄로 바뀐 사실을 crash 원인 확정으로 오해하지 않는가?
• JavaScript frame은 이 dSYM이 아니라 25편의 JavaScript 위치 대응 파일 경계를 따르는가?

한 장으로 다시 보기

문제       build 417 주소가 build 418 dSYM으로 profileOpen처럼 잘못 복원됨
선택       Binary Images에서 binary·architecture·load address·UUID 읽기
gate       crash UUID = binary UUID = dSYM UUID일 때만 계속
자동       Xcode가 전체 보고서와 찾을 수 있는 symbols로 먼저 복원
수동       atos + architecture + dSYM 내부 파일 + load address + frame address
보관       공개 build별 xcarchive·모든 dSYM·commit·UUID 저장
분리       앱·framework·extension은 각 실행 파일 UUID와 dSYM 사용
검증       crashed thread·exception·호출 순서·공개 build 소스와 대조
경계       JavaScript는 25편, Android native는 26편 도구가 맡음

iOS stack 복원은 주소에 가장 가까워 보이는 함수 이름을 붙이는 일이 아니다. crash 때 실제로 불러온 바이너리 이미지의 UUID와 주소 기준을 읽고, 그 build와 짝을 이루는 dSYM을 찾는 일이다. 그 뒤 전체 crash 보고서와 공개 build 소스를 함께 읽어야 수정할 코드를 고를 수 있다.

스스로 확인할 질문

1. Binary Images에서 atos 입력으로 가져올 다섯 값은 무엇인가?
2. 앱 version과 build number가 같아도 dSYM UUID를 비교해야 하는 이유는 무엇인가?
3. 왜 .dSYM 바깥 경로가 아니라 내부 DWARF 파일을 atos에 전달하는가?
4. 주 앱, framework와 app extension에 각자 dSYM이 필요한 이유는 무엇인가?
5. 공개 build마다 xcarchive를 보관해야 하는 이유는 무엇인가?
6. 함수와 원본 줄을 복원한 뒤에도 전체 crash 보고서를 다시 읽는 이유는 무엇인가?