Menyesuaikan laporan error Firebase Crashlytics

iOS+ Android Flutter Unity

Di dasbor Crashlytics, Anda dapat mengklik masalah dan mendapatkan laporan peristiwa yang mendetail. Anda dapat menyesuaikan laporan tersebut untuk membantu lebih memahami situasi yang terjadi di aplikasi dan situasi seputar peristiwa yang dilaporkan ke Crashlytics.

• Melengkapi aplikasi Anda untuk mencatat kunci kustom, pesan log kustom, dan ID pengguna.

• Melaporkan pengecualian ke Crashlytics.

• Mendapatkan log breadcrumb secara otomatis jika aplikasi Anda menggunakan Firebase SDK untuk Google Analytics. Log ini memberi Anda visibilitas terkait tindakan pengguna yang mengarah ke peristiwa yang dikumpulkan Crashlytics di aplikasi Anda.

• Menonaktifkan pelaporan error otomatis dan mengaktifkan pelaporan keikutsertaan untuk pengguna. Perlu diperhatikan bahwa, secara default, Crashlytics otomatis mengumpulkan laporan error untuk semua pengguna aplikasi Anda.

Menambahkan kunci kustom

Kunci kustom membantu Anda mendapatkan status tertentu aplikasi menjelang error. Anda dapat mengaitkan key-value pair apa pun dengan laporan error, lalu menggunakan kunci kustom untuk menelusuri dan memfilter laporan error di Firebase console.

• Di dasbor Crashlytics, Anda dapat mencari masalah yang cocok dengan kunci kustom.
• Saat meninjau masalah tertentu di console, Anda dapat melihat kunci kustom yang dikaitkan untuk setiap peristiwa (subtab Keys) dan bahkan memfilter peristiwa berdasarkan kunci kustom (menu Filter di bagian atas halaman).

Catatan: Crashlytics mendukung maksimum 64 key-value pair. Setelah Anda mencapai batas ini, nilai tambahan tidak akan disimpan. Setiap key-value pair dapat berukuran maksimal 1 kB.

Gunakan metode setCustomValue untuk menetapkan key-value pair. Contoh:

Swift

// Set int_key to 100.
Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set str_key to "hello".
Crashlytics.crashlytics().setCustomValue("hello", forKey: "str_key")

Objective-C

Saat menetapkan bilangan bulat, boolean, atau float, kotakkan nilai sebagai @(value).

// Set int_key to 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set str_key to "hello".
[[FIRCrashlytics crashlytics] setCustomValue:@"hello" forKey:@"str_key"];

Anda juga dapat mengubah nilai kunci yang ada dengan memanggil kunci tersebut dan menetapkannya ke nilai yang berbeda. Contoh:

Swift

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set int_key to 50 from 100.
Crashlytics.crashlytics().setCustomValue(50, forKey: "int_key")

Objective-C

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set int_key to 50 from 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(50) forKey:@"int_key"];

Tambahkan key-value pair sekaligus menggunakan metode setCustomKeysAndValues dengan NSDictionary sebagai satu-satunya parameter:

Swift

let keysAndValues = [
                 "string key" : "string value",
                 "string key 2" : "string value 2",
                 "boolean key" : true,
                 "boolean key 2" : false,
                 "float key" : 1.01,
                 "float key 2" : 2.02
                ] as [String : Any]

Crashlytics.crashlytics().setCustomKeysAndValues(keysAndValues)

Objective-C

NSDictionary *keysAndValues =
    @{@"string key" : @"string value",
      @"string key 2" : @"string value 2",
      @"boolean key" : @(YES),
      @"boolean key 2" : @(NO),
      @"float key" : @(1.01),
      @"float key 2" : @(2.02)};

[[FIRCrashlytics crashlytics] setCustomKeysAndValues: keysAndValues];

Menambahkan pesan log kustom

Untuk memberikan lebih banyak konteks mengenai peristiwa menjelang error, Anda dapat menambahkan log Crashlytics kustom ke aplikasi. Crashlytics mengaitkan log dengan data error dan menampilkannya di halaman Crashlytics di Firebase console, pada tab Logs.

Catatan: Untuk menghindari perlambatan aplikasi, Crashlytics membatasi log hingga 64 kB. Crashlytics menghapus entri log lama jika log sesi melewati batas tersebut.

Swift

