▼ More about EPiServer

Documentation

Products

CREATE+

EPiServer Connect...

Documentation Type

Logging in EPiServer CMS

Product version:	EPiServer CMS 4.62
Document version:	1.0
Document creation date:	07-06-2006
Document last saved:	05-10-2007

Purpose

This document 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.

Introduction

Enable Logging

Disable Logging

Site Information Logging

Statistics Logging

Organizing Log File Storage

Site Information Logging Reference
    - Top Class Level
    - DataAccess
    - DataAbstraction
    - Personalization
    - FileSystem
    - Core
    - WebControls
    - ClientTools
    - Security
    - Mirroring/Export/Import
    - Log Service
    - XForms
    - Multi Language
    - WSRP
    - Web Parts
    - System Controls
    - Util

Additional Information

Introduction

The logging system in EPiServer CMS 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 document.

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:

</layout>

</appender>

</layout>

</appender>

<appender-ref ref="StatisticsAppender" />

</logger>

<root>

<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 is designed to support such behavior. It should usually not be considered a replacement for the traditional IIS log file since the EPiServer 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, 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 the EPiServer CMS 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 CMS logs
1	Give each EPiServer CMS 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 the EPiServer CMS statistics logging.

Site Information Logging Reference

Every logging message has a unique identity in the form x.y.z to enable you to quickly determine the source of the message. This identity is hierarchical and based on the class structure in EPiServer CMS. The list below lists all possible log information that EPiServer CMS can generate as well as explanations and more information.

1 Top Class Level

1.1 Logger EPiServer.PageBase

1.1.1	WARN Access denied	The access denied method was called because the current user did not have access to the requested page.
1.1.2	WARN Loading page with wrong page template	The page that was referenced by the ID parameter should not be displayed with the page template file named in the URL.
1.1.3	INFO Page initialized	The page has been loaded and access has been verified. This is logged at the end of the PageBase.OnInit method.
1.1.4	DEBUG PageBase makes a permanent redirect to friendly URL from='<url>’ to=’<url>’	A access is made directly to the page and a permanent redirect is done to the friendly URL for the page.

1.2 Logger EPiServer.Global

1.2.1	DEBUG Enter Global constructor	Entering the EPiServer.Global constructor. Logged before any actions are performed. Note that this may be entered into the log multiple times, but the “Leave Global constructor” message (1.2.2) should only be logged once per application startup. This is because the constructor is protected from multiple initializations.
1.2.2	DEBUG Leave Global constructor	Leaving the Global constructor. See comments on 1.2.1
1.2.3	INFO Authenticate request	The Application_AuthenticateRequest event has been handled by EPiServer. If authentication is successful the Context.User should be set to the authenticated user.
1.2.4	ERROR - exception FormsAuthentication failed	The FormsAuthentication_OnAuthenticate event failed with an exception. The exception is logged and program execution continues with User set to AnonymousUser.
1.2.5	ERROR – exception Unhandled exception in ASP.NET	The HttpApplication.Error event has been raised and caught by EPiServer. The exception is logged and the error will be sent to the response stream if the current user has the required privileges to see runtime errors.
1.2.6	ERROR HttpApplication created without HttpContext	This message indicates that EPiServer may not have been able to configure all its internal settings due to missing information about the web application at the time the GlobalBase class was created. This should never happen under IIS as the first HttpApplication’s will be created by ASP.NET with a HttpContext, it can happen in design mode in Visual Studio.NET.
1.2.7	INFO Precompilation reqluest for file X	Added in version 4.40 A precompilation request, as indicated by the query string parameter EP_PreCompile, was received for the url X. This means that the actual processing of the page will terminate immediately after precompilation, so no further execution takes place.

1.3 Logger EPiServer.LazyIndexer

1.3.1

ERROR – exception IndexPage failed for page X

Some kind of error occurred when the LazyIndexer tried to index a page. Will append the ID of the page that failed.

1.4 Logger EPiServer.ApplicationConfiguration

1.4.1	DEBUG Persist entered	Will try to save EPiServer settings to web.config.
1.4.2	DEBUG Persist without a WindowsIdentity	Trying to save the config file when logged on with a non-Windows account. This may cause problems since the account might not have correct privileges to write the file.
1.4.3	DEBUG Persist with a WindowsIdentity	Trying to save the config file when loggen on with a Windows account. However no impersonation has been made.
1.4.4	DEBUG Persist with a WindowsIdentity and impersonation	Trying to save the config file when loggen on with a Windows account and impersonating that user.
1.4.5	DEBUG Persist with a WindowsIdentity and impersonation	Trying to save the config file when loggen on with a Windows account and impersonating that user.
1.4.6	*DEBUG* Persist values ‘<values' updatedBySid='<sid>

1.5 Logger EPiServer.GatlingCompatibility

1.5.1	DEBUG Gatling compatibility enabled / disabled	Reports the state of the Gatling (i e EPiServer 3) compatibility flag.
1.5.2	ERROR – exception Failed to write registry data	An exception was thrown in response to saving configuration data to the EPiServer 3 registry location. Usually caused by privilege problems.
1.5.3	ERROR – exception Failed to read registry data	An exception was thrown in response to loading configuration data from the EPiServer 3 registry location. Usually caused by privilege problems.
1.5.4	INFO EPiServer 3 cache management enabled	The GatlingCompatibility.InitializeCache method was called when EPiServer 3 compatibility was enabled. This has resulted in event handlers being attached to the global DataFactory instance to clear the EPiServer 3 cache as necessary.

1.6 Logger EPiServer.DataFactory

1.6.1	ERROR – exception Constructor without HttpContext	The DataFactory constructor was called without having a valid HttpContext. This may cause problems with the upload directory settings.
1.6.2	WARN – exception Access denined in GetDefaultPageData
1.6.3	ERROR – exception GetChildren failed	Some kind of exception occurred when loading children.
1.6.4	ERROR – exception GetPage failed
1.6.5	DEBUG FindPagesWithCriteria enter
1.6.6	DEBUG FindPagesWithCriteria leave
1.6.7	INFO Version: {VersionID} Page: {PageID} was deleted by {User}	The internal version number (i.e. not the one shown in the browser), page ID and the user who deleted (from the recycle bin) it, will be logged.
1.6.8	INFO Page: {PageID}, with {n} children was deleted by {User}	The page ID, number of children, and the user who deleted (from the recycle bin) it, will be logged.
1.6.9	INFO The recycle bin was purged by {User}	Each time a user purges the recycle bin it is logged.
1.6.10	DEBUG Page: {PageID_of_1st_page} was deleted by {User} . . DEBUG Page: {PageID_of_{n}th_page} was deleted by {User}	The page ID, and the user who deleted it (from the recycle bin), will be logged.
1.6.11	INFO Page: {PageID} was moved to the recycle bin by {User}	The page ID, and the user who moved the page to the recycle bin, will be logged. (If there are children, they will not be logged, since they are not deleted, only moved)
1.6.12	WARN – exception Access denied in CreateLanguageBranch
1.6.13	INFO Page: {PageID} Language: {LanguageID} was deleted by user {User}

1.7 Logger EPiServer.CacheManager

1.7.1	ERROR – exception Failed to remove item from remote cache
1.7.2	DEBUG Begin remove item from remote cache
1.7.3	DEBUG End remove item from remote cache
1.7.4	DEBUG Remove pending remote cache request without matching info. Key:X, Site:Y	This message is logged when the asynchronous web service call is finished if the corresponding information used for serializing calls cannot be found. This indicates a threading problem.

2 DataAccess

2.1 Logger EPiServer.DataAccess.BackupDB

2.1.1

ERROR – exception BackupDataBase failed

An exception occurred in the database backup process.

2.2 Logger EPiServer.DataAccess.CategoryDB

2.2.1	ERROR – exception Category load failed	An exception occurred in the category load process.
2.2.2	ERROR – exception Category save failed	An exception occurred in the category save process.
2.2.3	ERROR – exception Category load tree failed	An exception occurred in the category load tree process.
2.2.4	ERROR – exception Category dataset save failed	An exception occurred in the category dataset save process.
2.2.5	ERROR – exception Category list failed	An exception occurred in the category list process.

2.3 Logger EPiServer.DataAccess.DatabaseInformationDB

2.3.1

ERROR – exception Load information failed

2.4 Logger EPiServer.DataAccess.DynamicPropertiesDB

2.4.1	ERROR – exception Dynamic properties load tree failed
2.4.2	ERROR – exception Dynamic properties load failed
2.4.3	ERROR – exception Dynamic properties save failed
2.4.4	INFO – Dynamic property pageId='<pageId>' property='<PropertyValue>' sid='<sid>'

2.5 Logger EPiServer.DataAccess.FormDefinitionDB

2.5.1	ERROR – exception Load form definition failed
2.5.2	ERROR – exception Save form definition failed
2.5.3	ERROR – exception Listing all forms failed

2.6 Logger EPiServer.DataAccess.FormPostingDB

2.6.1	ERROR – exception Save form posting failed
2.6.2	ERROR – exception Posting check failed

2.7 Logger EPiServer.DataAccess.FormStatisticsDB

2.7.1	ERROR – exception Get form statistics failed
2.7.2	ERROR – exception Get form statistics with time limit failed
2.7.3	ERROR – exception Delete form statistics failed

2.8 Logger EPiServer.DataAccess.FrameDB

2.8.1	ERROR – exception List frames failed
2.8.2	ERROR – exception Save frames failed

2.9 Logger EPiServer.DataAccess.GatlingDB

2.9.1

ERROR – exception Gatling change log failed

2.10 Logger EPiServer.DataAccess.LanguageDB

2.10.1	ERROR – exception Language list failed
2.10.2	ERROR – exception Language save failed

2.11 Logger EPiServer.DataAccess.PageDefinitionDB

2.11.1	ERROR – exception Page ACL list failed
2.11.2	ERROR – exception Page ACL save failed
2.11.3	ERROR – exception Page ACL save recursive failed
2.11.4	*INFO* – Page definition save name='<Name>' id='<id>' sid='<sid>
2.11.5

Documentation

Products

CREATE+

EPiServer Connect...

Documentation Type

Logging in EPiServer CMS

Purpose

Table of Contents

Introduction

Logging Levels

Enable Logging

Disable Logging

Site Information Logging

Statistics Logging

Organizing Log File Storage

Where to Store Log Files

Site Information Logging Reference