Debugging Your Mappings

Nothing is more frustrating than having something that doesn’t work and not knowing why! That’s why I invested a great deal of effort to add the necessary tools allowing you to easily pinpoint those nasty issues.

The Debug Section

In the navigation bar click on Debug to get to the page where you can control the logging facility. This page is basically showing you the latest 50 log entries in reverse chronological order. The physical location of the log file is /debug.log in the application’s root folder.

Each log entry shows a message and the time at which it was created. All entries are initially in collapsed state, but if you click on one entry, it expands and additional information gets revealed. Different entries may have different amount of additional information.

The Log Entry Types

There are basically two main types of log entries:

  • Runtime entries – these ones are generated by runtime errors or unhandled exceptions and are preceded by a suggestive icon and one of the following severity level designators: NOTICE, WARNING, ERROR, CRITICAL, ALERT. They are also colored to better emphasize their severity levels. Of course, the occurrence of unhandled exceptions is generally a bad sign. An unhandled exception could reveal either a flawed design of the application or an abnormal condition that couldn’t be anticipated by the developer.
  • Debug entries – these ones are preceded by a bug-like icon and the word DEBUG. These are the log entries that we are going to concentrate on.

Normally, the log is populated only by runtime entries, when unhandled exceptions are occurring (hopefully never!), whereas the debug entries are generated only when debug mode is active.

The log entries are recorded in sequence and, as I already mentioned, they are displayed in reverse chronological order, the most recent entries being at the top.

Let me explain now the purpose of the buttons at the top of the Debug page:

  • Debug ON/OFF – as the name suggests, it turns ON and OFF the debug mode. With the debug mode ON, the log is populated with detailed debug messages, which can help you figure out what’s going on.
  • Refresh ON/OFF – with the ON setting the page is automatically refreshed at 10-second rate so that you see the log entries coming in almost in real-time. When you want to pause the refreshing, you simply turn it OFF.
  • Clear Log – removes all entries of the log so you can start your debugging session from scratch.
  • Collapse All / Expand All – these buttons do exactly what they say.

The debug messages have different colors, depending on the phase of the process that is carried on, and their meaning is as follows:

 marks the beginning of a notification processing.
 informational message.
 indicates a failed operation.
 indicates a successful operation.

So, a notification processing starts with a blue line and ends with a green or red line. Here’s an example of how an actual log snippet may look like:

In normal use, the Debug setting must be kept in OFF position to avoid uncontrollable growth of the log file. Activate the debug mode only when you need to investigate a malfunction.

The Mappings’ Error Indicator

In addition to the logging facility that includes complete information about the processing of all mappings, we created an error indicator for mappings so that you can get an idea of their health condition just by looking at the Mappings page. If a mapping process generated errors, that mapping will be shown in reddish color, and an exclamation point icon will appear to the left of its name.

At this point, if you click on that icon, a popup will show up displaying a mini-log related to that particular mapping, as in the picture below. These mini-logs will not retain all messages, but only the ones indicating failed operations, because their purpose is to be able to quickly spot and debug the mappings with buggy behavior.

To maintain the overall amount of data at a decent level, these mapping specific mini-logs are limited to maximum 10 most recent entries. As new entries are added, the oldest ones get deleted.

The log entries can be expanded and collapsed, and they are refreshed in real-time, just like in the Debug page, so you can always see the most up-to-date information.

These per mapping mini-logs are always populated regardless of the debug mode setting, so you’ll always be able to monitor the mappings’ health state.

To get rid of the mini log entries and to clear the mapping’s error state, just click on Clear Errors button.