Tùy chỉnh báo cáo sự cố Firebase Crashlytics của bạn

Hợp nhất rung trên iOS + Android

Hướng dẫn này mô tả cách tùy chỉnh các báo cáo sự cố của bạn bằng SDK Firebase Crashlytics. Theo mặc định, Crashlytics tự động thu thập báo cáo sự cố cho tất cả người dùng ứng dụng của bạn (thay vào đó, bạn có thể tắt báo cáo sự cố tự động và bật báo cáo chọn tham gia cho người dùng của mình). Crashlytics cung cấp bốn cơ chế ghi nhật ký ngay lập tức: khóa tùy chỉnh , nhật ký tùy chỉnh , số nhận dạng người dùng và ngoại lệ đã bắt được .

Thêm khóa tùy chỉnh

Khóa tùy chỉnh giúp bạn biết trạng thái cụ thể của ứng dụng dẫn đến sự cố. Bạn có thể liên kết các cặp khóa/giá trị tùy ý với các báo cáo sự cố của mình, sau đó sử dụng các khóa tùy chỉnh để tìm kiếm và lọc các báo cáo sự cố trong bảng điều khiển Firebase.

• Trong bảng điều khiển Crashlytics , bạn có thể tìm kiếm các sự cố khớp với khóa tùy chỉnh.
• Khi đang xem xét một sự cố cụ thể trong bảng điều khiển, bạn có thể xem các khóa tùy chỉnh được liên kết cho từng sự kiện ( tab phụ Khóa ) và thậm chí lọc các sự kiện theo các khóa tùy chỉnh ( menu Bộ lọc ở đầu trang).

Sử dụng phương thức setCustomValue để đặt các cặp khóa/giá trị. Ví dụ:

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

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

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

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

Bạn cũng có thể sửa đổi giá trị của một khóa hiện có bằng cách gọi khóa đó và đặt nó thành một giá trị khác. Ví dụ:

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

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

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

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

Thêm hàng loạt cặp khóa/giá trị bằng cách sử dụng phương thức setCustomKeysAndValues ​​với NSDictionary làm tham số duy nhất:

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)

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];

Thêm thông điệp nhật ký tùy chỉnh

Để cung cấp thêm ngữ cảnh cho các sự kiện dẫn đến sự cố, bạn có thể thêm nhật ký Crashlytics tùy chỉnh vào ứng dụng của mình. Crashlytics liên kết nhật ký với dữ liệu sự cố của bạn và hiển thị chúng trong trang Crashlytics của bảng điều khiển Firebase , trong tab Nhật ký .

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

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

[[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];

Đặt số nhận dạng người dùng

Để chẩn đoán sự cố, việc biết người dùng nào của bạn gặp phải sự cố cụ thể thường rất hữu ích. Crashlytics bao gồm một cách để xác định ẩn danh người dùng trong báo cáo sự cố của bạn.

Để thêm ID người dùng vào báo cáo của bạn, hãy chỉ định cho mỗi người dùng một số nhận dạng duy nhất ở dạng số ID, mã thông báo hoặc giá trị băm:

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

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

Nếu bạn cần xóa mã định danh người dùng sau khi đặt, hãy đặt lại giá trị thành chuỗi trống. Xóa mã định danh người dùng không xóa các bản ghi Crashlytics hiện có. Nếu bạn cần xóa bản ghi được liên kết với ID người dùng, hãy liên hệ với bộ phận hỗ trợ của Firebase .

Báo cáo các trường hợp ngoại lệ không nghiêm trọng

Ngoài việc tự động báo cáo sự cố của ứng dụng, Crashlytics cho phép bạn ghi lại các trường hợp ngoại lệ không nghiêm trọng và gửi chúng cho bạn vào lần khởi chạy tiếp theo của ứng dụng.

Bạn có thể ghi lại các ngoại lệ không nghiêm trọng bằng cách ghi lại các đối tượng NSError bằng phương thức recordError . recordError nắm bắt ngăn xếp cuộc gọi của chuỗi bằng cách gọi [NSThread callStackReturnAddresses] .

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

[[FIRCrashlytics crashlytics] recordError:error];

Khi sử dụng phương thức recordError , điều quan trọng là phải hiểu cấu trúc NSError và cách Crashlytics sử dụng dữ liệu để nhóm các sự cố. Việc sử dụng sai phương thức recordError có thể gây ra hành vi không thể đoán trước và có thể khiến Crashlytics hạn chế báo cáo lỗi đã ghi cho ứng dụng của bạn.

Một đối tượng NSError có ba đối số:

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

Không giống như các sự cố nghiêm trọng được nhóm thông qua phân tích dấu vết ngăn xếp, các lỗi đã ghi được nhóm theo domain và code . Đây là sự khác biệt quan trọng giữa sự cố nghiêm trọng và lỗi đã ghi. Ví dụ:

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)

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];

Khi bạn ghi lại lỗi ở trên, lỗi này sẽ tạo ra sự cố mới được nhóm theo NSSomeErrorDomain và -1001 . Các lỗi đã ghi bổ sung sử dụng cùng một tên miền và giá trị mã được nhóm lại trong cùng một vấn đề. Dữ liệu chứa trong đối tượng userInfo được chuyển đổi thành các cặp khóa-giá trị và được hiển thị trong phần khóa/nhật ký trong một vấn đề riêng lẻ.

Nhật ký và khóa tùy chỉnh

