This content is archived. See latest version here

Last updated: Mar 25 2013

Table of Contents

Introduction

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. The logging system in EPiServer CMS uses the log4net framework and you are recommended to read the introduction at the Log4net website before reading this document.

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

Enabling 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. The reason why the logging configuration is separated from web.config 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 can look as follows:

XML
<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<a 
            href="fileEPiServerStatistics.log&quot;>\\EPiServerStatistics.log</a>" />
                    <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.

Disabling Logging

You have the following ways to disable active logging:

  • Set the level to OFF in EPiServerLog.config.
  • Remove the file and restart the website. 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 because the website must be restarted to disable logging.

Logging Site Information

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. Avoid writing code that generates exceptions as part of the normal program flow.

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 website, filling up a system partition with log data etc. The EPiServer CMS logging functions are intended 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.

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 website.
  • Store log files outside the folder structure exposed by the web server. This means that if your EPiServer CMS application is installed in the C:\Inetpub\EPiServerSite1 folder, do 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 website.
  • Do not store log files on the system partition. This means that if your web server has the operating system installed on the C: drive, 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 website unavailable until the situation has been resolved.

Store log files in the following structure (the illustration assumes that E: is designated as the log storage partition):

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

See Also

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

Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/