Sentry React Native: 2026년 통합 가이드

로컬에서 React Native 앱이 작동 중일 때, QA가 승인했으며 프로덕션 근처에 있을 때, 사용자 장치에서 깨지면 발생하는 문제에 대한 명백한 질문이 있습니다.

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

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

목차

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

SDK

Sentry React Native를 시작하는 방법

설치 마법사를 사용하여 Sentry React Native를 새로운 앱에 빠르게 설치할 수 있습니다. 마법사는 반복적인 설정을 처리하고 빠르게 작동하는 기본선을 얻을 수 있도록 도와줍니다. 이것은 중요합니다. 첫 번째 설치를 수동으로 처리하면 첫 번째 프로덕션 오류가 발생할 때까지 작은 불일치가 발생할 수 있습니다.

설치하기 전에 필요한 것

React Native 개발 환경이 필요합니다. Node, 패키지 관리자, iOS 및 Android용 플랫폼 도구, macOS에서 Watchman이 이미 워크플로우의 일부일 경우. 또한 Sentry 계정과 React Native용 프로젝트가 생성된 상태여야 합니다. React Native가 팀의 운영 선택이 맞는지 여부를 평가 중이라면 React Native를 위한 기업용 가이드

Install the SDK with the wizard from the project root:

npx @sentry/wizard@latest -i reactNative

Sentry React Native를 프로젝트 루트에서 마법사에서 설치하세요:

• 마법사는 몇 가지 질문을 합니다. 개발자들은 종종 너무 빠르게 클릭합니다:프로젝트 선택
• . 실제로 프로덕션에서 사용할 Sentry 프로젝트를 선택하십시오. 나중에 업데이트를忘지 않는 임시 샌드박스를 선택하지 마십시오.. JavaScript-only 오류 캡처만으로는 모바일 앱을 충분히 다루지 못합니다.
• 선택적 기능. 사용할 수 있는 기능을 켜되, 팀이 결과 데이터를 검토하지 못할 경우 모든 기능을 일단 켜지 마십시오.

위자드 실행 및 결과 검토

위자드가 완료되면 결과를 신뢰하지 않고 검토하십시오. Sentry 패키지가 package.json, native 변경 사항이 ios 에 보입니다. android, 그리고 앱의 진입점 파일에 초기화 블록이 있습니다.

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

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

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

DSN은 __CAPGO_KEEP_0__ 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.

A React Native 앱에서 Sentry를 사용하는 데 있어 중요한 패턴은 환경에 따라 DSN을 로드하고 앱 tree가 마운트되기 전에 Sentry를 초기화하는 것입니다. 만약 스타트업 폴리시를 개선하는 중이라면, 이 __CAPGO_KEEP_0__에 대한 가이드는 유용합니다. React Native 스플래시 화면 설정 이 단계에서, code을 초기화하는 것이 중요합니다. 네비게이션, 인증, 리모트 구성과 같은 다른 작업을 기다리면 스타트업 오류를 놓치게 됩니다.

이 단계에서는 완벽함을 추구하지 마십시오. 즉시 목표는 앱을 출시하고 나중에 이 문서에서 설명하는 JavaScript 오류를 발생시키고, 이벤트가 Sentry로 전송되는지 확인하는 것입니다. 그 후, 네이티브 및 릴리스层가 더 쉬운 논리를 갖게 됩니다. 네이티브 iOS 및 Android 프로젝트 구성

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

iOS에서 변경된 사항

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.

Xcode에서 다음 위치를 확인하십시오:

앱 데리케이터의 스타트업 __CAPGO_KEEP_0__

앱 데리케이터의 스타트업 __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을 검토하고 센트리 관련된 플러그인 또는 태스크 연결을 확인하세요.

확인해야 할 사항:

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

릴리즈 빌드 유형 릴리즈 빌드 유형에 대한 이 설명은 모바일 빌드 유형에 대한 유용한 참고 자료입니다. 네이티브 설정 확인은 나중에 시간을 절약하는 데 도움이 됩니다.

‘마법사’가 파일을 수정했다는 것을 확인하는 것만으로 충분하지 않습니다. 직접 동작을 확인하세요.

릴리즈 아티팩트가 빌드 시간에 처리될 수 있습니다.

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

• iOS 빌드를 로컬에 저장하세요 symbol 처리 중에 빌드가 실패하지 않는지 확인하세요.
• Android 릴리즈 빌드를 생성하세요 CI 로그를 확인하여 Sentry 관련 작업이 있는지 확인하세요.
• 관리하는 여러 앱이 하나의 org 아래 있는 경우 Sentry에서 패키지 이름과 번들 식별자 매핑을 확인하세요. 릴리즈 이름 규칙을 확인하세요
• , CI가 불일치하는 이름으로 아티팩트를 업로드하기 전에.이게 잘 안되는 경우는 다음과 같습니다:

방법

최고의 설정은 흥미롭지 않습니다. Native 시작 hook이 설정되어 빌드 스크립트가 매번 실행되고, iOS, Android, JavaScript 번들에 걸쳐 릴리스 이름이 결정적입니다.

릴리스와 소스 맵 자동화

SDK

자동화된 릴리스와 소스 맵

Sentry React Native 설정이 무너지는 곳은 여기입니다. 팀은 __CAPGO_KEEP_0__를 설치하고 이벤트를 볼 수 있고 릴리스 자동화를 미루게 됩니다. 그런 다음 첫 번째 심각한 프로덕션 문제가 발생하고 스택 트레이스에 미니파이팅이 적용되어 릴리스가 누락되거나 소스 맵 업로드가 다른 번들에 속해있었습니다.

수동 소스 맵 업로드는 드물게 배포하는 경우에는 합리적으로 보입니다. 그러나 실제로는 반복적인 릴리스 관리를 수행하는 인간이 실패하기 때문입니다.

• 누군가가 맵을 업로드하지 못했다 밤늦은 시간에 핫픽스를 적용한 후
• 업로드한 파일은 다른 커밋에 속한다 실행 중인 바이너리 또는 OTA 패키지 사용자와 다르다.
• 릴리즈 이름은 iOS, Android, CI 단계에서 약간 다르다. 맵 업로드 후 재빌드가 발생하여 Sentry가 매칭해야 하는 대상이 무효화된다.
• 이것이 내가 'Notion'에서 단계를 문서화하는 방법을 추천하지 않는 이유이다. 그것은 한 번에 긴급 릴리즈가 출시될 때까지 작동한다. 리액트 네이티브용 세일런트 릴리즈 및 소스 맵 관리를 위한 자동화된 프로세스의 7단계 플로우 차트이다.

실질적인 릴리즈 프로세스를 갖춘다

7단계의 자동화된 프로세스

실질적인 릴리즈 프로세스를 갖춘다

• 릴리스 ID는 한번 생성되고 모든 곳에서 재사용됩니다.
• 빌드, 번들, 업로드 단계는 동일한 pipeline에서 발생합니다..
• 소스맵은 CI에서 업로드되며개발자 노트북에서 업로드되지 않습니다.
• 앱은 CI가 업로드할 때 사용한 동일한 릴리스 문자열로 Sentry를 초기화합니다. 이 마지막 점은 일반적으로 예상되는 것보다 더 중요합니다. Sentry에 소스맵만 필요하지 않습니다. 정확한 릴리스 식별자가 앱이 런타임에서 내뿜는 식별자와 연결된 소스맵이 필요합니다.

만약 팀이 이미 모바일 자동화에 표준화했다면, 이 __CAPGO_KEEP_0__ Actions를 사용하는 자동 빌드 및 릴리스 워크플로의 가이드에 잘 맞습니다. 이 가이드는 CI/CD 파이프라인을 구축하는 데 도움이 될 것입니다..

이 가이드는 CI/CD 파이프라인을 구축하는 데 도움이 될 것입니다. automatic build and release workflows with GitHub Actions 이 가이드는 CI/CD 파이프라인을 구축하는 데 도움이 될 것입니다.

A practical CI script pattern

CI 스크립트 패턴을 사용하세요.

#!/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 스크립트 패턴을 사용하기 위해서는 CI에서 다음 스크립트를 사용하세요.

Android용 빌드 명령어를 적절히 조정하고, 플랫폼에 따라 작업을 나누어야 합니다. 하지만 일관성을 유지하는 것이 중요합니다. Release discipline beats clever scripting.

CI에서 사용하는 이름 규칙을 선택하고, 앱에 빌드 시에 규칙을 적용하고, 로컬 업로드와 CI 업로드를 구분하세요. Sentry.init():

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

The payoff is simple. When an event arrives, Sentry can map the minified frame back to the code you shipped, not the code you think you shipped.

릴리즈 문자열을 저장하는 위치는 중요하지 않습니다. 중요한 것은 일관성입니다.

릴리즈 문자열을 저장하는 위치는 중요하지 않습니다. 중요한 것은 일관성입니다.

릴리즈 문자열을 저장하는 위치는 중요하지 않습니다. 중요한 것은 일관성입니다.

릴리즈 문자열을 저장하는 위치는 중요하지 않습니다. 중요한 것은 일관성입니다. Sentry는 앱의 동작을 모니터링하여, 사용자가 느끼는 문제를 파악할 수 있습니다.

__CAPGO_KEEP_0__

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

React Native에서 사용하는 Sentry를 활성화하기 위해 시작하세요. 정확한 샘플링 전략은 환경과 볼륨 tolerance에 따라 달라지지만 구조는 다음과 같습니다.

