Sentry React Native: 2026년 통합 가이드

당신의 React Native 앱이 로컬에서 작동하고 QA가 승인했으며 프로덕션에 가까운 상태에서, 사용자의 장치에서 깨지면 발생하는 문제에 대한 명백한 질문이 나타납니다.

Sentry가 없다면 일반적으로 나쁜 결과가 발생합니다. 지원 티켓, 모호한 스크린샷, 개발 빌드의 콘솔 로그가 프로덕션과 일치하지 않는 경우가 있습니다. Sentry React Native가 올바르게 설정되면 오류, 스택, 배포한 릴리스, 충분한 컨텍스트를 제공하여 추측 없이 고칠 수 있습니다. 문제는 기본 설치는 쉬운 부분입니다.. 실제로 어려운 부분은 나중에 시작됩니다: 네이티브 통합, symbolication, 소스 맵, 릴리스 이름, 그리고 배포 모델이 실시간 업데이트를 포함할 때 모든 것을 일치시키는 것입니다.

대부분의 가이드는 너무 일찍 멈춥니다. 실제 설정은 CI, App Store 빌드, Android 릴리스, 그리고 원본 바이너리에서 항상 오리지널 바이너리에서 오지 않는 자바스크립트 번들을 포함한 JavaScript 번들을 살아남아야 합니다.

목차

• Sentry SDK와 함께 시작하기
  • 설치하기 전에 필요한 것
  • 위치 마법사 실행 및 결과 검토
• 네이티브 iOS 및 Android 프로젝트 구성
  • iOS에서 변경된 점
  • Android에서 변경된 점
  • 나중에 시간을 절약하는 네이티브 설정
• 릴리스와 소스 맵을 자동화
  • 실제 업로드가 실패하는 이유
  • 실제로 작동하는 릴리스 프로세스
  • 실용적인 CI 스크립트 패턴
• 성능 데이터와 사용자 지정 이벤트 캡처
  • 느린 화면 대신 추적하는 방법
  • 오류에 유용한 컨텍스트 추가
• 통합을 확인하고 문제 해결
  • 안전하게 테스트 이벤트 트리거
  • Sentry UI에서 확인해야 할 사항
  • Sentry React Native 일반적인 문제 해결
• 라이브 업데이트 워크플로우와의 통합 ( Capgo )
  • 릴리스 식별자와 라이브 배ंडल 매칭

Sentry SDK 시작하기

Sentry React Native를 새로운 앱에 빠르게 설치하는 가장 빠른 방법은 여전히 설치 마법사입니다. 대부분의 반복적인 설정을 처리하고 작업을 빠르게 시작합니다. 이것은 중요합니다. 첫 번째 설치를 수동으로 처리하면 첫 번째 프로덕션 오류가 발생할 때까지 작은 불일치가 발생할 수 있습니다.

설치하기 전에 필요한 것

정상적인 React Native 개발 환경이 필요합니다. Node, 패키지 관리자, iOS 및 Android의 플랫폼 도구, macOS에서 Watchman이 이미 워크플로우의 일부인 경우. 또한 Sentry 계정과 React Native용 프로젝트가 필요합니다.

React Native가 팀에 적합한 운영 선택인지 여부를 평가 중이라면 기업용 React Native 가이드 플랫폼의 트레이드 오프, 인력, 유지 보수 예상치에 대한 유용한 비마케팅 컨텍스트를 제공합니다. 이 가이드는 Sentry와 릴리스 프로세스를 공유하는 공유 코드베이스에 대한 모니터링과 커밋 프로세스를 결정하기 전에 읽어야 합니다.

프로젝트 루트에서 마법사를 사용하여 SDK를 설치합니다:

npx @sentry/wizard@latest -i reactNative

마법사가 몇 가지 질문을 합니다. 개발자들은 종종 너무 빠르게 클릭합니다:

