Firebase Crashlytics 비정상 종료 보고서 맞춤설정

이 가이드에서는 Crashlytics API를 사용하여 비정상 종료 보고서를 맞춤설정하는 방법을 설명합니다. 기본적으로 Crashlytics는 모든 앱 사용자의 플랫폼 기반 비정상 종료 보고서를 자동으로 수집하지만, 사용자를 대신하여 자동 비정상 종료 보고를 해제하고 보고 선택 옵션을 사용 설정할 수 있습니다. Crashlytics는 커스텀 키, 커스텀 로그, 사용자 식별자, 포착된 예외, 포착되지 않은 예외라는 5가지 로깅 메커니즘을 제공합니다.

Flutter 앱의 경우 심각한 보고서는 사용자가 애플리케이션을 다시 시작할 필요 없이 실시간으로 Crashlytics에 전송됩니다. 심각하지 않은 보고서는 다음 심각한 보고서와 함께 또는 앱이 다시 시작될 때 전송되도록 디스크에 기록됩니다.

포착되지 않은 예외 보고

FlutterError.onError를 FirebaseCrashlytics.instance.recordFlutterFatalError로 재정의하여 Flutter 프레임워크 내에서 발생하는 모든 '심각한' 오류를 자동으로 포착할 수 있습니다. 또는 '심각하지 않은' 예외를 포착하려면 FlutterError.onError를 FirebaseCrashlytics.instance.recordFlutterError로 재정의합니다.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

비동기 오류

비동기 오류는 Flutter 프레임워크에서 포착되지 않습니다.

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

이러한 오류를 포착하려면 PlatformDispatcher.instance.onError 핸들러를 사용하면 됩니다.

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

Flutter 외부의 오류

Flutter 컨텍스트 외부에서 발생하는 오류를 포착하려면 현재 Isolate에 오류 리스너를 설치합니다.

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

포착된 예외 보고

Crashlytics를 사용하면 앱의 비정상 종료를 자동으로 보고하는 것 외에도 심각하지 않은 예외를 기록하고 다음번 심각한 이벤트가 보고되거나 앱이 다시 시작될 때 예외를 전송할 수 있습니다.

recordError 메서드를 사용하여 심각하지 않은 예외를 앱의 catch 블록에 기록합니다. 예를 들면 다음과 같습니다.

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

발생할 수 있는 오류에 대해 information 속성을 사용하여 추가 정보를 로깅할 수도 있습니다.

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

이러한 예외는 Firebase Console에서 심각하지 않은 문제로 표시됩니다. 문제 요약에는 비정상 종료에서 일반적으로 확인 가능한 모든 상태 정보가 버전 및 하드웨어 기기별 분류와 함께 포함됩니다.

Crashlytics는 앱에 미치는 성능 영향을 최소화하기 위해 전용 백그라운드 스레드에서 예외를 처리합니다. 사용자의 네트워크 트래픽을 줄이기 위해 Crashlytics는 필요한 경우 기기에서 전송되는 보고서 수를 비율 제한합니다.

커스텀 키 추가

커스텀 키를 사용하면 비정상 종료로 이어지는 앱의 구체적인 상태를 확인할 수 있습니다. 임의의 키-값 쌍을 비정상 종료 보고서에 연결하고 커스텀 키를 사용하여 Firebase Console에서 비정상 종료 보고서를 검색하고 필터링할 수 있습니다.

  • Crashlytics 대시보드에서 커스텀 키와 일치하는 문제를 검색할 수 있습니다.

  • 콘솔에서 특정 문제를 검토할 때 각 이벤트와 연결된 커스텀 키를 검토하고(키 하위 탭) 이벤트를 커스텀 키로 필터링할 수도 있습니다(페이지 상단의 필터 메뉴).

setCustomKey 인스턴스 메서드를 사용하여 키-값 쌍을 설정합니다. 다음은 몇 가지 예입니다.

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

커스텀 로그 메시지 추가

비정상 종료로 이어지는 이벤트에 대한 배경 정보를 자세히 파악하기 위해 앱에 커스텀 Crashlytics 로그를 추가할 수 있습니다. Crashlytics가 로그를 비정상 종료 데이터에 연결하고 Firebase Console의 Crashlytics 로그 탭 아래에 표시합니다.

log를 사용하여 문제를 정확하게 파악할 수 있습니다. 예를 들면 다음과 같습니다.

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

사용자 식별자 설정

어떤 사용자에게 특정 비정상 종료가 발생했는지 파악하면 문제를 진단하는 데 도움이 될 수 있습니다. Crashlytics는 비정상 종료 보고서에서 사용자를 익명으로 식별할 수 있는 방법을 제공합니다.

보고서에 사용자 ID를 추가하려면 각 사용자에게 ID 번호, 토큰 또는 해시 값 형식으로 고유 식별자를 할당합니다.

FirebaseCrashlytics.instance.setUserIdentifier("12345");

사용자 식별자를 설정한 후 삭제해야 하는 경우 값을 빈 문자열로 재설정합니다. 사용자 식별자를 지워도 기존 Crashlytics 레코드는 삭제되지 않습니다. 사용자 ID와 연결된 레코드를 삭제하려면 Firebase 지원팀에 문의하세요.

보고 선택 옵션 사용 설정

기본적으로 Crashlytics는 모든 앱 사용자의 비정상 종료 보고서를 자동으로 수집하지만 사용자가 자신이 전송하는 데이터를 더 잘 관리할 수 있도록 다음과 같이 코드에서 자동 보고를 사용 중지하고, 선택하는 경우에만 Crashlytics에 데이터를 전송하여, 보고 선택 옵션을 사용 설정할 수 있습니다.

  1. 기본적으로 자동 수집을 사용 중지하는 방법은 다음과 같습니다.

    Apple 플랫폼

    Info.plist 파일에 새 키를 추가합니다.

    • 키: FirebaseCrashlyticsCollectionEnabled
    • 값: false

    Android

    AndroidManifest.xml 파일의 application 블록에 meta-data 태그를 추가하여 자동 수집을 사용 중지합니다.

    <meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />

  2. 런타임에 Crashlytics 데이터 수집 재정의를 호출하여 특정 사용자에만 수집을 사용 설정합니다.

    재정의 값은 앱이 실행되는 동안 유지되므로 Crashlytics는 보고서를 자동으로 수집할 수 있습니다. 자동 비정상 종료 보고를 선택 해제하려면 false를 재정의 값으로 전달합니다. false로 설정하면 앱이 다음 번 실행될 때까지 새 값이 적용되지 않습니다.

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);

비정상 종료 통계 데이터 관리

비정상 종료 통계는 익명화된 스택 트레이스를 다른 Firebase 앱의 트레이스와 비교하여 문제가 더 큰 트렌드에 속하는지 여부를 파악함으로써 문제를 해결하는 데 도움을 줍니다. 비정상 종료 통계가 디버깅에 도움이 되는 경우도 많습니다.

비정상 종료 통계에서는 비정상 종료 집계 데이터를 사용하여 공통적인 안정성 트렌드를 파악합니다. 앱의 데이터를 공유하지 않으려는 경우 Firebase Console에 있는 Crashlytics 문제 목록 상단의 비정상 종료 통계 메뉴에서 비정상 종료 통계를 선택 해제할 수 있습니다.