SharePoint Guidance Library - SharePoint Logger Part-1

When you develop business-critical solutions, it is essential to ensure that you make diagnostic information about your application available to administrators and other developers.
Providing and consuming diagnostic information involves two distinct activities: logging and tracing. Logging is primarily directed toward system administrators, who typically rely on the Windows event logs to monitor deployed applications. They often use automated tools such as the System Center Operations Manager (SCOM) to monitor the event logs. Tracing, on the other hand, is primarily directed toward developers and field engineers. Trace logs record more detailed information about action taken and problems encountered during the execution of an application, and are typically used by people who are familiar with the implementation details of the application to monitor behavior and diagnose problems.
Like previous versions of SharePoint Products and Technologies, SharePoint 2010 uses both the Windows event logs and the SharePoint Unified Logging Service (ULS) trace log to record information and exceptions. Using the same approach in your own SharePoint applications offers many benefits. For example, logging your custom application traces to the ULS trace log allows you to view them in the larger context of Windows SharePoint Services operations without having to correlate multiple trace logs. However, implementing logging and tracing functionality can be complex and unwieldy.
The SharePoint Logger is a reusable component that you can use to write messages to the Windows event logs and the ULS trace log. The SharePoint Logger works by exposing and implementing a simple interface named ILogger. This interface defines the two key methods listed in the following table.
ILogger method Description
LogToOperations This method writes a message to the Windows event logs and the ULS trace log. Overloads allow you to specify identifiers, categories, severities, and exception details.
TraceToDeveloper This method writes a message to the ULS trace log. Overloads allow you to specify identifiers, categories, severities, and exception details.
When you write a message to either log, the SharePoint Logger adds contextual information, such as the current URL and the name of the currently logged-on user, which can help the reader to diagnose the problem. The SharePoint Logger also provides a high level of robustness in case the logging fails. For example, if a message cannot be written to the event log, a LoggingException is thrown that contains both the original message and the reason for the logging failure.
The following code shows a simple example of how you can use the SharePoint Logger to write a message to the ULS trace log.
ILogger logger = SharePointServiceLocator.GetCurrent().GetInstance<ILogger>();
logger.TraceToDeveloper("Unexpected condition");
SharePoint 2010 introduces new functionality that can help administrators to manage diagnostic information. You can now configure diagnostic logging by area and by category:
  • Areas correspond to broad areas of SharePoint functionality, such as Access Services, Business Connectivity Services, and Document Management Server.
  • The area is used as the event source name in the Windows event logs.
  • Each area contains one or more categories, which correspond to more specific areas of functionality. For example, the Document Management Server area includes categories named Content Organizer, Information Policy Management, and Records Center.
  • For each category, you can specify the least critical event to report to the event log and the trace log. In other words, this sets the default event throttling threshold for that category. These values are also used as the default severity for a trace or log if no severity level is specified.
The SharePoint Logger allows you to create and register custom areas and categories for use by your own SharePoint applications. This allows administrators to throttle diagnostic logging from your application, along with all the built-in areas and categories, through the SharePoint Central Administration Web site.

When Should I Use the SharePoint Logger?

Generally, when your solutions are migrated from a test environment to a production environment, you lose control over how the execution environment is configured and what resources are available to your solution. Applications can fail in production environments for a variety of reasons, such as firewall issues, permission restrictions, or database configuration. In these circumstances, it is essential that your application can report on any issues it encounters that prevent it from doing its job, in a language that a human can read and understand. To help developers who are working with your components, you should go further still. It is useful to log trace messages at significant points in the execution of your code, such as the following:
  • When you attempt to connect to databases or other external resources
  • When you attempt to query a database
  • When you attempt to call external code
  • When you commence long-running or resource-intensive procedures
  • When you call a method that persists data
You should use the SharePoint Logger whenever you want to write messages to the Windows event logs or the ULS trace log from your SharePoint applications. You can use the SharePoint Logger in any full-trust server–side code that runs in your SharePoint environment.

Benefits of the SharePoint Logger

The SharePoint Logger provides the following benefits:
  • It allows you to write messages and exceptions to the Windows event logs and the ULS trace log in a simple, consistent manner.
  • It adds contextual information to each message, such as the name of the logged-on user and the URL of the current request, to help the reader to identify the problem.
  • It provides a robust logging mechanism that throws a LoggingException with details of the problem if it is unable to write to the event log.
  • It offers a pluggable architecture that enables you to substitute your own custom logging components.
  • It allows you to manage logging through configuration, instead of by creating your own logger from the SPDiagnosticsServiceBase base class.
  • It allows you to use logging and tracing from sandboxed code, through the use of the logging proxy.

Limitations of the SharePoint Logger

By default, the SharePoint Logger can write messages to two locations: the Windows event logs and the ULS trace log. Some organizations prefer to use other repositories for diagnostic logging. For example, you might want log events in a third-party database or use a dedicated trace log for your custom applications.
In these scenarios, you will need to customize various components of the SharePoint Logger. These customizations can range from providing simple alternative implementations of the SharePoint Logger interfaces to developing an entirely new logging framework. For more information about how the SharePoint Logger provides opportunities for customization.

Using the Logger in the Sandbox Environment

The SharePoint Logger is built on the SPDiagnosticsServiceBase class. This is a SharePoint base class that exposes core logging functionality. However, you cannot use this class in sandboxed code. As a result, you cannot use the SharePoint Logger within the sandbox without taking additional action. The Application Design for SharePoint 2010 release includes a full-trust proxy that you can install to enable sandboxed solutions to use logging and tracing functionality. The proxy is installed by a farm scoped feature contained in a farm solution, which is also provided as part of the proxy implementation.
When you call the SharePoint Logger from your application code, the logger will automatically detect whether it is running in the sandbox environment. If it finds that it is running in the sandbox, it will then check whether the full-trust proxy is installed. If the proxy is installed, the logger will use it. If the proxy is not installed, the logger will drop any log or trace messages. If you are unable to install the full trust proxy in your environment, then you can derive from the SharePointLogger.
That’s overview od logging framework available with SharePoint which developers can use in their custom solutions I would come up with more details on implementation in next article on the same

Comments