elegantchaos/eclogging

Better logging for Objective-C

ECLogging provides a flexible logging system for iOS and MacOS X software to use.

This is a meme that I've implemented repeatedly in a number of projects over the last 15 or so years, stretching right back to my first big C++ library. I also did an open source C++ implementation in about 2000 I think, although I can't for the life of me work out where it is now!

Essentially, it's a smarter replacement for "printf" or "NSLog" style debug output.

The problem with simply using something like NSLog is that you either end up with reams of debug output, in which case you can't see the wood for the trees, or you end up with messy source code where you're endlessly commenting logging statements in/out. This is especially bad if you work on a big project and/or with lots of developers.

What all my various implementations of a logging system share is the ability to define named channels, and log handlers. These named channels can be organised functionally, rather than by "level". You don't just have to have "warning", "error", or "really bad error". You can have a channel like "stuff related to application notifications", or even "stuff relating to fixing bug #321".

You can direct logging output to a particular channel. All channels are off by default, so you can add detailed logging support to any file or module without spamming the log. If I make a channel, you won't see it in your log unless you choose to turn it on. When you need to, you can turn a particular channel or group of channels on. For release versions, you can compile away all logging completely, for top performance. Or you can choose to leave some log channels in the release build.

The output of log channels is directed through one or more log handlers. What log handlers give you is the ability to globally direct log output into alternative destinations. The console is one option, but you can also write a handler to log to the disk, or a remote machine, or a custom ui, or wherever.

Logging Documentation

If you don't like reading documentation, jump into the 30 Second User Guide, which should get you started quickly.

Or look at the Sample Projects.

If you do read documentation:

• Initialising ECLogging
• Log Channels
• Log Handlers
• User Interface Support
• Configuring ECLogging
• Miscellaneous Features
• Using ECLogging In Your Project

Other Documentation

As well as the logging functionality, ECLogging also contains some common files used by all the other Elegant Chaos libraries.

These were formerly part of the ECConfig and ECUnitTests frameworks, but for the sake of simplicity they're now rolled in to this framework.

For more information, see the associated documentation pages:

• Unit Testing Utilities: ,
• Standard xcconfig Files
• Standard Macros and Definitions
• Standard pch Files
• Standard scripts

Standard Project Layout

Some of the scripts, config files and prefixes work on the assumption that client projects have a standard organisation.

Generally this shouldn't be an issue, and if you don't encounter any problems, don't worry about it.

If you're trying to make use of the standard scripts or config files and are having issues, this may be relevant.

The Finding The Standard Config Files note has more information about why this can be a problem, particularly when you are using ECLogging in your project along with another EC framework.

Arranging your own project to use our standard organisation isn't essential, but if you use a different one you may have to modify some examples accordingly.

If you encounter problems with this, or have suggestions for improvements, please file an issue.

Future

There's lot of stuff that I plan to add to ECLogging, but it generally gets done on an ad-hoc basis as and when I need it.

Take a look at the Issues Page to see what's planned, and what's not working.

eclogging's Issues

add timeout to runUntil method, to avoid deadlocks from killing all tests

read the value of kSettingsVersion from the defaults plist

Currently it's set in code, which means you have to rebuild to force a refresh of the settings.

If we read it from the defaults plist, it makes it easier to bump.

when adding a new channel, the default settings should be read from the ECLogging.plist

Currently I think the ECLogging list will only get used if there are no settings for any channels stored in the preferences.

That's a bit dumb - it would be better if the granularity was per-channel, so that if a new one got added and there was an entry for it added to ECLogging, it would be used for the initial settings.

The channel and handler settings should have individual keys in NSUserDefaults

makes it easier to reset individual channels

More a question than a true issue

Hello,

I have more a question of understanding regarding the documentation.

I use ECDeclareDebugChannel in a .h file to declare common debug channel.
I have however to do ECDefineDebugChannel for that same channel in each individual files despite #import of my common header.

Is there something I am doing wrong ?

Allow the debug menu to be enabled by a user defaults setting

Normally it's on for debug builds and off for release builds. There's no reason in theory now why it couldn't be enabled in release builds too, by a hidden setting.

Look for ECLogging settings in the main Info.plist too

In a command line tool, it's not so convenient to have to embed multiple plists, so it would be handy if ECLogging could find its settings in the main Info.plist instead.

(nb yes, you can have an Info.plist in a command line app - you embed it in the TEXT section)

Allow enabling/disabling individual channels on the command line

We can read command line options from NSUserDefaults.

It would be handy if we could use this to enable/disable channels. We could just use the channel name, but we might need to prefix the names with something to avoid clashes.

NB this is mostly useful for command line tools - possibly it should go into ECCommandLine instead?