Flutter에 에러 기록을 위한 Sentry 적용하기

 

0. Sentry란??

• Sentry는 앱이나 웹서비스에서 오류와 성능 문제를 자동으로 추적해주는 모니터링 플랫폼입니다!
• 앱을 배포하고 나면 사용자의 핸드폰에서 발생하는 오류들을 개발자가 직접 추적하는 것이 불가능합니다. 하지만 Sentry를 사용하면 사용자의 환경에서 발생한 다양한 예외, 앱 멈춤, 느려짐과 같은 현상들을 실시간으로 수집하고 원인, 발생 위치 등을 개발자가 빠르게 파악할 수 있게 도와줍니다! 👍
• Sentry는 Flutter, Andriod, iOS, 웹 등 다양한 플랫폼을 지원합니다.

1. Sentry 가입 및 기초 설정

• 먼저 https://sentry.io/welcome/ 페이지로 이동 후 오른쪽 위의 Get Started를 클릭한 다음 계정을 생성합니다. 

 

• 다음으로 모니터링 할 플랫폼 선택합니다 → 저의 경우는 Flutter 선택했습니다 

 

 

• 다음으로 나오는 Configure Flutter SDK에서 Manual을 선택하면 Flutter 프로젝트에 Sentry를 적용하는 방법이 하나하나 나옵니다! 이 내용을 하나씩 적용해보겠습니다!

🚨 이 Configure Flutter SDK 내용 중 Configure SDK 파트의 코드에 나오는 options.dns는 꼭 기억하셔야합니다! 이후 Flutter 설정에서 사용됩니다!

 

2. Flutter에 Sentry 설정

• pubspecs.yaml에 아래와 같이 설정 후 저장합니다. 혹은 설정 이후 직접 터미널에 flutter pub get을 실행합니다. 

dependencies:
  sentry_flutter: ^9.4.0

 

 

• 그리고 main.dart에 아래와 같이 코드를 작성합니다. 

import 'package:flutter/material.dart';
import 'package:sentry_flutter/sentry_flutter.dart';

Future<void> main() async {
  // Sentry 초기화: 앱의 모든 에러 및 퍼포먼스(성능) 트레이싱을 모니터링합니다.
  await SentryFlutter.init(
    (options) {
      // Sentry DSN 주소를 입력해야 실제 Sentry 대시보드에 데이터가 전송됩니다.
      options.dsn = '여기에 본인의 dns 작성하기';

      // 개인정보(IP, 헤더 등)도 함께 전송 (GDPR 등 고려해 환경에 따라 true/false 조정)
      options.sendDefaultPii = true;

      // 성능 트레이싱 샘플링 비율: 1.0은 100% 모든 트랜잭션 기록 (운영에서는 0.1~0.3 추천)
      options.tracesSampleRate = 1.0;

      // 프로파일링 샘플 비율: tracesSampleRate와 곱해져서 적용됨. (1.0 = 모두 기록)
      options.profilesSampleRate = 1.0;

      // 환경 구분(운영, 개발 등) - 선택 사항
      // options.environment = 'production';

      // Sentry 콘솔에 디버그 로그 출력 (개발 단계에서만 true 추천)
      // options.debug = true;

      // 앱의 빌드/릴리즈 정보 등록 (대시보드에서 버전별로 에러 추적)
      // options.release = 'myapp@1.0.0+1';
    },
    // SentryWidget으로 앱 전체를 감싸 에러/트레이싱 자동 전송
    appRunner: () => runApp(
      SentryWidget(
        child: MyApp(),
      ),
    ),
  );

  // 또는 DSN 등 환경변수를 --dart-define으로 주입할 수도 있습니다.
}