• 프로젝트 선택. 실제로 프로덕션에서 사용할 Sentry 프로젝트를 선택하십시오. 나중에 업데이트를忘지 않는 임시 샌드박스를 선택하지 마십시오.
• Native 변경 사항. JavaScript-only 오류 캡처만으로는 모바일 앱을 위한 충분한 것은 아닙니다.
• 선택적 기능. 사용할 수 있는 기능을 모두 활성화하지 말고, 팀이 결과 데이터를 검토하지 못할 경우 첫 번째 날에 모든 것을 활성화하지 마십시오.

위치 마법사 실행 및 결과 검토

위치 마법사가 완료되면, 결과를 검토하기 전에 변경 사항을 검토하십시오. Sentry 패키지가 package.json, 네이티브 변경 사항이 ios , 그리고 앱 진입 파일의 초기화 블록이 android에서 보일 것입니다.

일반적인 초기화는 다음과 같습니다.

import * as Sentry from '@sentry/react-native';

Sentry.init({
  dsn: 'YOUR_DSN',
});

DSN은 __CAPGO_KEEP_0__에서 이벤트를 보낼 위치를 알려줍니다. 이에 대한 설정으로 다루십시오. 비밀 보관소의 항목으로 다루지 마십시오. 인증 토큰과는 다릅니다. 여전히 환경 설정이 깨끗하고 일관적일 수 있도록 앱이 각 환경에서 올바른 Sentry 프로젝트를 참조하도록 하십시오. The tells the SDK where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment.

환경 변수에 따라 DSN을 로드하고 앱 tree가 마운트되기 전에 Sentry를 초기화하는 실용적인 패턴입니다. 시작 순서를 다듬는 작업을 하는 경우, 이 React Native 스플래시 스크린 설정 가이드가 유용합니다. React Native 스플래시 스크린 설정 is useful because startup code order often intersects with where teams place Sentry initialization.

앱 시작 시 Sentry를 가능한 한 빠르게 초기화하십시오. 네비게이션, 인증, 원격 구성과 같은 작업이 끝난 후 초기화하는 경우, 시작 오류를 놓치게 됩니다. 이 단계에서는 완벽함을 추구하지 마십시오. 즉시 목표는 간단합니다: 앱을 출시하고, 이 문서의 나중에 설명하는 JavaScript 예외를 트리거하고, 이벤트가 Sentry로 도달하는지 확인하십시오. 그게 작동되면, 네이티브 및 릴리스层가 더 쉽게 이해됩니다.

Native iOS 및 Android 프로젝트 설정

이 단계에서 많은 React Native 팀은 JavaScript __CAPGO_KEEP_0__가 설치되고 이벤트가 표시되는 것을 보고, 충돌 보고가 완료된 것으로 착각합니다. 그러나 그렇지 않습니다. 네이티브 통합이 비활성화된 경우, 가장 중요하게 생각하는 충돌 중 일부는 Sentry에서 사용할 수 있는 형태로 도달하지 못할 것입니다.

At this stage, many React Native teams get a false sense of completion. The JavaScript SDK is installed, events show up, and everyone assumes crash reporting is done. It isn’t. If native integration is off, some of the crashes you care about most will never reach Sentry in a usable form.

iOS 프로젝트를 열고, 마법사가 변경한 것을 검토하십시오. Bare React Native 앱의 경우, 일반적으로 앱 시작과 빌드 단계와 관련된 업데이트가 있습니다. Sentry 초기화 hook 및 업로드 단계를 찾으십시오. 빌드 프로세스와 관련된 것입니다.

Xcode에서 확인할 곳은 다음과 같습니다.

앱 데몬 시작 __CAPGO_KEEP_0__']}

• App delegate startup code. 앱이 초기 런칭 시 네이티브 센트리 초기화를 필요로 합니다.
• 빌드 단계. 디버그 SYMBOL 또는 소스 맵 처리 관련된 센트리 업로드 스크립트를 찾으세요.
• 빌드 설정 및 아카이브 동작. 아카이브 빌드 시 SYMBOL 파일이 생성되어야 하며 사용 가능해야 합니다.

