Logging

Table of Contents

• Logging Levels
• Enable Logging
• Disable Logging
• Site Information Logging
• Statistics Logging
• Organizing Log File Storage
• Where to Store Log Files
• Additional Information

Logging Levels

There are seven levels of logging that are assigned according to priority level, with OFF having the highest value and ALL the lowest value.

• OFF
• FATAL
• ERROR
• WARN
• INFO
• DEBUG
• ALL

Enable Logging

Logging is controlled from a configuration file named EPiServerlog.config and should be placed in the same directory as the application's web.config file. Why is the logging configuration not placed in web.config? The reason for this decision is that if you want to enable logging when the application has entered a bad state, you have to change and save the configuration file. If the information is in web.config, the Web application would be restarted when you save web.config, possibly clearing the cause for the problem that you wanted to log. Keeping the log configuration separate from web.config eliminates this problem.

A typical log configuration file might look like this:

If you want to enable full logging, simply change the level value in the root tag to ALL. Note that this will give you a lot of data.

Disable Logging

There are two ways to disable active logging:

1. Set the level to OFF in EPiServerLog.config.
2. Remove the file and restart the Web site. This can be done by either resaving the system settings/web.config, killing the process or doing an iis-reset. It is not enough to just remove the file; the Web site must be restarted to disable logging.

Site Information Logging

The site information is primarily concerned with logging various problems and unusual events. Basically you should always monitor events with log level WARN and above. Events with lower levels are primarily intended to get information to track down specific errors and/or bugs. A developer might want to enable full logging to a RollingFileAppender (see the log4net documentation) in his development environment to be able to check what has happened in EPiServer CMS—in case a specific problem occurs—but during regular production use, you would probably want to just monitor WARN events and higher.

Exceptions will be logged with the complete stack trace to enable you to track down exception errors. Be aware that exceptions are expensive in terms of performance. You should avoid writing code that generates exceptions as part of the normal program flow.

Statistics Logging

EPiServer CMS has one specific logger that generates output that can be used for statistics analysis similar to traditional Web log analysis. This is the EPiServer.Diagnostics.StatisticsLog. The reason for its existence is that a dynamic Web site may exhibit behavior different from a static Web. For example, when a person looks at the start page of an intranet site, he may be presented with a headline news item and two smaller product-related news items. The Web site owner may want to have information about the specific news items being read so this single “start page hit” should actually be counted as three separate “content” hits.

The statistics logging function in EPiServer CMS is designed to support such behavior. It should usually not be considered a replacement for the traditional IIS log file since the EPiServer CMS log will not register information about GIF images or other static file accesses.

The log file format generated is non-standard and created to be quickly parsed without resorting to complicated algorithms. The format is one row per hit:

YYYY-MM-DD HH:mm:SS,sss|url|hitType|session|sid|pageLink|userName|pageName

Some lines from a sample log file are displayed below:

If you want EPiServer CMS to produce a log file formatted like a standard IIS / W3C Web log file, you can use the Statistics logging event that will be fired for every statistics event and contains all the information described above. In your event handler, you can then choose to output this information in a suitable format, maybe even use the logging functions since they provide a simple and high-performance way to log data.

Some sample code to illustrate how to attach your event handler to such a logging function – for this example it is placed in global.asax.cs:

Organizing Log File Storage

For a production site, it is essential to have a policy regarding log files to avoid problems such as exposing log files on your Web site, filling up a system partition with log data etc. The EPiServer CMS logging functions, with the exception of the EPiServer.Diagnostics.StatisticsLog, are intended to be used to monitor the health of your Web application and should under normal operation not cause excessive logging, as long as you do not enable logging of events below the WARN level. The following are our recommendations on how to store log files. Note that if you are using remoting, UDP appenders or any type of appender that does not write log files to the local drives, the actual storage of log data will probably not happen on the Web server, although other restrictions may apply.

Where to Store Log Files

• Log files should be stored outside the folder structure exposed by the Web server.
  That is to say that if your EPiServer CMS application is installed in the C:\Inetpub\EPiServerSite1 folder, you should not store your log files in the C:\Inetpub\EPiServerSite1\logs folder. This could (depending on Web server configuration and file access rights) expose your logs to any visitor to your Web site.
• Log files should not be stored on the system partition.
  If your Web server has the operating system installed on the C: drive, you should store the log files on another drive. Even though EPiServer's log functions should not cause large log files during normal operation, the log files may grow very large, if you enable full debugging. If the logging takes all free space on your system partition, you will experience all sorts of problems, most likely making your Web site unavailable until the situation has been resolved.

We suggest that you store log files in the following structure (the illustration assumes that we have designated E: as the log storage partition).

Additional Information

The following keys will be added to the Mapped Diagnostic Context (MDC in log4net terms) when possible: