Flexible iOS Logging

Download

Help us continue to provide great software!

If you find this software useful, please consider making a donation to help us continue to provide and support quality products like this.

(opens in a new window)

Apple’s Cocoa SDK framework for the iOS provides basic logging capabilities through the NSLog function. This allows the developer to log simple text messages to the development console.

However, the use of NSLog suffers from two drawbacks:

There is only one level of logging with NSLog. So during development, you get a record of all of the NSLog calls that you’ve inserted, some of which might be quite detailed and frequent, and it’s easy to be overwhelmed by the clutter. There is no way of selectively turning off some of the output.

The NSLog function is called every time it is encountered, including within executing production release code. To avoid this, developers must typically remove all calls to NSLog before compiling for a production release. This is a headache fraught with possible mistakes and inhibits debugging future releases.

To remedy this, we’ve developed a logging framework that solves both of these issues. This library consists of a single Logging.h header file which adds, to iOS, flexible, non-intrusive logging capabilities that are efficiently enabled or disabled via compile switches.

Quick Start

To use this enhanced logging functionality, simply #import the Logging.h header file into any code file to which you want to add enhanced logging, and set the compiler switch LOGGING_ENABLED=1, either in a #define statement or in the Xcode build setting GCC_PREPROCESSOR_DEFINITIONS.

Logging Levels

To address the first issue described above, that of a single level of logging, this library defines four levels of logging: Trace, Info, Error and Debug, and each is enabled independently via a distinct compiler switch. Invoking any level is as simple as calling the appropriate variadic (variable number of arguments) function as shown in the following examples:

In the examples above, you can see the four logging levels in action, along with the use of variable arguments that match against templates in the message string, in exactly the same manner as the NSLog or printf functions. The first argument is an NSString that optionally includes embedded format specifiers, and subsequent optional arguments indicate data to be formatted and inserted into that string. As with NSLog and printf, there must be an equal number of embedded format specifiers and optional arguments. For more information on string formatting, see the documentation for NSLog, String Format Specifiers and printf formatting.

In this output listing, Logging Sample is just the name of the Xcode project. As you can see, each log message identifies the level of logging. Trace logging is recommended for detailed tracing of program flow, such as inside a loop, or on each frame render in a graphic engine. Info logging is recommended for general, infrequent, information messages such as initialization or shutdown activities, file loads, or user settings changes. Error logging, as the name suggests, is recommended for use only when there is an error to be logged. And finally, debug logging is recommended for temporary use during debugging. When trying to track down a coding error, you might temporarily sprinkle even your most detailed code with debug log messages. But once the problem is resolved, you should remove them, or possibly convert the most useful of them into info or trace logs.

Each of the logging levels is independently turned on or off by setting a boolean compiler switch to either 1 or 0, respectively, as follows:

LOGGING_LEVEL_TRACE enables or disables the LogTrace function.

LOGGING_LEVEL_INFO enables or disables the LogInfo function.

LOGGING_LEVEL_ERROR enables or disables the LogError function.

LOGGING_LEVEL_DEBUG enables or disables the LogDebug function.

By selectively turning on or off each of these switches, you could choose to output only error log messages so that logging will only occur if something goes wrong, or perhaps include info messages, so that you can keep track of high-level events such as file loads, or initialization and shutdown code. And when attempting to debug the details of a module, where you want more copious and detailed logging, you might enable either or both of the trace or debug logging levels.

The LOGGING_ENABLED compiler switch controls overall logging. This is normally turned on in development code to make use of the logging functionality. But in production code, you can disable all logging in one fell swoop by turning off the LOGGING_ENABLED compiler switch. This has the effect of overriding all the individual level switches, and disables all logging. None of the levels will produce log messages with the LOGGING_ENABLED compiler switch turned off.

To assist with tracking down bugs, you can opt to have each logged entry automatically include class, method and line information by turning on the LOGGING_INCLUDE_CODE_LOCATION compiler switch. Doing so will modify the log output above to appear as:

Like most compiler switches, each of the switches discussed in this article is turned on by setting its value to 1 and turned off by setting its value to 0. This can be done via #define statements in your code (or in Logging.h), or via the compiler build setting GCC_PREPROCESSOR_DEFINITIONS in your Xcode build configuration. Using the GCC_PREPROCESSOR_DEFINITIONSXcode setting is the preferred choice, so that logging can be configured differently for different Xcodetargets or build configurations, and particularly to ensure that logging is not accidentally left enabled in production release builds.

Logging Overhead

To address the second issue described above, namely the memory and processing overhead of the logging function calls themselves, the logging functions are implemented here via macros. Disabling logging, either entirely, or at a specific level, completely removes the corresponding log invocations from the compiled code, thereby eliminating both the memory and CPU overhead that the logging calls would add. So, there is absolutely no runtime penalty to be paid by leaving copious quantities of LogTrace calls spread thickly throughout your code, as long as you simply disable either trace logging or all logging by turning off the LOGGING_LEVEL_TRACE or LOGGING_ENABLED compiler switch, respectively, at build time.

Fantastic! Where Can I Get Me Some of That?

You can download this logging framework (a single Logging.h file) in the download area at the top-right of this article. It is distributed under an MIT license, which makes it free for you to use in your projects. However, if you find this code is useful, please remember to make a donation above to help us fund the ongoing development and support of frameworks such as this.

Credit Where Credit is Due

Thanks to Nick Dalton for outlining the underlying ideas for using variadic macros as well as for outputting the code location as part of the log entry.

where lang is a source language format
(eg. text, objc, java).
You can find the full list of language formats and additional configuration options
here.
The source code will be colored according to the language syntax. Don't forget the [] square brackets.