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 )
  • 릴리스 식별자와 라이브 배ंडल 매칭

Sentry SDK 시작하기

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

설치하기 전에 필요한 항목

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

React Native가 팀의 운영 선택으로 적합한지 여부를 평가 중이라면 기업용 React Native 가이드 플랫폼의 거래-offs, 인력, 유지 보수 예상치에 대한 유용한 비판적 콘텍스트를 제공합니다. 이 가이드는 모니터링 및 릴리스 프로세스를 공유 코드베이스에 적용하기 전에 읽어야 합니다.

프로젝트 루트에서 SDK를 마법사와 함께 설치하세요:

npx @sentry/wizard@latest -i reactNative

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

• 프로젝트 선택생산 환경에서 사용할 Sentry 프로젝트를 선택하세요. 임시 샌드박스를 사용하여 나중에 업데이트를 잊지 마세요.
• 네이티브 변경. JavaScript-only 오류 캡처만으로는 모바일 앱을 위한 충분한 것은 아닙니다.
• 선택적 기능. 사용할 수 있는 기능을 켜되, 팀이 결과 데이터를 검토하지 못할 경우 첫날에 모든 기능을 무작위로 켜지 마십시오.

위자드 실행 및 결과 검토

위자드가 완료되면, 결과를 신뢰하지 않고 검토하십시오. Sentry 패키지를 package.jsonnative 변경 사항이 ios 및 android에서 볼 수 있습니다.

그리고

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

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

앱 진입 파일에서 초기화 블록이 있습니다. 일반적인 초기화는 다음과 같습니다: DSN은 SDK에서 이벤트를 보낼 위치를 알려줍니다. 그것은 구성으로 다루어져야 하며, 비밀 보관소 항목으로 다루어져서는 안 됩니다. 그것은 인증 토큰과 다르며, 환경 설정이 깨끗하고 일관적일 때 앱이 올바른 Sentry 프로젝트를 각 환경에서 참조하도록 하십시오.

A React Native 앱에서 Sentry를 초기화하는 데 사용할 수 있는 실용적인 패턴은 환경에 따라 DSN을 로드하고 앱 tree가 마운트되기 전에 Sentry를 초기화하는 것입니다. 만약 스타트업 폴리시를 개선하는 중이라면 이 __CAPGO_KEEP_0__ React Native 스플래시 화면 설정 은 유용합니다. 스타트업 code 순서가 Sentry 초기화 위치와 겹치는 경우가 많기 때문입니다.

실용적인 규칙: Sentry를 가능한 한 빠른 시점에 앱 스타트업에서 초기화하세요. 네비게이션, 인증, 리모트 구성과 같은 작업이 끝난 후 초기화한다면 스타트업 오류를 놓치게 됩니다.

이 단계에서는 완벽함을 추구하지 마세요. 즉시 목표는 간단합니다: 앱을 출시하고 이 문서의 나중에 발생하는 자바스크립트 예외를 트리거하고 Sentry로 이벤트가 도달하는지 확인하세요. 그게 작동하면 네이티브 및 릴리스层가 더 쉬운 논리를 갖게 됩니다.

네이티브 iOS 및 Android 프로젝트 구성

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

iOS에서 변경된 사항

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

Xcode에서 다음 위치를 확인하세요:

• 앱 데리게이트 스타트업 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.

릴리즈 경로는 빌드 타입이 다르며, 특히 최소화 및 CI 서명이 포함된 경우가 많습니다. 팀이 별도의 디버그, 스테이징, QA, 및 스토어 빌드를 유지하는 경우 이 모바일 빌드 타입의 분해는 각 빌드 변형에 맞춰 모니터링 동작을 일치시키기 위한 유용한 참고 자료입니다.

네이티브 설정 확인이 나중에 시간을 절약하는 데 도움이 됩니다

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

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

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

방법

최고의 설정은 흥미롭지 않다. 네이티브 시작 hook이 설정되어 빌드 스크립트가 매번 실행되고, iOS, Android 및 JavaScript 번들에 대한 릴리스 이름이 결정적이다.

릴리스와 소스 맵 자동화

SDK를 설치하여 이벤트를 볼 수 있지만 릴리스 자동화를 연기하는 팀이 있습니다. 그 다음 심각한 프로덕션 문제가 발생하면 스택 추적이 미니파이드, 릴리스가 누락되거나 소스 맵 업로드가 다른 번들에 속한 경우가 있습니다.

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

실제로 수동 업로드가 실패하는 이유

실패 모드는 예측할 수 있습니다:

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

실질적인 릴리즈 프로세스를 구축하는 방법

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

정확한 릴리즈 프로세스를 구축하는 방법

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

정확한 릴리즈 아이디가 앱이 런타임에서 내뿜는 것과 정확히 매치되는 소스맵이 필요합니다. 팀이 이미 모바일 자동화 표준화를 이미 시작했다면, 이 __CAPGO_KEEP_0__ Actions를 사용하는 자동 빌드 및 릴리즈 워크플로의 안내서.