Giống như báo cáo sự cố, bạn có thể nhúng nhật ký và khóa tùy chỉnh để thêm ngữ cảnh vào NSError . Tuy nhiên, có sự khác biệt về loại nhật ký được đính kèm với sự cố so với lỗi đã ghi. Khi sự cố xảy ra và ứng dụng được khởi chạy lại, nhật ký mà Crashlytics truy xuất từ ​​đĩa là những nhật ký được ghi ngay trước thời điểm xảy ra sự cố. Khi bạn đăng nhập NSError , ứng dụng sẽ không chấm dứt ngay lập tức. Vì Crashlytics chỉ gửi báo cáo lỗi đã ghi vào lần khởi chạy ứng dụng tiếp theo và phải giới hạn dung lượng được phân bổ cho các nhật ký trên đĩa, nên có thể ghi đủ nhật ký sau khi NSError được ghi lại để tất cả các nhật ký có liên quan được loại bỏ vào thời điểm Crashlytics gửi báo cáo từ thiết bị. Hãy ghi nhớ số dư này khi ghi nhật NSErrors và sử dụng nhật ký cũng như khóa tùy chỉnh trong ứng dụng của bạn.

cân nhắc hiệu suất

Hãy nhớ rằng việc ghi lại một NSError có thể khá tốn kém. Tại thời điểm bạn thực hiện cuộc gọi, Crashlytics nắm bắt ngăn xếp cuộc gọi của luồng hiện tại bằng cách sử dụng một quy trình có tên là tháo ngăn xếp. Quá trình này có thể tốn nhiều công sức của CPU và I/O, đặc biệt là trên các kiến ​​trúc hỗ trợ tháo gỡ DWARF (arm64 và x86). Sau khi quá trình thư giãn hoàn tất, thông tin được ghi vào đĩa một cách đồng bộ. Điều này ngăn ngừa mất dữ liệu nếu dòng tiếp theo bị lỗi.

Mặc dù gọi API này trên chuỗi nền là an toàn, nhưng hãy nhớ rằng việc gửi lệnh gọi này đến một hàng đợi khác sẽ làm mất ngữ cảnh của dấu vết ngăn xếp hiện tại.

Còn về NSExceptions thì sao?

Crashlytics không cung cấp phương tiện để ghi nhật ký và ghi trực tiếp các phiên bản NSException . Nói chung, Cocoa và Cocoa Touch API không phải là ngoại lệ an toàn. Điều đó có nghĩa là việc sử dụng @catch có thể gây ra các tác dụng phụ ngoài ý muốn rất nghiêm trọng trong quy trình của bạn, ngay cả khi được sử dụng hết sức cẩn thận. Bạn không bao giờ nên sử dụng câu lệnh @catch trong mã của mình. Vui lòng tham khảo tài liệu của Apple về chủ đề này.

Tùy chỉnh dấu vết ngăn xếp

Nếu ứng dụng của bạn chạy trong môi trường không phải nguồn gốc (chẳng hạn như C++ hoặc Unity), bạn có thể sử dụng API Mô hình ngoại lệ để báo cáo siêu dữ liệu sự cố ở định dạng ngoại lệ gốc của ứng dụng. Các trường hợp ngoại lệ được báo cáo được đánh dấu là không gây tử vong.

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)

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];

Khung ngăn xếp tùy chỉnh cũng có thể được khởi tạo chỉ bằng các địa chỉ:

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)

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];

Bật báo cáo chọn tham gia

Theo mặc định, Crashlytics tự động thu thập báo cáo sự cố cho tất cả người dùng ứng dụng của bạn. Để cung cấp cho người dùng nhiều quyền kiểm soát hơn đối với dữ liệu họ gửi, bạn có thể bật báo cáo chọn tham gia bằng cách tắt báo cáo tự động và chỉ gửi dữ liệu tới Crashlytics khi bạn chọn trong mã của mình:

1. Tắt bộ sưu tập tự động bằng cách thêm khóa mới vào tệp Info.plist của bạn:

   • Khóa: FirebaseCrashlyticsCollectionEnabled
   • Giá trị: false

2. Kích hoạt tính năng thu thập cho những người dùng được chọn bằng cách gọi tính năng ghi đè thu thập dữ liệu Crashlytics khi chạy. Giá trị ghi đè vẫn tồn tại trong các lần khởi chạy ứng dụng của bạn để Crashlytics có thể tự động thu thập báo cáo.

   Để chọn không tham gia báo cáo sự cố tự động, hãy chuyển false làm giá trị ghi đè. Khi được đặt thành false , giá trị mới sẽ không áp dụng cho đến lần chạy tiếp theo của ứng dụng.

   Nhanh

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Mục tiêu-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

Quản lý dữ liệu Crash Insights

Thông tin chi tiết về sự cố giúp bạn giải quyết sự cố bằng cách so sánh dấu vết ngăn xếp ẩn danh của bạn với dấu vết từ các ứng dụng Firebase khác và cho bạn biết liệu sự cố của bạn có phải là một phần của xu hướng lớn hơn hay không. Đối với nhiều sự cố, Crash Insights thậm chí còn cung cấp tài nguyên để giúp bạn gỡ lỗi sự cố.

Thông tin chi tiết về sự cố sử dụng dữ liệu sự cố tổng hợp để xác định các xu hướng ổn định chung. Nếu không muốn chia sẻ dữ liệu của ứng dụng, bạn có thể chọn không tham gia Thông tin chi tiết về sự cố từ menu Thông tin chi tiết về sự cố ở đầu danh sách sự cố Crashlytics trong bảng điều khiển Firebase .