Logging in EPiServer CMS 5

Product version:	EPiServer CMS 5 SP2
Document version:	1.0
Document last saved:	21-04-2008

Introduction

This technical note describes how to configure logging in EPiServer CMS and provides information on how to interpret the logged information and best practices. The intended audiences are developers and system administrators.

The logging system in EPiServer CMS 5 uses the log4net framework and we recommend that you read the introduction at the log4net Web site, http://logging.apache.org/log4net, before reading this technical note.

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:

<log4net>
<appender name="ErrorAppender" type="log4net.Appender.FileAppender" >
        <file value="c:\\EPiServerLog\\1\\Monitor\\Errorlog-file.txt" />
        <appendToFile value="true" />
        <layout type="log4net.Layout.PatternLayout">
                <conversionPattern value="%d [%t] %l - %m%n" />
        </layout>
</appender>

<appender name="StatisticsAppender" type="log4net.Appender.RollingFileAppender">
        <file value="C:\\EPiServerLog\\1\\Statistics\\EPiServerStatistics.log" />
        <appendToFile value="true" />
        <rollingStyle value="Date" />
        <layout type="log4net.Layout.PatternLayout">
            <param name="ConversionPattern" value="%d|%m%n" />
        </layout>              
</appender>

<logger name="EPiServer.Diagnostics.StatisticsLog">
        <level value="INFO" />
        <appender-ref ref="StatisticsAppender" />
</logger>

<root>
        <level value="WARN" />
        <appender-ref ref="ErrorAppender" />
</root>
</log4net>

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:

Set the level to OFF in EPiServerLog.config.
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	Year, month and day. The information is zero-padded.
MM	Month, zero-padded. 01 = January, 02=February etc.
DD	Day, zero-padded.
HH	Hours in 24 hour format, zero-padded.
mm	Minutes, zero-padded.
SS	Seconds, zero-padded.
sss	Milliseconds, zero-padded.
url	The full URL of the request as received by EPiServer CMS, including protocol and host information.
hitType	Indicates the type of page view. Can be one of the following: Page – Regular page view Content – The indicated pageLink was displayed as part of another page. External – Data external to EPiServer was displayed. File – A static file was send to the client.
session	A string identifying a unique session. If a session cannot be determined, this string will be empty. The current implementation simply uses the session ID and thus relies on the session mechanism to be enabled. This is an implementation detail and may change in the future.
sid	An integer representing the user viewing the page. This maps directly to the SID (Security Identifier) used internally in EPiServer (not to be confused with SIDs in Windows). For non-authenticated users this SID will be 3 (= Anonymous).
pageLink	An integer representing the page ID. This field may be empty if hitType is External or File.
userName	The login name of the user viewing the page. For non-authenticated users this name will be Anonymous.
pageName	The name of the current page as entered in edit mode.

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:

public class Global : EPiServer.Global
{
    public Global()
    {
        InitializeComponent();
        EPiServer.Diagnostics.StatisticsLog.Logging +=new EPiServer.Diagnostics.StatisticsEventHandler(StatisticsLog_Logging);
    }
    private void StatisticsLog_Logging(object sender, EPiServer.Diagnostics.StatisticsEventArgs e)
    {
        // Output information from e to the desired target
    }
...
...

Another use for the Logging event would be to implement some type of information aggregation “on-the-fly”. The simplest possible example would be a page hit counter.

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.

Note You must have at least write permission for the directory that you wish to log to for the account that you are using for your Web site.

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).

E:\EPiServerLog\	The root folder for EPiServer logs
1	Give each EPiServer application its unique folder
Monitor	A Monitor folder used to log warnings and errors, i e health monitoring logs.
Statistics	A Statistics folder that should be used if you choose to enable EPiServer's statistics logging.

Additional Information

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

Key name	Description
PageReference	String representation of the current pages page link. Usually the last value set by PageBase.CurrentPageLink
DataFactoryPage	String representation of the page reference passed in to a DataFactory method.
UnifiedFileSystemPath	The path affected by a log event from EPiServer.FileSystem namespace

Try our conversational search powered by Generative AI!