Gunakan log() atau log(format:, arguments:) untuk membantu menentukan masalah. Jika Anda ingin mendapatkan output log yang berguna dengan pesan, objek yang Anda teruskan ke log() harus sesuai dengan properti CustomStringConvertible. log() menampilkan properti deskripsi yang Anda tentukan untuk objek. Contoh:

Crashlytics.crashlytics().log("Higgs-Boson detected! Bailing out…, \(attributesDict)")

.log(format:, arguments:) memformat nilai yang ditampilkan setelah memanggil getVaList(). Contoh:

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList(["Higgs-Boson detected! Bailing out…", attributesDict]))

Untuk mengetahui detail selengkapnya mengenai cara menggunakan log() atau log(format:, arguments:), lihat dokumentasi referensi Crashlytics.

Objective-C

Gunakan log atau logWithFormat untuk membantu menentukan masalah. Perhatikan bahwa jika Anda ingin mendapatkan output log yang berguna dengan pesan, objek yang Anda teruskan ke salah satu metode tersebut harus mengganti properti instance description. Contoh:

[[FIRCrashlytics crashlytics] log:@"Simple string message"];

[[FIRCrashlytics crashlytics] logWithFormat:@"Higgs-Boson detected! Bailing out... %@", attributesDict];

[[FIRCrashlytics crashlytics] logWithFormat:@"Logging a variable argument list %@" arguments:va_list_arg];

Untuk mengetahui detail selengkapnya mengenai cara menggunakan log dan logWithFormat, lihat dokumentasi referensi Crashlytics.

Menetapkan ID pengguna

Untuk mendiagnosis masalah, mengetahui pengguna mana yang mengalami error akan sangat membantu. Crashlytics menyertakan cara mengidentifikasi pengguna secara anonim dalam laporan error Anda.

Untuk menambahkan ID pengguna ke laporan, tetapkan ID unik untuk setiap pengguna dalam bentuk nomor ID, token, atau nilai hash:

Swift

Crashlytics.crashlytics().setUserID("123456789")

Objective-C

[[FIRCrashlytics crashlytics] setUserID:@"123456789"];

Jika perlu menghapus ID pengguna setelah menetapkannya, reset nilainya ke string kosong. Menghapus ID pengguna tidak menghapus catatan Crashlytics yang ada. Jika ingin menghapus catatan yang terkait dengan ID pengguna, hubungi dukungan Firebase.

Melaporkan pengecualian non-fatal

Selain melaporkan error aplikasi secara otomatis, Crashlytics dapat Anda gunakan untuk mencatat pengecualian non-fatal dan mengirimkannya kepada Anda saat aplikasi diluncurkan pada kesempatan berikutnya.

Catatan: Crashlytics hanya menyimpan delapan pengecualian terbaru dalam satu sesi aplikasi. Jika aplikasi Anda melempar lebih dari delapan pengecualian dalam satu sesi, pengecualian yang lebih lama akan hilang.

Anda dapat mencatat pengecualian non-fatal dengan mencatat objek NSError menggunakan metode recordError. recordError merekam stack panggilan thread dengan memanggil [NSThread callStackReturnAddresses].

Swift

Crashlytics.crashlytics().record(error: error)

Objective-C

[[FIRCrashlytics crashlytics] recordError:error];

Saat menggunakan metode recordError, pahami struktur NSError dan cara Crashlytics menggunakan data untuk mengelompokkan error. Penggunaan metode recordError yang salah dapat menyebabkan perilaku yang tidak dapat diprediksi dan mungkin akan menyebabkan Crashlytics perlu membatasi pelaporan error yang dicatat ke dalam log untuk aplikasi Anda.

Objek NSError memiliki tiga argumen:

• domain: String
• code: Int
• userInfo: [AnyHashable : Any]? = nil

Tidak seperti error fatal yang dikelompokkan melalui analisis pelacakan tumpukan, error yang dicatat ke dalam log dikelompokkan menurut domain dan code. Hal ini menunjukkan perbedaan penting antara error fatal dan error yang dicatat ke dalam log. Contoh:

Swift

let userInfo = [
  NSLocalizedDescriptionKey: NSLocalizedString("The request failed.", comment: ""),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString("The response returned a 404.", comment: ""),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString("Does this page exist?", comment: ""),
  "ProductID": "123456",
  "View": "MainView"
]

let error = NSError.init(domain: NSCocoaErrorDomain,
                         code: -1001,
                         userInfo: userInfo)

Objective-C

