ERROR HANDLING AND LOGGING

Umbraco has a reputation for generous error logging; some even say that Umbraco's verbose error and event logging is too much. When you have an issue with your Umbraco site, the error log is an invaluable tool in helping you discover the cause. By default, Umbraco creates a log entry for nearly all events, errors, and custom logging routines, but you can adjust what Umbraco logs by updating the log configuration.

As Umbraco is really an ASP.NET application at heart, errors that are generated within the ASP .NET runtime, and not handled by an error handling routine, will generate an entry (or two) in the Windows event log. This log can be hugely beneficial to developers creating custom code for Umbraco and also for helping to identify issues in third-party packages and code used as part of your Umbraco site.

The Umbraco Error Log

The Umbraco error log is the table umbracoLog in your Umbraco site's database. Because the log is located in the database it offers another good reason to have the Microsoft SQL Server Management Studio installed because viewing the table is much easier. A number of Umbraco packages are also available that allow you to view and manage the contents of the umbracoLog table. You can find these packages in the Projects section of the Umbraco Community site (http://our.umbraco.org/projects/).

As mentioned earlier, the Umbraco error log creates entries for nearly all errors and events in Umbraco. You can change what Umbraco logs by updating the logging section in the /config/umbracoSettings.config file for your site. Here is the default setting for the logging section:

<logging>
    <enableLogging>true</enableLogging>
    <enableAsyncLogging>true</enableAsyncLogging>
    <disabledLogTypes>
      <!-- <logTypeAlias>[alias-of-log-type-in-lowercase]</logTypeAlias> -->
    </disabledLogTypes>
  </logging>

As a general rule, enabling logging in Umbraco is a good practice. However, in situations where a high-performing site is of the utmost importance you may choose to disable logging and gain a performance boost. To disable logging simply set the following key value to false:

<enableLogging>true</enableLogging>

For a production version of your site, disabling some of the types of entries that Umbraco logs is a good practice. Which you decide to disable will depend on your particular requirements and, especially, on the amount of errors your site may generate. The available log type aliases you may choose to disable include the following:

<logTypeAlias>assigndomain</logTypeAlias>
<logTypeAlias>copy</logTypeAlias>
<logTypeAlias>debug</logTypeAlias>
<logTypeAlias>delete</logTypeAlias>
<logTypeAlias>login</logTypeAlias>
<logTypeAlias>loginfailure</logTypeAlias>
<logTypeAlias>logout</logTypeAlias>
<logTypeAlias>move</logTypeAlias>
<logTypeAlias>new</logTypeAlias>
<logTypeAlias>notfound</logTypeAlias>
<logTypeAlias>open</logTypeAlias>
<logTypeAlias>packagerinstall</logTypeAlias>
<logTypeAlias>packageruninstall</logTypeAlias>
<logTypeAlias>ping</logTypeAlias>
<logTypeAlias>publicaccess</logTypeAlias>
<logTypeAlias>publish</logTypeAlias>
<logTypeAlias>rollback</logTypeAlias>

<logTypeAlias>save</logTypeAlias>
<logTypeAlias>scheduledtask</logTypeAlias>
<logTypeAlias>sendtopublish</logTypeAlias>
<logTypeAlias>sendtotranslate</logTypeAlias>
<logTypeAlias>sort</logTypeAlias>
<logTypeAlias>unpublish</logTypeAlias>

You will generally leave the following log type aliases enabled:

<logTypeAlias>system</logTypeAlias>
<logTypeAlias>error</logTypeAlias>
<logTypeAlias>custom</logTypeAlias>

The Windows Event Log

The Windows event log contains entries for errors generated by Umbraco, third-party code, and custom code that run in the .NET Runtime. Generally the errors are logged in the Application section of the Windows logs. You can view the Windows event log from the Windows Event Viewer, a Microsoft Management Console plug-in.

An especially helpful tactic is to create a filtered view of the Application log that displays only entries where the source is from the .NET Runtime and the ASP.NET Runtime version that your Umbraco site is using (see Figure 14-5).

FIGURE 14-5

The most helpful information in a Windows event log entry is generally found in the Exception Information section of the entry's details. The following is an example entry that shows the error is originating from a failed attempt to load the Umbraco.Forms.UI.Pages.FeedProxy class:

…
Exception information:
    Exception type: HttpParseException
    Exception message: Could not load type ‘Umbraco.Forms.UI.Pages.FeedProxy’.
…

A Note about XSLT and Errors

Both of the preceding sections about the Umbraco error log and the Windows event log deal primarily with errors that occur in the execution of .NET code. Although the Umbraco error log also contains entries for Umbraco events and will, generally, contain entries for Umbraco errors, errors encountered in the execution of XSLT are not captured by either of the logs. In the case of XSLT, an XSLT specific error will generally be output to the browser. By default, the error output from Umbraco is the rather unhelpful “Error parsing XSLT file: xsltsomexslt.xslt.”

Given the behavior of XSLT and errors, the best approach is to carefully create your XSLT so that proactive error handling is included, such as checking for empty values or unexpected input. Beyond what you can anticipate occurring, your XSLT might also contain a routine to output a default value if the expected behavior fails.

You can use the XSLT Visualizer from the Umbraco XSLT Editor to test negative input and verify that your XSLT will handle unexpected values gracefully. You can find the XSLT Visualizer on the toolbar of the Umbraco XSLT Editor.