Enhance Crash Reports

Note

All of the following logging tools are thread safe.

Custom Keys

Custom keys help you get the specific state of your app leading up to a crash. You can associate arbitrary key/value pairs with your crash reports, viewable right from the Fabric dashboard.

Setting Keys

Start with [CrashlyticsKit setObjectValue:forKey:] or one of the related methods:

- (void)setObjectValue:(id)value forKey:(NSString *)key;

// calls -description on value, perfect for NSStrings!
- (void)setIntValue:(int)value forKey:(NSString *)key;

- (void)setBoolValue:(BOOL)value forKey:(NSString *)key;

- (void)setFloatValue:(float)value forKey:(NSString *)key;

Update Existing Key Value

Sometimes you need to change the existing key value. Call the same key, but replace the value. Examples:

[CrashlyticsKit setIntValue:3 forKey:@"current_level"];
[CrashlyticsKit setObjectValue:@"logged_in" forKey:@"last_UI_action"];
Crashlytics.sharedInstance().setIntValue(42, forKey: "MeaningOfLife")
Crashlytics.sharedInstance().setObjectValue("Test value", forKey: "last_UI_action")

Note

Crashlytics supports a maximum of 64 key/value pairs. Once you reach this threshold, additional values are not saved. Each key/value pair can be up to 1 KB in size.

Custom Logs

It’s often useful to have some context recorded about the events leading up to a crash. Crashlytics provides logging facilities to make this easy. These messages are associated with your crash data and are visible in the Fabric dashboard if you look at the specific crash.

Note

To make sure that sending crash reports has the smallest impact on your user’s devices, Crashlytics logs have a maximum size of 64 KB. When a log exceeds 64 KB, the earliest logged values will be dropped in order to maintain this threshold.

Custom Logging in Objective-C

CLS_LOG was built to help pinpoint issues. It automatically includes information about the Objective-C class, method and line number where the log line came from.

CLS_LOG(format, ...) is the recommended way to add custom logging to your app.

  • In Debug builds, CLS_LOG passes through to NSLog so you can see the output in Xcode and on the device or simulator.
  • In Release builds, however, CLS_LOG silences all other output, resulting in logging that is about 10X faster than NSLog

Example:

CLS_LOG(@"Higgs-Boson detected! Bailing out... %@", attributesDict);

Browse the Crashlytics/Crashlytics.h header file for more details.

Custom Logging in Swift

To use custom logging in Swift, just use CLSLogv or CLSNSLogv. You need to make an array and then call getVaList function on that array.

CLSLogv("Log awesomeness %d %d %@", getVaList([1, 2, "three"]))

One important thing to note when using Swift is that the format argument of CLSLog, and NSLog, must be a compile-time constant string. While this is enforced by the compiler in Objective-C, it is currently lost in the bridging to Swift at the moment. A possible solution:

func write(string: String) {
    CLSLogv("%@", getVaList([string]))
}

Warning

Swift string interpolation will not result in a compile-time constant string. Just like with printf and NSLog, using a non-constant string with CLSLog can result in a crash.

Advanced

For more control, you can directly leverage CLSLog(format, ...) and CLSNSLog(format, ...). The latter passes through to NSLog so you can see the output in Xcode or on the device or simulator. CLSLog(format, ...) and CLSNSLog(format, ...) are thread safe. CLSLog is meant for logging information important to solving crashes. It should not be used to track in-app events.

Note

Crashlytics ensures that all log entries are recorded, even if the very next line of code crashes. This means that logging must incur some IO. Be careful when logging in performance-critical areas.

User Identifiers

It’s often helpful to know which of your users experienced a given crash. After initializing Fabric, you can use [CrashlyticsKit setUserIdentifier:] to provide an ID number, token, or hashed value that uniquely identifies the end-user of your application without disclosing or transmitting any of their personal information. You can also clear the value by setting it to a blank string. This value is displayed in the Fabric dashboard when looking at a specific crash. Two other related APIs also allow you to include a name and email address.

User Identifiers in Objective-C

[CrashlyticsKit setUserIdentifier:@"123456789"];
[CrashlyticsKit setUserEmail:@"person@domain.com"];
[CrashlyticsKit setUserName:@"Awesome AppUser"];
Crashlytics.sharedInstance().setUserIdentifier("123456789")
Crashlytics.sharedInstance().setUserEmail("person@domain.com")
Crashlytics.sharedInstance().setUserName("Awesome AppUser")