NSDictionary *userInfo = @{
  NSLocalizedDescriptionKey: NSLocalizedString(@"The request failed.", nil),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"The response returned a 404.", nil),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString(@"Does this page exist?", nil),
  @"ProductID": @"123456",
  @"View": @"MainView",
};

NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain
                                     code:-1001
                                 userInfo:userInfo];

Saat Anda mencatat error di atas ke dalam log, masalah baru akan dibuat dan dikelompokkan berdasarkan NSSomeErrorDomain dan -1001. Error lainnya yang dicatat ke dalam log, yang menggunakan nilai domain dan kode yang sama, akan dikelompokkan ke dalam masalah yang sama. Data yang terdapat dalam objek userInfo dikonversi menjadi key-value pair dan ditampilkan di bagian kunci/log dalam satu masalah.

Peringatan: Hindari penggunaan nilai unik, seperti ID pengguna, ID produk, dan stempel waktu di kolom domain dan kode. Penggunaan nilai unik di kolom ini menyebabkan kardinalitas masalah yang tinggi, sehingga Crashlytics perlu membatasi pelaporan error yang dicatat ke dalam log untuk aplikasi Anda. Nilai unik seharusnya ditambahkan ke objek dictionary userInfo.

Log dan kunci kustom

Sama seperti laporan error, Anda dapat menyematkan log dan kunci kustom untuk menambahkan konteks ke NSError. Namun, ada perbedaan antara log yang disematkan pada error dan error yang dicatat ke dalam log. Saat terjadi error lalu aplikasi diluncurkan kembali, log yang diambil Crashlytics dari disk adalah log yang ditulis hingga saat error terjadi. Saat Anda mencatat NSError ke dalam log, aplikasi tidak segera dihentikan. Karena Crashlytics hanya mengirimkan laporan error yang dicatat ke dalam log pada peluncuran aplikasi berikutnya, dan karena Crashlytics harus membatasi jumlah ruang yang dialokasikan untuk log pada disk, akan ada cukup logging yang dilakukan setelah NSError dicatat sehingga semua log yang relevan sudah dirotasi pada saat Crashlytics mengirimkan laporan dari perangkat. Jaga keseimbangan ini saat mencatat NSErrors ke dalam log dan saat menggunakan log dan kunci kustom di aplikasi Anda.

Pertimbangan performa

Perlu diingat bahwa logging NSError bisa jadi cukup mahal. Pada saat Anda melakukan panggilan, Crashlytics menangkap stack panggilan thread saat ini dengan menggunakan proses yang disebut pelepasan stack (stack unwinding). Proses ini mungkin memerlukan performa CPU dan I/O yang tinggi, terutama pada arsitektur yang mendukung pelepasan DWARF (arm64 dan x86). Setelah proses pelepasan selesai, informasinya ditulis ke disk secara sinkron. Ini untuk mencegah hilangnya data jika baris berikutnya mengalami error.

Meskipun aman untuk memanggil API ini di thread latar belakang, ingat bahwa mengirimkan panggilan ini ke antrean lainnya akan menghilangkan konteks pelacakan tumpukan saat ini.

Bagaimana dengan NSException?

Crashlytics tidak menawarkan fasilitas untuk logging dan pencatatan instance NSException secara langsung. Secara umum, Cocoa dan Cocoa Touch API tidak benar-benar aman dari pengecualian. Itu berarti penggunaan @catch memiliki efek samping sangat serius yang tidak diinginkan dalam proses Anda, bahkan jika digunakan dengan sangat hati-hati. Jangan pernah menggunakan pernyataan @catch dalam kode Anda. Lihat dokumentasi Apple untuk topik ini.

Menyesuaikan stack trace

Jika aplikasi Anda berjalan di lingkungan non-native (seperti C++ atau Unity), Anda dapat menggunakan Exception Model API untuk melaporkan metadata error dalam format pengecualian native aplikasi. Pengecualian yang dilaporkan akan ditandai sebagai non-fatal.

Swift

var  ex = ExceptionModel(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(symbol:"makeError", file:"handler.js", line:495),
  StackFrame(symbol:"then", file:"routes.js", line:102),
  StackFrame(symbol:"main", file:"app.js", line:12),
]

crashlytics.record(exceptionModel:ex)

Objective-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" file:@"handler.js" line:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" file:@"routes.js" line:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" file:@"app.js" line:12],
];