동일한 운영 모델과 잘 맞습니다. GitHub __CAPGO_KEEP_0__

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 스크립트를 사용하여 pipeline 환경에서 값을 입력하세요.

Android용 배포 명령어를 적절히 조정하고, 플랫폼별 작업을 분리하는 것이 좋습니다. 하지만, CI 스크립트를 둘 다 처리하도록 강요하는 것은 피하세요. 중요한 것은 일관성입니다. Release discipline beats clever scripting.

CI에서 사용하는 이름 규칙을 선택하고, 앱에 빌드 시에 주입하고, 로컬 업로드와 CI 업로드를 혼동하지 마세요. Sentry.init():

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

React Native에서, 나는 빌드 시에 생성된 code 위치에 릴리스 문자열을 저장하고, code을 읽는 것을 선호합니다.

릴리스 문자열을 저장하고 읽는 것은 간단합니다. 이벤트가 발생하면, Sentry는 __CAPGO_KEEP_0__을 읽어 __CAPGO_KEEP_1__을 읽어오지 않습니다.

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

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

소프트웨어 개발자가 데이터 시각화 그래프를 배경 모니터에 표시한 채로 노트북에 코드를 작성하는 모습입니다. 느린 화면을 추적하는 대신 추측하지 마세요.

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

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

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

실용적인 대시보드 예시:

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

감정에 의한 추측보다 더 나은 결과를 얻었습니다.

웹뷰 또는 하이브리드 앱 모니터링 패턴에 대해 넓게 생각하는 팀에게는 __CAPGO_KEEP_0__ 프로젝트에서 성능 모니터링에 대한 이 글을 읽어보는 것이 가치가 있습니다. performance monitoring in Capacitor projects 이 글을 읽어보세요.

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

성능 데이터가 더 유용해질 때는 이벤트가 비즈니스 맥락을 포함해야 합니다. 자랑하기 위한 메타데이터가 아닌, 오류가 발생하기 직전의 상황, 영향을 받은 사용자, 화면에 어떤 작업을 수행한지에 대한 정보입니다.

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

• 사용자 맥락 사용자 지원 팀이 보고서를 사용자 계정과 관련시킬 수 있도록 guesswork를 피하기 위해. Sentry.setUser() 액션의 기록
• submit 버튼을 클릭하거나 모달을 열거나 sync를 시작할 때. 차원에 대한 커스텀 태그
• plan 유형, feature flag 상태, 또는 __CAPGO_KEEP_0__ 지역과 같은. for dimensions like plan type, feature flag state, or API region.
• 오류를 다시 던지거나 제어된 실패를 노출할 때. 이러한 도구를 의도적으로 사용하세요:

예시:

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는 종종 "앱이 멈췄다"고 말하는 사용자와 "대시보드 열기, 싱크 시작, 스태일 요청 다시 시도" 후 앱이 실패한 경우를 구분하는 것입니다.

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

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

SDK 배포 전에, 빌드 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 버전과 플랫폼 연결에 따라 사용할 수 있는 exact helper 메소드가 달라질 수 있으므로, SDK의 문서화된 네이티브 크래시 테스트 유틸리티를 사용하는 것이 좋습니다.

Sentry UI에서 확인해야 할 항목

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

다음 필드를 확인하세요:

• 플랫폼 및 메커니즘이것은 JS 예외와 네이티브 충돌을 구분하는 데 도움이 됩니다.
• 릴리즈 및 디스트이들이 빈거나 잘못된 경우 소스맵과 symbolication이 비틀릴 것입니다.
• 스택 프레임정확히 업로드된 자바스크립트 맵에 대한 읽을 수 있는 소스 위치가 나타날 것입니다.
• 브레드크럼과 태그사용자 정의 컨텍스트가 도착했는지 확인하세요.
• 환경개발 및 운영 이벤트가 혼합되지 않도록 하세요.

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

Sentry React Native 일반적인 문제 해결

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

Capgo와 같은 라이브 업데이트 워크플로와 통합하는 것입니다.

라이브 업데이트 모델은 릴리스 모델을 바꿉니다. 스토어에 있는 바이너리는 동일한 채로 유지될 수 있지만 JavaScript 번들 아래에 있는 JavaScript가 변경될 수 있습니다. Sentry가 여전히 원래 앱 버전만 생각한다면 스택 트레이스에는 속도가 빠르게 오류가 생깁니다.

해결책은 라이브 번들을 따라하는 Sentry 릴리스 식별자입니다.라이브 업데이트 워크플로에서,

라이브 번들을 따라하는

runtime identifier release delivered JavaScript package dist runtime identifier

runtime identifier

• 자연스러운 앱 버전을 기본 릴리스 이름의 일부로 사용하세요.
• 실시간 업데이트 버전 또는 패키지 식별자를 추가하세요.
• 사용 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__ 앱에서 실시간 업데이트 방법에 대한 것입니다.

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.