• 여기서 tracesSampleRate과 profileSampleRate에 대해 조금 더 알아보겠습니다
  1. traceSampleRate
     • 퍼포먼스 트레이싱 샘플링 비율
       • “트랜잭션” = 한 번의 사용자 액션(예: 화면 진입, 버튼 클릭, API 호출 등)의 전체 실행 흐름과 시간 측정
       • traceSampleRate의 값이 1.0이면 앱에서 일어나는 모든 트랜잭션(=성능 기록)을 100% Sentry에 전송
       • 0.1이면 10%만 랜덤 샘플링해서 전송(트래픽/비용 아끼기 위해 운영에서 흔히 사용)
     • 화면 전환, 네트워크 요청 등 "어디가 느린가"를 알 수 있게 해줌
  2. 퍼포먼스 프로파일링 샘플링 비율
     • 퍼포먼스 프로파일링 샘플링 비율
       • “프로파일링” = CPU, 메모리 등 시스템 리소스를 상세하게 추적 (실제 어느 함수/코드라인이 CPU를 가장 많이 썼는지, 어떤 위젯이 느린지 등)
       • profileSampleRate는 "트랜잭션 중에서도 몇 %에서만 프로파일링 정보까지 수집할 것인가"를 결정
       • 이 값이 1.0이면, 위의 traceSampleRate를 통해 트랜잭션으로 측정된 모든 요청에 대해 프로파일링도 100% 실행 (즉, tracesSampleRate가 0.5, profileSampleRate가 1.0이면 전체의 50%에서만 프로파일링도 활성화))

3. 결과 확인하기

• 이제 여기까지 내용을 진행했으면 앱을 완전히 정지했다가 재시작합니다. (Hot reload/hot restart 말고, 완전히 재시작)

• 그리고 이제 테스트를 위해 화면 어디엔가 아래와 같이 일부러 에러를 발생시키는 버튼을 추가합니다.
  • 이때 2개의 버튼을 만드는데 2 버튼은 각각 아래의 기능을 수행합니다.
    • 위의 버튼은 단순히 StateError를 일으키는 버튼입니다.
    • 아래 버튼은 Sentry.captureException을 통해 에러의 내용을 직접적으로 Sentry에 전달하는 버튼입니다.

      ElevatedButton(
        onPressed: () {
          throw StateError('This is test exception automatically');
        },
        child: const Text('Sentry 자동 전송'),
      ),
      ElevatedButton(
        onPressed: () async {
          try {
            throw StateError(
                'This is test exception with captureException');
          } catch (e, stackTrace) {
            await Sentry.captureException(e, stackTrace: stackTrace);
          }
        },
        child: const Text('Sentry 직접 전송'),
      )

 

• 현재 제가 만든 앱에서는 아래 이미지처럼 앱 하단에 버튼을 추가했습니다.
  (버튼은 테스트용이라 일단 안 예뻐도 그냥 적용했습니다..ㅎㅎ..) 

 

• 일단 저의 경우에는 debug 모드로 simulator에서 앱을 구동하고 있었는데요! 먼저 위쪽 버튼을 누르면 아래와 같이 예외 발생했습니다. 

 

• 하지만 Sentry에 해당 에러가 전달이 되지 않습니다!! → 이유는? 디버그 모드에서는 Sentry 전송이 제한된다고 합니다.
  • 이에 따라 앱을 빌드할 때 flutter run --release를 통해 릴리즈 모드로 앱을 빌드하면! 아래와 같이 에러가 잘 기록되는 것을 확인할 수 있습니다. (단, release 모드에서는 릴리즈 상태이므로 위와 같이 예외가 발생하며 앱이 멈추진 않습니다)

 

• 다음으로 아래쪽 버튼을 눌러보았습니다.
  • 이 경우는 Sentry.captureException를 사용해서 에러를 직접 Sentry로 전송하는 경우였고 이 경우 debug 모드여도 아래와 같이 에러가 Sentry로 전달되는 것을 확인할 수 있습니다. 

 

 

• 또한 Sentry를 사용하다보니 위와 같은 에러도 감지하는 것을 확인했습니다.
  • 이는 특정 시점에서 앱이 2초 이상 멈춘 것을 Sentry가 자동으로 감지해서 보고한 것입니다!

4. 마무리

여기까지의 내용으로 Sentry를 사용해서 Flutter로 만든 앱에서 발생하는 에러들을 로깅하는 내용을 직접 진행해보았습니다! 🧑‍💻

앞으로 Flutter에서 Sentry를 사용하다가 또 공유할만한 유용한 것을 알아내면 글 작성해보겠습니다! 👋