Log File Viewing documentation for the dotCMS Content Management System

dotCMS provides an extremely flexible logging framework which provides a number of default logs, and gives you the flexibility to modify the logging configuration, and to view the log files in the back-end UI (without the need for administrative shell access to the dotCMS server).

Viewing the Log Files

The most recent messages from the dotCMS log files may be displayed from the dotCMS back-end by opening the Control Panel → Maintenance Tool and selecting the Log Files tab.

The Log Files tab “tails” the logs. When you first open the logs, only the most recent messages in the log files will be shown. Once you've opened this screen, any new messages written to the log file will be added to the display, so you can use this screen to continually view the log files.

Log File Descriptions

By default, dotCMS creates and updates several different log files, each of which records different types of information, warnings, and errors. The following table lists all of the default log files created, and the purpose of each log file and the information tracked in each. For any of the log files displayed with a link in the table below, you may click on the link for a more detailed description of the contents of the log file.

NameFile NameType of Information Recorded
Main LogdotCMS.logThe primary log file, in which most status, warning, and error messages are written.
This is the most common log file viewed by customers and dotCMS support.
Audit Logdotcms-userActivity.logUser activity.
Admin Audit Logdotcms-adminaudit.logMore sensitive administrative activity.
Push Publishing Logdotcms-pushpublish.logPush Publishing operations.
Note: Most Push Publishing operations are also recorded in the Main Log.
Security Logdotcms-security.logLogin activity.
Site Search Logdotcms-sitesearch.logErrors and warnings related to the Site Search feature and indexes.
Velocity Logdotcms-velocity.logErrors and information generated during the execution of Velocity code.
Access Logdotcms_access.XXX-XX-XX.logA daily log of all access requests made to the dotCMS server.

Audit Log: dotcms-userActivity.log

The dotCMS User Activity log records the following information for all of the following changes to the system:

  1. Content Publishing
    • Start & end dates
    • User that made the modification
    • Content identifier
  2. Role Modifications
    • Type of action: creation, modification, deletion, enabling, or disabling
    • Date of modification
    • User that made the modification
    • Role identifier
  3. User Role Modifications
    • User that was modified
    • User that made the modification
    • Date of modification
    • Roles added or removed
  4. Scheduled Jobs
    • User starting/stopping the job
    • Date of modificaton
    • Job identifier
  5. Scheduled Job Modifications
    • Type of Action: creation, deletion, or modification
    • User that made the modification

Admin Audit Log: dotcms-adminaudit.log

For webmaster convenience, the admin audit log isolates logging of more sensitive operations concerning the creation and activation of dotcms data and processes. The log records the following information:

  • Date & time of operation
  • UserID or dotCMS class initiating the action
  • Verbose description of the action
  • Verbose description of the results of the action

Push Publishing Log: dotcms-pushpublish.log

Whenever a push publishing action takes place (an object is push published, a bundle is uploaded or downloaded, etc.), the push publish log records the following information:

  • Date and time of attempt
  • User performing the action
  • Bundle ID
  • Date & time of Push Publish start
  • Date & time of Push Publish end
  • Errors from failed Push Publish actions

Security Log: dotcms-security.log

The security log records the following information regarding all login activity by dotCMS users:

  • Date & time of user login/logout
  • UserID
  • IP Address of user

Velocity Log: dotcms-velocity.log

The velocity log displays helpful velocity error and information messages to help webmasters identify and correct problems in velocity code. The Velocity log records the following information:

  • URL of the request
  • Macro ID (if applicable)
  • Template used by the page request
  • Velocity stack trace

Access Log: dotcms_access.XXX-XX-XX.log

The Access Log is named and stored with the date in the title, and records the following:

  • IP Address making the request
  • Date and time
  • Request type
  • Request detail (url's, context, header info, etc.)

Changing and Adding Log Files

The log file names and locations, and the information written to each log file, are defined in the log4j2.xml file, and may be changed. For more information please see the Logging Configuration documentation.

The Log Manager Tool

Clicking on Log Manager Tool pops up a window that allows webmasters to turn on / off the logging to dotcms-adminaudit.log, dotcms-security.log and dotcms-userActivity.log. To turn logging on/off, simply select the checkbox to the left of the desired log, and click the “Update System Logging” button.

Log File Locations

The Log Files tab lists only files that end in a .log extension. By default, the Log Files tab will only list log files contained in the default log file location (/dotserver/Tomcat-X.xx/webapps/ROOT/dotsecure/logs in the dotCMS installation).

If you change the location where your log files are stored, or if you wish to be able to tail logs in other locations (such as your application server log files), you must update your configuration so dotCMS can find the log files in different locations.

Note: If you change the DYNAMIC_CONTENT_PATH property, the location of the log files will change, and the log files will no longer display in the Log Files tab. You must use one of the methods below or you will no longer be able to display your logs from the Log Files tab.

There are two ways to specify where the Log Files tab looks for log files:

1. Set the TAIL_LOG_LOG_FOLDER Property

You may set the TAIL_LOG_LOG_FOLDER property in the dotmarketing-config.properties file to tell dotCMS where to look for log files. When this property is set, the Log Files tab will display all log files found in and below the specified folder.

For example, if you set this property to the root of your dotCMS installation, the Log Files tab will include all log files in and below the dotCMS root folder, which will include:

  • Your currently active dotCMS log files.
  • Older (rolled) versions of your dotCMS log files.
  • Your Tomcat application server log files.
  • Any other files anywhere in the dotCMS folder tree that end in a .log extension.

If your log files are not stored in the default location, you can create a symbolic link from the default location (/dotserver/Tomcat-X.xx/webapps/ROOT/dotsecure/logs) to the location where your log files are stored.

Note:

  • This approach allows you to update the log file location without re-deploying plugins and restarting the dotCMS server.
  • However it requires a manual change to the dotCMS file tree, which makes upgrades more difficult.
    • Since upgrades of dotCMS replace all files and folders in the dotCMS installation tree, if you use this method, the symbolic links must be recreated manually any time dotCMS is updated.
    • For this reason, this method is not recommended for most installations.

Symbolic Link Example

If you change the DYNAMIC_CONTENT_PATH property to /opt/dotcms/dotsecure, your log files will now be located in /opt/dotcms/dotsecure/logs. You could then run the following Linux command to add a symbolic link to point the Log Files tab to the new log location:

ln -s /opt/dotcms/dotsecure/logs $DOTCMS_HOME/dotserver/tomcat-8.0.18/webapps/ROOT/dotsecure/logs