React Navigation을 사용하는 경우, 화면 전환을 통해 트레이스 데이터를 생성하도록 통합하세요. 그런 다음 물리 장치에서만 불량 신고를 재현하세요. 시뮬레이터는 사용자가 느끼는 느린 속도에 대한 정보를 숨깁니다.

1. 실용적인 대시보드 예시:
2. 사용자는 로그인 후 메인 대시보드를 열어보세요.
3. 네비게이션 완료되지만 콘텐츠가 늦게 나타납니다.
4. Child spans reveal one API request and one expensive render path.
5. 자식 스팬은 하나의 __CAPGO_KEEP_0__ 요청과 하나의 비싼 렌더 경로를 드러냅니다.

렌더 경로를 최적화하고 다시 배포한 후, 새로운 트레이스 형태를 비교하세요.

감정에 의한 추측보다 더 나은 결과입니다. 웹뷰 또는 하이브리드 앱 모니터링 패턴에 대해 넓게 생각하는 팀에게는 Capacitor 프로젝트에서 성능 모니터링에 대한 이 글을 읽어보는 것이 도움이 될 것입니다. 성능 모니터링

오류에 유용한 맥락을 추가하는 방법

성능 데이터가 더 유용해질 때는 이벤트가 비즈니스 맥락을 포함해야 합니다. 그것은 자랑하는 메타데이터가 아니라, 실패 직전의 상황, 영향을 받은 사용자, 그리고 실패한 화면을 알 수 있게 해주는 정도입니다.

이러한 도구를 의도적으로 사용하세요:

• 사용자 맥락 with Sentry.setUser() 지원팀이 보고서를 사용자 계정과 관련시킬 수 있도록 guesswork를 피할 수 있도록 합니다.
• 액션의 기록 서브밋 버튼을 클릭하거나 모달을 열거나 싱크를 시작하는 등
• 차원에 대한 커스텀 태그 계획 유형, 기능 플래그 상태, 또는 API 지역과 같은
• 추가 맥락이 포함된 캡처된 예외 예외를 캐치하고 다시 던지거나 제어된 실패를 표면화할 때

예시:

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');
  }}
/>

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

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

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

Sentry UI에서 확인해야 할 내용

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

다음 필드를 확인하세요:

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

native 이벤트가 도착하지만 symbolication이 좋지 않다면, 앱 code을 계속 조정하지 마십시오. 일반적으로 빌드 아티팩트 문제입니다.

Sentry React Native 일반적인 문제 해결

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

라이브 업데이트 워크플로와의 통합, Capgo

라이브 업데이트에서는 릴리스 모델이 바뀌게 됩니다. 스토어에 있는 바이너리는 동일한 채로 유지될 수 있지만 JavaScript 번들 아래에 있는 내용이 바뀌게 됩니다. Sentry가 여전히 원래 앱 버전만 생각한다면 스택 트레이스에 오류가 빠르게 발생합니다.

해결책은 Sentry 릴리스 식별자가 라이브 번들을 따라야 합니다.라이브 업데이트 워크플로에서 릴리스 식별자를 라이브 번들과 매칭시킵니다.

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

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

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

• 자연어 앱 버전을 기본 릴리스 이름의 일부로 사용하세요.
• 실시간 업데이트 버전 또는 패키지 식별자를 추가하세요.
• 사용 dist 채널 또는 빌드에 대한 구별을 위해 모델에 맞게 사용하세요.
• 해당 정확한 릴리스 식별자 아래에서 각 실시간 번들을 업로드하는 소스 맵을 업로드하세요.

예를 들어, 앱이 시작 시 업데이트된 메타데이터를 로드한다면, 현재 활성 번들을 사용하여 Sentry를 초기화하세요. 정적 빌드 구성만으로는 충분하지 않습니다.

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

이러한 방식으로 사용자가 핫픽스된 번들에서 오류를 발생시킬 때, Sentry는 핫픽스 대신에 이전 스토어 번들의 소스 맵으로 프레임을 해결합니다.

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

__CAPGO_KEEP_0__

주된 실수를 피해야 하는 것은 하나의 정적 릴리스 문자열을 모든 포스트 스토어 업데이트에 사용하는 것입니다. 여러 번들이 동일한 Sentry 릴리스를 공유할 경우 디버깅은 다시 추측의 문제가 됩니다.

앱 스토어 리뷰 사이클 외에 팀이 수정 사항을 배포한다면 Capgo 팀이 Capacitor을 사용하면 라이브 업데이트를 전달하는 구조화된 방법을 제공하고 채널을 대상으로 하며 롤아웃을 제어하고 나쁜 릴리스에서 빠르게 복구할 수 있습니다. 정제된 Sentry 릴리스 이름과 소스 맵 업로드를 pair하면 에러가 여전히 정확한 code 사용자들이 실행 중인 code을 가리키게 됩니다.