Sentry React Native: 2026 통합 가이드

당신의 React Native 앱이 로컬에서 작동하고 QA가 승인했으며 프로덕션이 가까워지면, 사용자의 장치에서 깨지면 어떻게 될까?

Sentry가 없다면 일반적으로 나쁜 결과가 나온다. 지원 티켓, 모호한 스크린샷, 개발 빌드의 콘솔 로그가 프로덕션 빌드와 일치하지 않는 경우가 많다. Sentry React Native를 올바르게 설정하면 에러, 스택, 배포한 버전, 그리고 고칠 수 있는 충분한 컨텍스트를 얻을 수 있다. 하지만 기본적인 설치는 쉬운 부분이다.. 그러나 고통스러운 부분은 나중에 온다: 네이티브 통합, symbolication, 소스 맵, 배포 이름, 그리고 CI, App Store 빌드, Android 배포, 그리고 원본 바이너리에서 오지 않는 자바스크립트 번들을 포함하는 배달 모델을 유지할 때

대부분의 가이드가 너무 일찍 멈춘다. 실제 설정은 CI, App Store 빌드, Android 배포, 그리고 자바스크립트 번들이 원본 바이너리에서 오지 않는 경우를 포함하는 배달 모델을 유지할 때 살아남아야 한다.

목차

• Getting Started with the Sentry SDK
  • Sentinel과 함께 시작하기
  • 설치하기 전에 필요한 것
• 자연 iOS 및 안드로이드 프로젝트 설정
  • 위치: page blog/[slug].astro. 메시지 키 `what_you_need_before_installing` (설치하기 전에 필요한 것)
  • 안드로이드에서 변경된 사항
  • 앞으로 시간을 절약하는 네이티브 설정 확인
• 릴리즈와 소스 맵을 자동화
  • 실제로 실패하는 수동 업로드의 이유
  • 실질적으로 유지되는 릴리즈 프로세스
  • 실용적인 CI 스크립트 패턴
• 성능 데이터와 커스텀 이벤트 캡처
  • 느린 화면 대신 추적하는 방법
  • 오류에 유용한 컨텍스트 추가
• 인터그레이션을 검증하고 문제를 해결
  • 안전하게 테스트 이벤트를 트리거
  • Sentry UI에서 확인해야 할 사항
  • React Native Sentry 일반 문제 해결
• Live Update와 Capgo 워크플로와의 통합
  • 실시간 배포 식별자와 매칭

Sentry SDK를 사용한 시작

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

설치하기 전에 필요한 것

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

React Native가 팀의 운영 선택으로 적합한지 여부를 평가 중이라면 React Native 비즈니스 가이드 플랫폼의 상호 작용, 인력, 유지 보수 기대치를 포함한 유용한 비마케팅 컨텍스트를 제공합니다. 공유 코드베이스에 대한 모니터링 및 릴리스 프로세스를 확정하기 전에 읽어보세요.

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

npx @sentry/wizard@latest -i reactNative

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

• 프로젝트 선택. 실제 운영에 사용할 Sentry 프로젝트를 선택하세요. 임시로 생성한 샌드박스를 업데이트하지 않고 잊어버리게 되면 안 됩니다.
• 네이티브 변경. 모바일 앱을 위한 JavaScript만으로 오류 캡처는 충분하지 않습니다.
• 선택적 기능. 사용할 것 같은 기능을 켜세요. 그러나 팀이 결과 데이터를 검토하지 않으면 모든 기능을 일단 켜지 마세요.

위자드 실행 및 결과 검토

위자드가 완료되면 결과를 검토하기보다는 변경 사항을 검토하세요. Sentry 패키지가 package.json__CAPGO_KEEP_0__ ios 에서 android__CAPGO_KEEP_1__

에 보이게 됩니다. 그리고 앱의 진입점 파일에 초기화 블록이 추가됩니다.

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

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

The DSN SDK

configuration DSN 애플리케이션 시작 시점 code 순서가 종종 팀이 Sentry 초기화를 어디에 두는지와 겹치기 때문에 유용합니다.

React Native splash screen

__CAPGO_KEEP_0__

React Native

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.

Configuring Native iOS and Android Projects