앱이 AppDelegate.mm을 사용하는 경우, 초기화는 종종 React Native 브릿지 부트스트래핑과 근접합니다. 정확한 파일 내용은 React Native 버전, 템플릿 및 새로운 아키텍처 사용 여부에 따라 달라질 수 있으므로, 프로젝트 형태와 일치하는 랜덤 리포지토리에서 Snippet을 복사하지 마세요.

중요한 것은 의도입니다: iOS 네이티브 크래시에서 SYMBOL 데이터가 필요하고 앱은 센트리 초기화가 크래시가 신뢰할 수 있게 관찰될 수 있도록 시작해야 합니다.

iOS 크래시가 센트리에서 읽을 수 없는 네이티브 프레임으로 나타나면, 일반적으로 문제는 “센트리가 깨진다”는 것이 아닙니다. SYMBOL 업로드 또는 릴리즈 매칭 문제입니다.

Android에서 변경된 사항은 무엇입니까

Android는 일반적으로 Gradle 파일의 변경과 때로는 매니페스트 수준 구성 변경을 포함합니다. android/build.gradle, android/app/build.gradle 및 센트리 관련 플러그인 또는 태스크 연결을 검토하세요.

__CAPGO_KEEP_0__

1. The Sentry Gradle 플러그인은 적용되어 빌드 시간에 릴리즈 아티팩트가 처리될 수 있습니다.
2. 변형 처리는 정상입니다. 제품 플래버 또는 여러 빌드 타입을 사용하는 경우입니다.
3. ProGuard 또는 R8의 출력이 __CAPGO_KEEP_0__의 릴리즈 빌드가 압축 또는 암호화되는 경우에 고려됩니다. if your release builds shrink or obfuscate code.

모바일 빌드 타입 은 각 빌드 변형과 모니터링 동작을 일치시키기 위해 유용한 참고 자료입니다. 나중에 시간을 절약하는 데 도움이 되는 네이티브 설정 확인

'마법사'가 파일을 수정했다는 것에만 중단하지 마십시오. 직접 동작을 확인하십시오.

이 안드로이드 빌드 타입의 분해는 디버그, 스테이징, QA 및 스토어 빌드를 유지하는 팀에게 유용한 참고 자료입니다.

이 체크리스트를 사용하세요:

• iOS 빌드를 로컬로 저장하고 symbol 처리 중에 빌드가 실패하지 않는지 확인하세요. 릴리즈 안드로이드 빌드를 생성하세요.
• CI 로그를 확인하여 Sentry 관련 작업이 있는지 확인하세요. 관리하는 여러 앱이 하나의 org 아래에 있는 경우 Sentry에서 패키지 이름과 번들 식별자 매핑을 확인하세요.
• CI가 불일치하는 이름으로 아티팩트를 업로드하기 전에 릴리즈 이름 규칙을 확인하세요. 일반적으로 잘 작동하지 않는 것은:
• 방법문제가 발생하는 이유

What goes wrong

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

SDK

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

• 누군가가 지연수정 후 맵을 업로드하지 않았습니다. 지연수정 후에 맵을 업로드하지 않았습니다.
• 업로드한 파일은 다른 커밋에 속합니다. 실행 중인 바이너리 또는 OTA 패키지와 다른 커밋에 속합니다.
• iOS, Android, CI 단계에서 릴리스 이름이 약간 다릅니다. 맵 업로드 후 재빌드가 발생하여 Sentry가 매칭해야 하는 대상이 무효화됩니다.
• 이것이 바로 Notion에서 단계를 문서화하는 방법이 긴급한 릴리스를 출시할 때까지는 작동하지만, 압박을 받는 긴급한 릴리스가 출시될 때까지는 작동하지 않는다는 이유입니다. React Native용 Sentry 릴리스 및 소스맵 관리를 자동화하는 7단계 플로우차트입니다.

