Best Practices for Error Logging and/or reporting

Question

When I do web development, I use a custom made logger that catches fatal errors and appends a trace to a file and displays a message to the user. I can occasionally glance to see if the file changed, which means, some user encountered an error and I can dig in to see what they encountered.

I'd like something similar on the iphone, with some caveats:

• While developing, it should be trivial to reset the list of errors or turn off notification.
• While developing, the error messages should also show up in some obvious place, like on the screen on in the console
• Once deployed, errors should politely be sent to the mothership for analysis (for a bug fix in the next update)
• Turn on Trace/Info logging when trying to track down a problem during development
• Turn off console logging for 'Release' to speed up things for the user
• Should clean-up after itself so as to be a good citizen on the phone

Some Related Links

• Using GSLog for instead of NSLog
• logging to a file on the iphone
• On the Mac, people say Apple System Logger and GTM Logger are the way to go objective-c logging best practices
• Jeff A's Blog entry on logging

It seem like there would be a common toolkit to do this - how do you handle this?

[Update Oct 2011] There have been some developments, of varying maturity...

• PLCrashReporter.
• Quincy sits on top of PLC.
• Bugsense commercial crash reporter.
• Crittercism crash and error reporting (some free packages, some paid).
• Test flight now has an SDK that catches crashes (but not yet for app store apps, just dev apps).
• Like Test Flight, Hockey aims to combine ad hoc distribution with crash reporting.

Answer 1

Here's what we do:

• Let the iPhone handle its own crash dumps through the existing App Store mechanisms. Update: having found iTunes Connect to be unreliable at providing crash reports, I recommend using Fabric/Crashlytics, or a competitor like Crittercism or Rollbar.
• Our released product has no trace in, this seems to be consistent with what most other iPhone apps do.
• If a bug is reported then we reproduce it using a traced build.

In more detail:

• We define macros to NSLog trace at numerous different levels of granularity.
• Use Xcode build settings to change the trace level, which controls how much trace gets compiled into the product, e.g. there are Release and Debug build configurations.
• If no trace level is defined then we show full trace in the Simulator, and no trace when running on a real Device.

I've included example code below showing how we've written this, and what the output looks like.

We define multiple different trace levels so developers can identify which lines of trace are important, and can filter out lower level detail if they want to.

Example code:

- (void)myMethod:(NSObject *)xiObj
{
  TRC_ENTRY;
  TRC_DBG(@"Boring low level stuff");
  TRC_NRM(@"Higher level trace for more important info");
  TRC_ALT(@"Really important trace, something bad is happening");
  TRC_ERR(@"Error, this indicates a coding bug or unexpected condition");
  TRC_EXIT;
}

Example trace output:

2009-09-11 14:22:48.051 MyApp[3122:207] ENTRY:+[MyClass myMethod:]
2009-09-11 14:22:48.063 MyApp[3122:207] DEBUG:+[MyClass myMethod:]:Boring low level stuff
2009-09-11 14:22:48.063 MyApp[3122:207] NORMAL:+[MyClass myMethod:]:Higher level trace for more important info
2009-09-11 14:22:48.063 MyApp[3122:207] ALERT:+[MyClass myMethod:]:Really important trace, something bad is happening
2009-09-11 14:22:48.063 MyApp[3122:207] ERROR:+[MyClass myMethod:]:Error, this indicates a coding bug or unexpected condition
2009-09-11 14:22:48.073 MyApp[3122:207] EXIT:+[MyClass myMethod:]

Our trace definitions:

#ifndef TRC_LEVEL
#if TARGET_IPHONE_SIMULATOR != 0
#define TRC_LEVEL 0
#else
#define TRC_LEVEL 5
#endif
#endif

/*****************************************************************************/
/* Entry/exit trace macros                                                   */
/*****************************************************************************/
#if TRC_LEVEL == 0
#define TRC_ENTRY    NSLog(@"ENTRY: %s:%d:", __PRETTY_FUNCTION__,__LINE__);
#define TRC_EXIT     NSLog(@"EXIT:  %s:%d:", __PRETTY_FUNCTION__,__LINE__);
#else
#define TRC_ENTRY
#define TRC_EXIT
#endif

/*****************************************************************************/
/* Debug trace macros                                                        */
/*****************************************************************************/
#if (TRC_LEVEL <= 1)
#define TRC_DBG(A, ...) NSLog(@"DEBUG: %s:%d:%@", __PRETTY_FUNCTION__,__LINE__,[NSString stringWithFormat:A, ## __VA_ARGS__]);
#else
#define TRC_DBG(A, ...)
#endif

#if (TRC_LEVEL <= 2)
#define TRC_NRM(A, ...) NSLog(@"NORMAL:%s:%d:%@", __PRETTY_FUNCTION__,__LINE__,[NSString stringWithFormat:A, ## __VA_ARGS__]);
#else
#define TRC_NRM(A, ...)
#endif

#if (TRC_LEVEL <= 3)
#define TRC_ALT(A, ...) NSLog(@"ALERT: %s:%d:%@", __PRETTY_FUNCTION__,__LINE__,[NSString stringWithFormat:A, ## __VA_ARGS__]);
#else
#define TRC_ALT(A, ...)
#endif

#if (TRC_LEVEL <= 4)
#define TRC_ERR(A, ...) NSLog(@"ERROR: %s:%d:%@", __PRETTY_FUNCTION__,__LINE__,[NSString stringWithFormat:A, ## __VA_ARGS__]);
#else
#define TRC_ERR(A, ...)
#endif

Xcode settings:

In Xcode build settings, choose "Add User-Defined Setting" (by clicking on the little cog at the bottom left of the build configuration screen), then define a new setting called GCC_PREPROCESSOR_DEFINITIONS and give it the value TRC_LEVEL=0.

The only subtlety is that Xcode doesn't know to do a clean build if you change this setting, so remember to manually do a Clean if you change it.

Answer 2

Do you know that CrashReporter for iPhone exists?

There is a repository on github which demos that code.

It has some cool features like maping the stack trace to your code and manages some git specific things like version hashes.

Answer 3

Apple automatically collects crash logs from users for you, and you can download them from iTunes connect.

If that's not enough for you, I'm not aware of a toolkit but I wouldn't want to roll something on my own, personally. It seems like too much effort to develop something robust, might raise privacy concerns, and in the end, with 100,000K apps in the app store, how many users would use your application again after discovering it was buggy?

Answer 4

I highly recommend Robbie Hanson's CocoaLumberJack: https://github.com/robbiehanson/CocoaLumberjack

It is very flexible and powerful maybe even a bit excessive if abused. Supports different levels of logging. Logging to files can be turned on with a couple of lines of code and even be sent over the network.