iOS 프로젝트를 열고 마법사가 변경한 것을 검토하세요. bare React Native 앱에서, 일반적으로 앱 시작과 빌드 단계 주변에 업데이트가 발생합니다. Sentry 초기화 훅과 업로드 단계를 찾으려면 빌드 프로세스와 관련이 있습니다.

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

• 앱 델리게이트 시작 code. 앱이 초기화에 native Sentry를 필요로 합니다.
• 빌드 단계. 디버그 SYMBOL 또는 소스 맵 처리와 관련된 Sentry 업로드 스크립트를 찾으세요.
• 빌드 설정 및 아카이브 동작. Symbol 파일이 생성되고 아카이브 빌드 중에 사용 가능해야 합니다.

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

중요한 것은 의도입니다: iOS native 충돌은 Symbol 데이터가 필요하고 앱은 충돌을 신뢰할 수 있는 방식으로 관찰하기 전에 Sentry를 시작해야 합니다.

iOS 충돌이 Sentry에서 읽을 수 없는 native 프레임으로 나타나면, 문제는 "Sentry가 깨졌습니다."가 아닙니다. 일반적으로 Symbol 업로드 또는 릴리즈 매칭 문제입니다.

안드로이드에서 변경된 사항은?

안드로이드는 일반적으로 Gradle 파일과 때로는 매니페스트 수준 구성 변경을 포함합니다. Review android/build.gradle, android/app/build.gradle, 그리고 Sentry 관련 플러그인 또는 작업 연결입니다.

검증해야 할 사항:

1. Sentry Gradle 플러그인이 적용되어 릴리스 아티팩트가 빌드 시간에 처리될 수 있습니다.
2. 변형 처리는 제품 플래버 또는 여러 빌드 타입을 사용하는 경우 정상적입니다. 제품 플래버 또는 여러 빌드 타입을 사용하는 경우.
3. 프로 가드 또는 R8 출력물은 고려됩니다. release 빌드가 code을 압축하거나 난독화할 경우

분해 은 이 문서는 빌드 버전별로 모니터링 동작을 유지하기 위한 유용한 참고 자료입니다.

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

‘마법사’가 파일을 수정했다고 말하는 것에서 멈추지 마세요. 직접 동작을 확인하세요.

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

• iOS 빌드를 로컬에 저장하세요 symbol 처리 중에 빌드가 실패하지 않는지 확인하세요.
• 릴리즈 Android 빌드를 생성하세요 Sentry 관련 작업에 대한 CI 로그를 검사하세요.
• 관리하는 여러 앱이 하나의 조직 하에 있는 경우 Sentry에서 패키지 이름과 번들 식별자 매핑을 확인하세요. 릴리즈 이름 규칙을 확인하세요
• CI가 불일치하는 이름으로 아티팩트를 업로드하기 전에.__CAPGO_KEEP_0__

이런 것이 잘 작동하지 않는다:

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

릴리스와 소스 맵 자동화

Sentry React Native 설정이 무너지는 곳은 여기다. 팀은 SDK를 설치하고 이벤트를 확인하고 릴리스 자동화를 미루고 있다. 그런 다음 첫 번째 심각한 프로덕션 문제가 발생하고 스택 추적이 미니파이즈되거나 릴리스가 누락되거나 소스 맵 업로드가 다른 번들에 속한다.

정기적으로 배포하지 않는 경우에는 수동으로 매핑 업로드가 받아들여질 수 있습니다. 그러나 실제로는 실패합니다. 왜냐하면 인간은 반복적인 릴리스 관리에 취약하기 때문입니다.

실무에서 수동 업로드가 실패하는 이유

실패 모드는 예측 가능합니다:

• 누군가가 늦은 밤의 핫픽스 후에 매핑을 업로드하지 않습니다. 업로드한 파일은 바이너리 또는 OTA 버전을 실행하는 사용자가 실행하는 커밋과 다릅니다.
• iOS, Android, CI 단계 간에 릴리스 이름이 약간 다릅니다. 매핑 업로드 후에 재빌드가 발생하여 Sentry가 매칭해야 하는 것이 무효화됩니다.
• 릴리스 이름이 약간 다릅니다. Someone forgets to upload maps
• after a late-night hotfix. The uploaded files belong to a different commit

than the binary or OTA bundle users run.

