When running dotCMS, log files from several sources are created, depending on how dotCMS is installed and what features you have enabled in both dotCMS and your application server. Please see the following documentation sections for the different log file types and configurations:
- dotCMS Application Log Files (this document)
- Application Server Log Files
- Special Logging Configurations
Note: Log File Locations
By default, each log file is stored in a specific default location, but the locations where the log files are stored can be changed. To find the default locations for each log file or to change the log file locations, please see the Log File Locations documentation.
Application Log Files
The dotCMS application generates log files to record dotCMS operation, warnings, and errors. dotCMS allows for easy logging configuration, including log rotation, controlling the frequency of log messages, and setting up of multiple loggers. All logging in dotCMS uses the industry standard Apache Log4j 2.0 framework.
By default, all dotCMS application logs are configured for moderate message frequency and no output to the console. To modify the dotCMS logging configuration for improved performance or to address specific logging needs, please select the appropriate section below:
Log4j Configuration File
To configure dotCMS logging, edit the log4j2.xml file. The default location for the file is /dotserver/tomcat-X.xx/webapps/ROOT/WEB-INF/log4j/log4j2.xml.
This is best handled by mounting an adjusted file into your container.
There are 3 sections of the log4j2.xml file: Properties, Appenders and Loggers.
Properties Section
The locations and file names of all log files is specified in the <Properties> section.
File Names and Paths
The properties ending in _LOG_FILE specify the name and location of the active log file.
The properties ending in _FILENAME_PATTERN specify the name and location of additional rotation files (additional files created when the log file exceeds the maximum log file size set in the Appenders section — see below).
By default, all log files are stored in the location specified by the system variable $\{sys:DOTCMS_LOGGING_HOME\}, which is set automatically by dotCMS. To change the location where log files are stored, change the properties ending in _LOG_FILE and _FILENAME_PATTERN to the desired path(s).
Message Patterns
Messages displayed on the console will be displayed in the form defined in the CONSOLE_PATTERN property. Messages written to log files will be written in the form defined in the MESSAGE_PATTERN property. For more information on patterns, please see the Apache Log4j Pattern Layout documentation.
Appenders Section
The <Appenders> section defines the log4j appenders which may be used, and the parameters for each appender. Appender parameters include SizeBasedTriggeringPolicy, which specifies the maximum size of a single log file, and DefaultRolloverStrategy, which specifies the number of rollover files created after the main log file reaches the maximum size. For additional information on appenders, please see the Apache Log4j Appenders documentation.
Loggers Section
The <Loggers> section allows you to change how messages from specific dotCMS modules are logged. For each class, you may specify both the Appender (which log file the messages are written to), and the log level (which determines both the level of detail and number of messages written).
AppenderRef
Each Logger must specify one or more Appenders using the <AppenderRef> tag. Loggers can only reference Appenders which are specified in the Appenders section of the log4j2.xml file. If 2 or more Appenders are specified for a single Logger, messages from that class will be duplicated and written to both Appenders.
The Root Logger
The <Root> Logger is the default Logger. Any class which does not have a Logger specifically configured will use the log level and Appender specified in the Root logger.
Log Level and Message Frequency
The log level determines what kinds of messages will be written to the log file. There are 5 message levels defined in dotCMS:
- debug
- info
- warn
- error
- fatal
The higher the message level, the more serious the issue being logged. When a logger specifies a log level, all messages of that level and all higher levels will be logged to the file. So, for example, if you specify a log level of info, all messages of warn, error, and fatal message levels will also be written to the logs.
Common Logging Changes
Changing Message Frequency
The log level also affects the frequency of the messages. The lower the message level configured for a module, the greater the number of messages that will be logged for that module.
- To increase the number of messages logged for a particular module, reduce the log level for that module.
- To decrease the number of messages logged for a particular module, increase the log level for that module.
- Note: Also see Filters, below.
For example, if you are debugging your Velocity code and wish to get more detailed messages, you may wish to change the log level for “org.apache.velocity” from “warn” (level 3) to “info” (level 2). But if you want to reduce the number of messages in the logs for Apache nutch, you may want to change the log level for “org.apache.nutch” from “info” (level 2) to “warn” (level 3).
Console Output
The CONSOLE is a special Appender which allows you to specify how messages logged to the console are displayed. The configuration of the console output is specified in the <Console> portion of the Appenders section. For more information on configuring the Console Appender, please see the Apache Log4j Console Appender documentation.
By default all CONSOLE Appender messages are written to the standard output (stdout). However the default configuration in dotCMS does not include the CONSOLE Appender in any Loggers. This means that by default, no dotCMS log messages will be written to standard output.
For performance reasons, it is strongly recommended that you do not display dotCMS log messages to the console (standard output). However if you wish to log messages to the console for diagnostic purposes, you can do so by adding an AppenderRef for the CONSOLE Appender to each Logger you wish to monitor in the console.
Adding New Loggers
You may add new Loggers to change or filter logging on specific classes as needed. For example to configure debug level logging on just webdav classes you can use the following:
<Logger name="com.dotmarketing.webdav" level="debug" additivity="false">
<AppenderRef ref="generic"/>
</Logger>
Combining All Logs into a Single File
There are two ways to combine all log messages into a single log file.
Important Note: On busy systems with high levels of logging activity, combining all messages into a single log file can cause significant performance degredation. Because of this it is not recommended to combine log files on very large or very busy sites.
1. Single Combined Log File
If you wish to eliminate all other log files, simply comment out all Loggers except for the Root Logger. Since all classes which do not have a specific Logger will use the Root Logger, this will cause all messages to log to the Appender specified in the Root Logger.
2. Log Messages Duplicated Into a Combined File
If you wish to maintain separate log files, but still ensure that all messages are also logged into a single combined log file, you must add an <AppenderRef> for the combined log file into the Logger for each class.
For example, in the default log4j2.xml file, the “generic” Appender writes to the dotcms.log file, and the Root Logger writes to the “generic” Appender (and thus to the dotcms.log file). If you want all log messages to be written to the dotcms.log file, you must add an <AppenderRef> for the “generic” appender to all Loggers which do not already include it.
<AppenderRef ref="generic"/>
When a Logger includes an <AppenderRef> for more than one Appender, all messages for that class will be written to the log files for both Appenders. For example, if you add the “generic” Appender to the “com.liferay.portal.action.LoginAction” Logger, then each time a user logs in to the system, a message will be written to both the “generic” Appender (dotcms.log file) and the “security” Appender (dotcms-security.log file).
<Logger name="com.liferay.portal.action.LoginAction" level="info" additivity="false">
<AppenderRef ref="security"/>
<AppenderRef ref="generic"/>
</Logger>
Filters
In addition to changing the Log Level for different Loggers, you may also limit the number of log messages by specifying a <Filters> section within individual loggers. Filters enable you to selectively limit output by preventing some messages from being logged.
Log4j provides 10 different types of filters, and filters may be configured directly in the configuration (Context-wide Filters), on a specified logger (Logger Filters), in an Appender (Appender Filters) or in an Appender Reference (Appender Reference Filters). For more information on all of the filter types and how the filters operate in each context, please see the Apache Log4j Filters documentation.
Burst Filter
Although Log4j offers multiple filter types, the <BurstFilter> can be especially useful for improving performance, and is recommended for managing log size and improving performance for high traffic sites.
This filter allows you to limit the number and rate of messages of a given type sent to a logger. For example, the following configuration limits the number of log statements that can be sent to the console:
<Console name="CONSOLE" target="SYSTEM_OUT">
<PatternLayout pattern="${CONSOLE_PATTERN}"/>
<Filters>
<BurstFilter level="info" rate="15" maxBurst="100"/>
</Filters>
</Console>
This specifies that a maximum of 100 messages can be sent at one time (per the maxBurst="100" data attribute) and no more than 15 messages can be sent per second (the rate="15" attribute). Since the filter level is set to “info”, this affects info and debug message levels, but warn, error and fatal messages will continue to be delivered without any filtering (so no important messages will be lost, even under high load).
For more information on the Burst Filter configuration, please see the Apache Log4j BurstFilter documentation.
For more information on Log4j configuration, please see the Apache Log4j documentation.
