SharePoint Trace Logs and the Unified Logging Service (ULS)

This is to explain what the ULS logs are, why they exist, and how to read and write 'em. In a nutshell, the Unified Logging Service (ULS) writes WSS 3.0 and MOSS events to SharePoint’s Trace Logs, and these are stored in the file system in ...\12\LOGS. Collectively this location and its files are commonly referred to as the “ULS Logs” though MSDN calls them the Trace Logs.  

According to the MSDN Trace Log docs:

<“Developers can program their applications to write custom operations messages to the trace log, the same log that Windows SharePoint Services uses to log developer-oriented information and events. Writing to the same trace log Windows SharePoint Services employs enables third-party developers to view their custom application traces in the larger context of Windows SharePoint Services operations, without having to correlate multiple trace logs. In addition, the trace log provides a central destination for information concerning development processes, such as debugging. This alleviates the need for developers to log their development information in other places, such as the Windows Event Log, which are more commonly used by system administrators.”

Configuring ULS Logs

Operations àDiagnostic Logging. The Diagnostic Logging options are described on TechNet,  and in the excellent "Taming SharePoint Trace Logs" blog.

Recommended configuration:

• Sign up for the Customer Experience Improvement Program: Disabled
• Error Reports: Ignore errors and don’t collect information.
• Event Throttling: Recommend no throttling in development environments, and throttling from Audit Failure and above to capture warnings and errors in Production environments.
• Trace Log Path: Create a new logging location on a drive (i.e. a physical spindle) that does not contain your OS or data. It is a good practice to create such a location for all such logs so that if the drive fills up, it doesn't jeopardize the health of either the OS or your data. Yes, of course you can also use it for your IIS logs. Note that if you change this location, the location must exist for all servers in the farm.
• Number of log files and minutes to use a log file: The default gets you two days, how far you go is up to you.

The administrator can select events to log either in the Diagnostic Logging page, or more selectively with the STSADM command line utility. Verbosity should be set according to the environment and intended audience. For example: more verbose in development where developers actively debug applications, and as-needed in production where a network operations team uses the logs to monitor application health. For further information see the Taming article (cited above) on the topic search the internet for “SharePoint verbosity diagnostic logging.”

Reading the ULS Logs

The raw ULS logs can be difficult to navigate, and SharePoint provides no built-in viewer. To fill the gap and ease development and administration, free third-party tools exist like SPTraceView and WSS/MOSS Log File Reader (which plugs into Central Administration). Some utilities including SPTraceView will aggregate log data from more than one server in the farm. 

Writing ULS Logs

What to write? The ULS logs are appropriate for recording any application lifecycle and diagnostic events not recorded elsewhere, including messages during feature installation, removal, activation, deactivation, startup, shutdown, and exceptions. Message types are identified through the Trace Severity property: Unassigned, Critical Event, Warning Event, Information Event, Exception, Assert, Unexpected, Monitorable, High, Medium, and Verbose.

To write Trace Logs you need a Trace Provider. MSDN provides a sample TraceProvider here. And that one was either adapted or copied into the Community Kit for SharePoint available here. I'm providing both, even though they're (virtually?) identical is that I would hope the CKS code will evolve and I don't expect that of the MSDN content.

Assuming the CKS version works for you (it's buried in the CKS.EWE subtree), you could build a wrapper like this for exception logging:

using System;
using System.Collections.Generic;
using System.Text;
using System.Diagnostics;
using CKS.Utilities.UlsLogs;
using System.Reflection;
namespace EliRobillard.SharePoint.Diagnostics
{
class ULS
{
/// <summary>
/// Log an error to the ULS log
/// </summary>
/// <param name="productName">The name of the application or project.</param>
/// <param name="errorMessage">The text of the error message.</param>
/// <param name="errorCategory">The category of the error, usually the feature or solution being implemented.</param>
public static void LogError(string productName, string errorMessage, string errorCategory)
{
TraceProvider.WriteTrace(0, TraceProvider.TraceSeverity.CriticalEvent, Guid.NewGuid(), Assembly.GetExecutingAssembly().FullName, productName, errorCategory, errorMessage);
}
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Or just as simple (and without the overhead of reflection), just add your reference and call WriteTrace() directly. Look for the LogMessage methods inside the CKS.EWE.WikiDiscussion.CoordinateActions receiver, there are good examples of descriptive logging and those methods could be used in your own MyName.SharePoint.Utilities.Diagnostics project.