When Should I Use the SharePoint Logger?

  • Article

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.

Note

You cannot use the SharePoint Logger from the sandbox environment without a full trust sandbox proxy. This is because the logger derives from a SharePoint base class, SPDiagnosticsServiceBase, which is located in the administrative namespace, is not accessible from the sandbox. The SharePoint Guidance Library includes a full trust proxy that enables you to use the SharePoint Logger within the sandbox environment.

It is important to ensure that you create appropriate areas and categories for your logging messages and that you choose suitable trace and event severity levels for the logged information. Typically, administrators set up message filtering according to severity levels. If you set your severity levels too low, important information could be missed. On the other hand, if you set your severity levels too high, it could cause performance issues as large amounts of details information are written to the logs. For best practice guidance on how to configure logging in a SharePoint environment see Configure diagnostic logging on TechNet.

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, see Design of the SharePoint Logger.

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.

For more information about how to deploy the logging proxy and how to define your own logger, see Using the SharePoint Logger from Sandboxed Code. For more information about full-trust proxies in general, see Execution Models in SharePoint 2010.