실제로 작동하는 릴리스 프로세스입니다.

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

• __CAPGO_KEEP_0__ ID는 한 번 생성되고 모든 곳에서 재사용됩니다.
• 배포, 번들, 업로드 단계는 동일한 pipeline에서 발생합니다..
• 소스맵은 CI에서 업로드되며개발자 로컬에서 업로드되지 않습니다.
• 앱은 CI가 업로드 시 사용한 동일한 릴리스 문자열로 Sentry를 초기화합니다. 그 마지막 점은 일반적으로 예상되는 것보다 더 중요합니다. Sentry에 소스맵만 필요하지 않습니다.

정확한 릴리스 식별자가 앱이 런타임 시.emit하는 식별자와 일치하는 소스맵이 필요합니다. 팀이 이미 모바일 자동화에 표준화했다면.

__CAPGO_KEEP_0__ Actions와 함께 자동 배포 및 릴리스 워크플로에 대한 이 안내서 automatic build and release workflows with GitHub Actions __CAPGO_KEEP_0__ Actions

A practical CI 스크립트 패턴

CI에서 스크립트를 사용하여 pipeline 환경 변수에서 값을 제공하십시오:

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

안드로이드에 대한 번들 명령어를 적절히 조정하고, 많은 팀이 플랫폼별 작업을 분리하는 대신 하나의 스크립트를 사용하도록 강요하지 않습니다. 그건 괜찮습니다. 중요한 것은 일관성입니다.

릴리즈 규칙이 재미있는 스크립팅보다 더 중요합니다. 하나의 이름 규칙을 선택하고 빌드 시에 앱에 삽입하고, CI와 지역적으로 업로드하는 ad hoc 업로드와 경쟁하지 않도록 하십시오.

React Native의 경우, 릴리즈 문자열을 하나의 빌드 생성된 구성 위치에 저장하고, 해당 위치에서 읽도록 하는 것을 선호합니다. Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

결과는 간단합니다. 이벤트가 도착하면 Sentry는 미니파이드 프레임을 code로 매핑할 수 있습니다. 하지만 code로 생각하고 shipped한 것은 아닙니다.

성능 데이터 캡처 및 사용자 정의 이벤트

에러는 무엇이 깨졌는지 알려줍니다. 성능 추적은 사용자가 포기하기 전에 무엇을 느꼈는지 알려줍니다.

일반적인 보고서의 예는 다음과 같습니다. “대시보드는 느립니다.” 하지만 이는 디버깅을 위한 충분한 정보가 아닙니다. 느린 곳은 어디인가요? 네비게이션 중인가요? 데이터를 가져오는 중인가요? 무거운 차트를 렌더링하는 중인가요? Sentry는 에러 인박스처럼 다루지 않고 앱 동작을 인스트루먼트할 때 유용해집니다.

느린 화면을 추적하는 대신 추측하지 말고, Sentry를 에러 인박스처럼 다루지 않고 앱 동작을 인스트루먼트할 때 유용해집니다.

__CAPGO_KEEP_0__를 활성화하여 초기화 단계에서 성능 추적을 시작하세요. 정확한 샘플링 전략은 환경과 볼륨耐성에 따라 달라지지만 구조는 다음과 같습니다.

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

React Navigation을 사용하는 경우, 화면 전환을 통해 추적 데이터를 생성하도록 통합하세요. 그런 다음 물리적 장치에서만, 시뮬레이터에서만 reproducibility를 테스트하지 마세요. 시뮬레이터는 사용자가 느끼는 느린 속도와 같은 것을 숨깁니다.

실제적인 대시보드 예시:

1. 사용자가 로그인 후 메인 대시보드를 열 때.
2. 네비게이션 완료, 그러나 콘텐츠가 늦게 나타납니다.
3. 트레이스에서는 화면 거래가 길다는 것을 보여줍니다.
4. 자식 스팬은 하나의 API 요청과 하나의 비싼 렌더 경로를 드러냅니다.
5. 렌더 경로를 최적화하고 다시 배포한 후, 새로운 트레이스 형태를 비교하세요.

감각에 의한 추측보다 낫습니다.

웹뷰 또는 하이브리드 앱 모니터링 패턴에 대해 넓게 생각하는 팀에게는 Capacitor 프로젝트의 성능 모니터링에 대한 이 글을 읽어보는 것이 좋습니다. 운영 관점은 동일하지만 스택이 다르기 때문에.

Adding useful context to errors

오류에 유용한 정보를 추가하는 것

Performance data gets more useful when events carry business context. Not vanity metadata. Just enough to answer who was affected, what screen they were on, and what happened right before failure.

• 이러한 도구를 의도적으로 사용하세요: 사용자 정보 Sentry.setUser() with
• 이러한 정보를 사용하여 지원팀이 보고서를 사용자 계정과 관련시킬 수 있습니다. 경로
• 액션들(예: submit 버튼을 클릭, 모달을 열기, 동기화 시작)에서 for dimensions like plan type, feature flag state, or API region.
• 차원들(예: 플랜 타입, 기능 플래그 상태, __CAPGO_KEEP_0__ 지역)에서 예외가 발생한 경우에 추가 정보를 캡처합니다. 예외를 다시 던지거나 제어된 실패를 노출할 때.

예시:

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

브레드 크럼bs는 종종 사용자가 앱이 멈췄다고 말하는 것과 앱이 데스크톱을 열고 동기화를 시작하고 오래된 요청을 다시 시도한 후 실패한 것 사이의 차이를 나타냅니다.

사용자 지정 인스트루먼테이션의 오류는 일반적으로 너무 많은 노이즈로 인해 발생합니다. 앱의 모든 버튼 클릭을 영원히 캡처하지 마십시오. 디버깅을 위해 중요할 때만 캡처하십시오. 이벤트를 설명할 수 있는 충분한 컨텍스트를 제공하십시오. 이벤트를 설명할 수 있는 충분한 컨텍스트를 제공하십시오. 이벤트를 설명할 수 있는 충분한 컨텍스트를 제공하십시오.

통합을 확인하고 문제를 해결하는 방법

배송하기 전에, 빌드 PIPELINE 변경 후, 그리고 SDK 업그레이드 후 Sentry를 확인해야 합니다. “몇 달 전에는 작동했다”는 것은 의미가 없습니다.

제일 깨끗한 방법은 자바스크립트와 네이티브 경로 모두에 제어된 실패를 트리거하고 Sentry로 도착하는 방법을 검사하는 것입니다.

자바스크립트 오류의 경우, 비프로덕션 화면에 임시 버튼을 추가하십시오:

포획된 예외가 앱을 멈추지 않는 경우:

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

네이티브 크래시 테스트는 개발 또는 제어된 QA 빌드에서만 수행해야 합니다. 정확한 도우미 메소드가 __CAPGO_KEEP_0__ 버전과 플랫폼 연결에 따라 달라질 수 있으므로, 사용자 지정 크래시 경로를 만들기보다 __CAPGO_KEEP_1__의 문서화된 네이티브 크래시 테스트 유틸리티를 사용하는 것이 좋습니다.

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

Native crash testing should be done carefully and only in development or controlled QA builds. The exact helper methods available can vary by SDK version and platform wiring, so I prefer using the SDK’s documented native crash test utility when present rather than inventing your own crash path.

What to check in the Sentry UI

이벤트가 나타날 때 제목만으로는 충분하지 않습니다.

이 필드를 확인하세요:

• 플랫폼 및 메커니즘. JS 예외와 네이티브 충돌을 구분하기 위해 도움이 됩니다.
• 릴리즈 및 디스트. 비어 있거나 잘못된 경우 소스 맵과 심볼리케이션은 비정상입니다.
• 스택 프레임. 올바르게 업로드된 자바스크립트 맵에 대해 읽을 수 있는 소스 위치가 나타나야 합니다.
• 브레드크럼과 태그. 커스텀 컨텍스트가 올바르게 도착했는지 확인하세요.
• 환경. 개발 및 운영 이벤트가 혼합되지 않도록 하세요.

If a native event arrives but has poor symbolication, don’t keep tweaking app code. That’s usually a build artifact problem.

React Native Sentry 문제 해결

릴리스 프로세스에서 작고 '모니터링 스모크 테스트' 체크리스트를 유지하는 것이 유익한 습관입니다. 스테이징에서 하나의 JS 이벤트를 트리거하고, 릴리스 값을 확인하고, 소스 위치를 확인하기 전에 빌드를 승격합니다.

Capgo와 같은 Live Update 워크플로와 통합하는 것

라이브 업데이트가 릴리스 모델을 변경합니다. 스토어에 있는 바이너리는 동일한 채로 유지될 수 있지만, 아래에 있는 JavaScript 번들을 변경할 수 있습니다. Sentry가 여전히 원래 앱 버전만을 고려한다면, 스택 트레이스들은 속도감 있게 오해를 일으킵니다.

해결책은 라이브 번들을 따라하는 Sentry 릴리스 식별자가 아니라, 원본 네이티브 바이너리만을 따라하는 것입니다.라이브 업데이트 워크플로에서 릴리스 식별자를 라이브 번들에 매칭합니다.

라이브 업데이트 워크플로에서

와 release 를 배달된 JavaScript 패키지와 관련된 런타임 식별자로 다룹니다. 네이티브 앱 버전은 여전히 중요하지만, 독립적으로 변경될 수 있는 번들이 있으면 충분하지 않습니다. dist 실용적인 패턴은 이렇습니다:

라이브 업데이트 워크플로에서 네이티브 앱 버전과 JavaScript 번들을 모두 고려해야 합니다.

• native 앱 버전을 기본 릴리스 이름의 일부로 사용하세요.
• live 업데이트 버전 또는 패키지 식별자를 추가하세요.
• 사용 dist 릴리스 이름에 channel 또는 빌드에 대한 구분을 위해 사용하세요. 그게 당신의 모델에 맞을 때.
• 각 live 번들을 위한 소스맵을 정확한 릴리스 식별자 아래 업로드하세요.

예를 들어, 앱이 런타임에 업데이트 메타데이터를 로드한다면, 현재 활성 번들을 기준으로 초기화하는 대신 정적 빌드 구성에서만 Sentry를 초기화하세요.

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

이러한 방식으로, 사용자가 핫픽스된 번들에서 오류를 만나면 Sentry는 핫픽스 대신에 더 오래된 스토어 번들을 기준으로 프레임을 해결하지 않습니다.

이것은 OTA-style 워크플로우와 관련하여 중요합니다. OTA-style 워크플로우의 움직이는 조각에 대한 좋은 프라이머를 원한다면, __CAPGO_KEEP_0__ 앱에서 live 업데이트 작동 방식에 대한 설명을 참조하세요. how live updates work in Capacitor apps https://__CAPGO_KEEP_0__.app에서 스크린샷

__CAPGO_KEEP_0__ 앱에서 live 업데이트 작동 방식에 대한 설명

The main mistake to avoid is reusing one static release string for every post-store update. If multiple bundles share the same Sentry release, debugging turns into guesswork again.

If your team ships fixes outside app store review cycles, Capgo is worth evaluating. It gives Capacitor teams a structured way to deliver live updates, target channels, control rollouts, and recover from bad releases quickly. Pair that with disciplined Sentry release naming and source map uploads, and you get a workflow where errors still point to the exact code users are running.