Introduction to NSLogger

Logging as a debugging aid

Developing complex applications is hard. Your software goes through numerous execution paths, and it can sometimes be confusing to precisely understand how your software runs. This is particularly true of multi-threaded software, networking in general and applications with complex data models where not only code paths but also execution timing can be crucial.

One way to better understand your code’s behavior at runtime is to log as much information as possible about what internally happens in your software, when important changes happen, when unpredicted situations arise, and so on. Crawling through a mountain of log lines (the haystack) can make it difficult to find the precise bit of information (the needle) you’re looking for.

This is one of the motivations behind the development of NSLogger. The goal is to make it easy to explore specific aspects of an application’s runtime behavior, while keeping constant access to as much context information as possible. To this end, a suggested approach is to instrument your application with as much logging as needed, and leave all the log constantly turned on during debugging.

Traditionally, developers enable partial logging in their applications when they need to get specific information. The NSLogger approach is to leave all log turned all, all of the time, and to provide the developer with a data mining tool that makes it straightforward to locate what you’re looking for. The viewer is designed to be able to swallow large amounts of log data; the client code was written in a way that doesn’t slow down your application while it transfers your logs to the viewer.

Modern logging options

NSLogger can of course log text messages (which are not limited in length), but also binary data and even images. Logging binary data in one simple API call is a very helpful option that can be a time saver in many situations (for example network programming). Logging images is less crucial has its use too, for example when you need to inspect graphics downloaded from the network or created by your application, or when you want to remotely log a screenshot.

Categorize information

To make your information easier to search, NSLogger lets you categorize it through the use of tags, and levels. A tag is meant to specify the general domain in your application the log gives information about (for example “graphics”, “networking”, “database”, etc). Levels can be used to log more general information at lower levels, and much more data at higher levels.

A view of your world

NSLogger lets you create filters you’ll use to quickly switch between different views of your data. You can select multiple filters to aggregate them and view just the relevant information your need. To give you a sense of time lapse in your application, the time elapsed between each log message and the previous one (the displayed one, if your display is currently being filtered) is shown by NSLogger.

Save, reload and share

Each logged session can be saved for later inspection. You can also send log sessions to coworkers if needed, which can be very useful in a teamwork context.

Advanced uses

Every time your application starts, or creates and starts a new Logger instance, the viewer opens a new window and displays the information sent through this logger. There are benefits to this approach. You can, for example (NSLogger has been created with these scenarios in mind):

• Use the default logger for debugging, and through the use of macros and conditional compilation, turn debug logging off for release builds,
• Instrument your code to use a logger you instantiate on demand, in a release build. Combined with the ability to connect to the viewer remotely over the internet, this lets you distribute builds to testers or even customers, that have the capacity to connect directly to your viewer when running. One of the potential uses is live troubleshooting of issues in software running at remote locations.
• Buffer logs to a file that you can later transmit to a server. The NSLogger desktop viewer can read this raw file (provided that is has the .rawnsloggerdata extension).

Secure team player

NSLogger encrypts its connections using SSL, so your data is secure. In teamwork situations, you can setup Bonjour so that it automatically finds your computer and not send logs to another machine. Sharing log files with other team members is a no brainer, and the ability to place markers within the log let you share your comments of what happen.

Even more advanced: extensibility

NSLogger has been designed to be extensible in several ways:

• The data transfer protocol transmits binary encoded key-value data. Besides the regular keys the logger itself uses, you are free to customize the client side to add any custom data.
• Combined with the above, the viewer could be customized to display your custom data in a completely different way. For example, let’s say you develop a server on Mac OS X. You could leverage the NSLogger code to create a window that displays internal information about your server in real time, like the number of open connections, server load, cache information, etc.
• Since NSLogger was designed to have clients separate from the viewer, your monitoring console can be on a separate machine on your network, or even in a remote location.
• The NSLogger desktop viewer is architected to make it easy to plug in new log sources. In other words, it is possible to add support for receiving logs in other formats. For example, one could add support for receiving logs in JSON format, and turn them into standard NSLogger messages for viewing.