실제로 릴리스 프로세스를 유지하는 방법

신뢰할 수 있는 설정에는 몇 가지 특성이 있습니다.

• 릴리스 ID는 한 번 생성되고 어디서든 재사용됩니다. 빌드, 번들, 업로드 단계는 동일한 PIPELINE에서 발생합니다.
• CI에서 소스맵을 업로드합니다..
• 개발자 노트북에서 아니라.앱은 CI가 업로드할 때 사용한 동일한 릴리스 문자열로 Sentry를 초기화합니다.
• 앱은 동일한 릴리스 문자열로 세인티를 초기화합니다. 이것은 Sentry에서 소스맵이 필요하다는 것보다 더 중요합니다.

이것은 Sentry에서 소스맵이 필요하다는 것보다 더 중요합니다. 이것은 Sentry에서 소스맵이 필요하다는 것보다 더 중요합니다..

이 팀이 이미 모바일 자동화 표준화를 진행 중이라면, 이 안내서를 자동 빌드 및 릴리즈 워크플로에 대한 GitHub Actions를 사용하는 방법 이 모델은 CI/CD 파이프라인의 운영 모델과 잘 맞습니다.

실용적인 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"

Android용으로 배포 명령어를 적절히 조정해야 하며, 많은 팀이 플랫폼별 작업을 분리하는 대신 하나의 스크립트를 사용하려고 하지 않습니다. 그건 괜찮습니다. 중요한 것은 일관성입니다.

Release discipline beats clever scripting. 하나의 이름 규칙을 선택하고 빌드 시간에 앱에 주입하고, CI와 지역 ad hoc 업로드가 경쟁하지 않도록 하십시오.

React Native의 경우, 빌드 생성된 구성 위치에 릴리즈 문자열을 저장하고, 빌드 시간에 주입하는 것이 좋습니다. Sentry.init():

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

결과는 간단합니다. 이벤트가 도착하면 Sentry는 shipped한 code을 code으로 매핑할 수 있습니다.

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

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

이러한 보고서는 일반적으로 다음과 같은 형태를 띠며, “대시보드는 느립니다.”라는 보고가 나옵니다. 하지만 이는 디버깅하기에 충분하지 않습니다. 느리다는 곳이 어디인가요? 네비게이션 중인가요? 데이터를 불러오는 중인가요? 혹은 무거운 차트를 렌더링하는 중인가요? Sentry는 여기서 유용하게 작동합니다. Sentry를 오류 인박스처럼 다루지 않고, 앱의 동작을 측정하는 것을 시작할 때입니다.

느린 화면을 추적하는 것보다 추측하는 것

첫 단계는 초기화 시에 성능 추적을 활성화하는 것입니다. 정확한 샘플링 전략은 환경과 볼륨_tolerance에 따라 달라질 수 있지만, 구조는 다음과 같습니다.

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

React Navigation을 사용하는 경우, 화면 전환을 통해 추적 데이터를 생성하도록 통합을 구성하세요. 그리고 물리적 장치에서만 reproducibility를 테스트하세요. 시뮬레이터는 사용자가 느끼는 느려짐을 숨기기 때문입니다.

실제 대시보드 예시:

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

이것은 직감에 의한 논쟁보다 낫습니다.

웹뷰 또는 하이브리드 앱 모니터링 패턴에 대해 넓게 생각하는 팀에게 이 글은 가치가 있습니다. Capacitor 프로젝트의 성능 모니터링에 대한 이 글은 읽어보세요. 운영 방식은 다르지만 스택이 다르더라도 이 글은 가치가 있습니다.

오류에 유용한 맥락을 추가하세요.

이벤트에 비즈니스 맥락이 포함된 경우 성능 데이터가 더 유용합니다.

vanity metadata가 아닌, 오류가 발생하기 직전의 화면과 관련된 정보가 포함된 경우.

• 이러한 도구를 의도적으로 사용하세요: 사용자 맥락 Sentry.setUser() 사용자 지원 팀이 보고서를 관련된 계정과 연결할 수 있도록 지원하세요.
• 브레드 크럼bs 서브밋 버튼을 클릭하거나 모달을 열거나 SYNC를 시작하는 등의 액션을 기록하세요.
• 사용자 지정 태그 다음 차원들에 대해 예를 들어, 플랜 타입, 기능 플래그 상태, 또는 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' },
  });
}