[[FIRCrashlytics crashlytics] recordExceptionModel:model];

Frame stack kustom juga dapat diinisialisasi dengan alamat saja:

Swift

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(address:0xfa12123),
  StackFrame(address:12412412),
  StackFrame(address:194129124),
]

crashlytics.record(exceptionModel:ex)

Objective-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithAddress:0xfa12123],
  [FIRStackFrame stackFrameWithAddress:12412412],
  [FIRStackFrame stackFrameWithAddress:194129124],
];


[[FIRCrashlytics crashlytics] recordExceptionModel:model];

Mendapatkan log breadcrumb

Log breadcrumb memberi Anda pemahaman yang lebih baik tentang interaksi yang dilakukan pengguna dengan aplikasi Anda yang mengarah ke peristiwa error, non-fatal, atau ANR. Log ini dapat bermanfaat saat mencoba mereproduksi dan men-debug masalah.

Log breadcrumb didukung oleh Google Analytics. Jadi, untuk mendapatkan log breadcrumb, Anda harus mengaktifkan Google Analytics untuk project Firebase dan menambahkan Firebase SDK untuk Google Analytics ke aplikasi Anda. Setelah persyaratan ini terpenuhi, log breadcrumb akan otomatis disertakan dengan data peristiwa dalam tab Logs saat Anda melihat detail masalah.

Analytics SDK otomatis mencatat peristiwa screen_view ke dalam log, sehingga log breadcrumb dapat menampilkan daftar layar yang dilihat sebelum peristiwa error, non-fatal, atau ANR. Log breadcrumb screen_view berisi parameter firebase_screen_class.

Log breadcrumb juga diisi dengan setiap peristiwa kustom yang Anda catat secara manual dalam sesi pengguna, termasuk data parameter peristiwa. Data ini dapat membantu menunjukkan serangkaian tindakan pengguna yang mengarah ke peristiwa error, non-fatal, atau ANR.

Perhatikan bahwa Anda dapat mengontrol pengumpulan dan penggunaan data Google Analytics, yang mencakup data yang mengisi log breadcrumb.

Mengaktifkan pelaporan keikutsertaan

Secara default, Crashlytics otomatis mengumpulkan laporan error untuk semua pengguna aplikasi Anda. Untuk memberi pengguna kontrol lebih terhadap data yang mereka kirim, Anda dapat mengaktifkan pelaporan keikutsertaan dengan menonaktifkan pelaporan otomatis dan hanya mengirim data ke Crashlytics saat Anda ingin melakukannya dalam kode:

1. Nonaktifkan pengumpulan otomatis dengan menambahkan kunci baru ke file Info.plist Anda:

   • Kunci: FirebaseCrashlyticsCollectionEnabled
   • Nilai: false

2. Aktifkan pengumpulan untuk pengguna tertentu dengan memanggil penggantian pengumpulan data Crashlytics saat runtime. Nilai penggantian tetap ada setiap kali aplikasi diluncurkan, sehingga Crashlytics dapat otomatis mengumpulkan laporan.

   Untuk tidak diikutsertakan dalam pelaporan error otomatis, teruskan false sebagai nilai penggantian. Jika ditetapkan ke false, nilai baru tidak berlaku hingga aplikasi dijalankan berikutnya.

   Swift

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Objective-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

Catatan: Jika pengumpulan data dinonaktifkan, Crashlytics akan menyimpan informasi error secara lokal di perangkat. Jika selanjutnya pengumpulan data diaktifkan, informasi error yang disimpan di perangkat akan dikirim ke Crashlytics untuk diproses.

Mengelola data Crash Insights

Crash Insights membantu Anda mengatasi masalah dengan membandingkan pelacakan tumpukan anonim dengan trace dari aplikasi Firebase lain, serta memberitahukan apakah masalah Anda adalah bagian dari tren yang lebih besar. Untuk sebagian besar masalah, Crash Insights bahkan menyediakan resource untuk membantu Anda mendebug error.

Crash Insights menggunakan data error gabungan untuk mengidentifikasi tren stabilitas umum. Jika tidak ingin membagikan data aplikasi, Anda dapat menonaktifkan Crash Insights dari menu Crash Insights di bagian atas daftar masalah Crashlytics pada Firebase console.

Catatan: Menonaktifkan berbagi data juga akan menghapus hasil analisis masalah Anda. Perubahan mungkin memerlukan waktu hingga 24 jam untuk diterapkan.