브레드 크럼블 트레일은

앱이 멈췄다고 말하는 사용자

앱이 데스크톱을 열고 싱크를 시작하고 스테일한 요청을 다시 시도한 후 실패한 앱

Sentry를 배포하기 전에, 빌드 파이프라인 변경 후, 그리고 SDK 업그레이드 후에 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'));
  }}
/>

자연스러운 Native 앱 다운 테스트는 개발 또는 제어된 QA 빌드에서만 수행해야 합니다. 정확한 도우미 메소드가 SDK 버전과 플랫폼 연결에 따라 달라질 수 있으므로, SDK의 문서화된 Native 앱 다운 테스트 유틸리티가 존재할 때 사용하는 것이 좋습니다.

Sentry UI에서 확인할 항목

이벤트가 나타날 때, 제목만 확인하지 말고 더 자세히 살펴보세요.

다음 항목을 확인하세요:

• 플랫폼 및 메커니즘. JS 예외와 Native 다운을 구분하는 데 도움이 됩니다.
• 릴리즈 및 디스트. 비어 있거나 잘못된 경우 소스맵과 심볼화가 비정상적으로 작동합니다.
• 스택 프레임. 올바르게 업로드된 자바스크립트 맵에 대한 읽을 수 있는 소스 위치가 나타나야 합니다.
• 크럼블 및 태그. 사용자 정의 컨텍스트가 도착했습니다.
• 환경. 개발 및 운영 이벤트가 혼합되지 않도록 확인하세요.

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

Sentry React Native 일반적인 문제 해결

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

Live Update 워크플로와 같은 Capgo와 통합합니다.

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

해결책은 라이브 번들을 따라하는 Sentry 릴리스 식별자를 만드는 것입니다.바이너리만을 고려하는 것이 아니라.

라이브 번들과 일치하는 릴리스 식별자를 만드는 것입니다.

live update 워크플로에 대해 release 그리고 dist 배포된 자바스크립트 패키지와 관련된 런타임 식별자입니다. 네이티브 앱 버전은 여전히 중요하지만, 배포할 수 있는 패키지의 독립적인 변경이 가능해지면 충분하지 않습니다.

실용적인 패턴은 다음과 같습니다:

• 네이티브 앱 버전을 기본 릴리스 이름의 일부로 사용합니다.
• live update 버전 또는 패키지 식별자를 추가합니다.
• Use dist 각 라이브 배포 아래에 정확한 릴리스 식별자와 함께 소스 맵을 업로드합니다.
• 라이브 번들에 대한 정확한 릴리스 식별자 아래에 각 라이브 번들을 위한 소스 맵을 업로드 하십시오.

이러한 OTA 스타일 워크플로우와 관련하여 중요합니다. 핫픽스에 대한 소스 맵을 사용하여 프레임을 해결할 수 있도록 하려면, 핫픽스 대신에 스토어 배포에 대한 프레임을 해결하는 대신, 핫픽스에 대한 프레임을 해결합니다.

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

이것은 __CAPGO_KEEP_0__ 앱에서 라이브 업데이트가 어떻게 작동하는지에 대한 설명

이것은 __CAPGO_KEEP_0__ 앱에서 라이브 업데이트가 어떻게 작동하는지에 대한 설명 이것은 Capacitor 앱에서 라이브 업데이트가 어떻게 작동하는지에 대한 설명 Capgo는 완전한 참고 자료입니다.

다음과 같은 운영 환경을 구축하는 것이 팀이 업데이트된 메타데이터와 릴리스 추적을 결합할 때 목표입니다:

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

앱 스토어 리뷰 사이클 외에 팀이 수정 사항을 배포한다면 Capgo Capgo는 Capacitor 팀에게 실시간 업데이트를 제공하는 구조화된 방법을 제공합니다. Capacitor 팀은 채널을 대상으로 업데이트를 제어하고 나쁜 릴리스에서 빠르게 회복할 수 있습니다. 정제된 Sentry 릴리스 이름과 소스 맵 업로드를 pair하면, 오류는 여전히 정확한 code 사용자들이 실행 중인 code에 대한 지시를 제공합니다.