Log files

Introduction to log files in ConSol CM

Log files are the main source of information about the activities in the system and potential problems. They are used to save log messages from the different components of ConSol CM.

Definitions

log file: Text file with the extension .log used to write messages about the activities in the system and errors
log level: The log level determines which messages are written in the log files and how many details are included in the log messages. The most used log levels are ERROR, INFO and DEBUG.

Purpose and usage

Log files contain information about the system activity. If an error occurs during system operation, they contain details about the error. Analyzing log files is useful for troubleshooting of errors and to reveal problems which do not appear on the user interface.

There are two ways of accessing the log files:

Open the file on the file system. The default path is <JBOSS_HOME>/standalone/log.
Open the Log files page of the Web Admin Suite, where you can view and download the log files.

Available log files

The following log files are available in ConSol CM:

access.log: Contains log messages about the access to and usage of the Web Client. Needs to be enabled explicitly, see Activating the access.log file.
audit.log: Contains log messages about login / logout operations in the Web Admin Suite, and all operations which are performed using these applications, e.g. configuration changes and workflow deployments. In addition, all changes to the page customization are logged.
cmrf.log: Contains log messages from the CMRF (ConSol CM Reporting Framework), i.e., messages regarding the data transfer operations from the ConSol CM database to the CMRF database (DWH).
cmweb.log: Contains log messages from the Web Client.
ctx.log: Contains log messages from the Spring Framework.
errors.log: Contains only log messages that have at least the log level ERROR.
etl-runner.log: Contains log messages generated by ETL Runner. If ETL Runner is run as standalone application, the file is called etlRunner.log.
index.log: Contains log messages regarding the index.
mail.log: Contains log messages regarding email system.
operationtimes.log: Contains log messages with timing information for requests in order to identify possible performance bottlenecks. This logging is configured using the system property cmweb-server-adapter, request.log.threshold.milliseconds.
operationtimes-db.log: Contains log messages about database access times of atomic operations in order to identify possible performance bottlenecks. This logging is configured using the system properties cmas-core-server, dao.log.threshold.milliseconds and cmas-core-server, dao.log.username.
operationtimes-rest.log: Contains log messages with operation times for REST requests. The request URL and the time needed to process the request are logged on DEBUG level. The logging is configured using the system properties cmas-restapi-core, request.log.threshold.milliseconds and cmas-restapi-core, request.log.username.
operationtimes-search.log: Contains log messages with operation times for searches. The logging is configured using the system property cmas-core-server, search.log.threshold.milliseconds.
scripts-output.log: Contains log messages generated by scripts.
security.log: Contains log messages which are related to security, authorization and authentication
server.log: Contains all log messages with at least log level INFO.
session.log: Contains log messages about logins (session starts) and session timeouts of users.
sql.log: Contains log messages about SQL statements coming from Hibernate if it is set to DEBUG level (by default it is set to INFO).
support_libs_errors.log: Contains error messages which are thrown by supporting libraries but are properly handled by ConSol CM (this method keeps the server.log clean).
timer-manager.log: Contains additional log messages written in log level DEBUG when workflow timers are activated or deactivated. Information about the escalation date is logged, too.
track_jersey.log: Contains log messages from CM/Track.
trackv3.log: Contains log messages from CM/Track V3.
transfer.log: Contains log messages about the export / import of scenes.
tx.log: Contains log messages related to Spring Framework transactions.
unit-deletion.log: Contains information regarding the deletion of contacts.
workflow.log: Contains log messages about activated / reinitialized / deactivated timers, which are logged with level INFO and all debug output related to the workflow engine.

Structure of log files

In the default configuration, the log file entries have the following syntax:

Date Timestamp Loglevel [Logger] Message

Example for a log file entry:

2020-10-11 13:52:44,526 INFO [reemarker.FreeMarkerConfigurer] [-] ClassTemplateLoader for Spring macros added to FreeMarker configuration

The components of the message:

Date: October 11th, 2020
Timestamp: 13:52:44
Log level: INFO
Logger: reemarker.FreeMarkerConfigurer. These are the last 30 characters of the name of the Java class.
Message: ClassTemplateLoader for Spring macros added to FreeMarker configuration

Simple messages and messages reporting a successful operation often have only one line. When errors are reported (log level ERROR), you might find stack traces in the logs.

Basic tasks

Accessing the log files using the Web Admin Suite.

You can access the log files which are saved in the default directory on the Log files page in the Operation menu. When opening the page, the latest lines of the server.log file are displayed.

You can perform the following actions on the page:

View a log file: Select the desired log file in the selector on the left side. All the log files which are saved in the default directory, <JBOSS_HOME>/standalone/log, are available. You can click the Full screen icon to view the log file in full screen mode. The Wrap text / Unwrap text icon allows you to decide whether the log messages should be wrapped or not.
Download log files: Click the Download log files button and select the log files which you want to download. The currently displayed log file is preselected. You can select additional log files to download several files at once. If several files are selected, they are downloaded as zip package. You can click the Download all log files button to add all log files to the zip package.
Refresh log files: By default, the log files are refreshed every 5 seconds. If needed, you can change the selector to Refresh every second or Do not refresh automatically. You can reload the log files manually at any time by clicking the Refresh icon.
Configure display order: The newest lines are displayed at the top if the checkbox Display newest lines first is selected. Deselect his checkbox to display the oldest lines first.

Add logging to scripts

You can add log output to your scripts by using the log statement with the desired log level.

log.info "This is my log message."

DEBUG messages will only appear in the log file when the logging configuration has been changed. Check whether debugging is switched on to avoid unnecessary operations:

if (log.isDebugEnabled()) {
  log.debug("Processing ticket ${ticket.name}")
}

Advanced tasks

Configuring logging

The default path for the log files is <JBOSS_HOME>/standalone/log. The location of the log files and the logging behavior can be configured in the respective configuration files:

cm6-config.properties: JBoss EAP / Wildfly standalone installations with or without CMRF
cm6-domain-config.properties: JBoss EAP cluster installation
cmrf.properties: CMRF as a standalone application
trackv3.properties: CM/Track V3 as a standalone application
etlRunnerApplication.properties: ETL Runner as standalone application

Advanced logging configuration

The built-in logging module of JBoss EAP is used for the ConSol CM logging subsystem. Usually, no changes are required in a standard ConSol CM standalone installation.

The log files are saved under <JBOSS_HOME>/standalone/log.

The configuration of the logging subsystem is defined in one of the following files, depending on the infrastructure of your CM system. Usually, you do not need to edit the XML files.

ConSol CM only: <JBOSS_HOME>/standalone/configuration/cm6-<DB>.xml
ConSol CM with CMRF/DWH: <JBOSS_HOME>/standalone/configuration/cm6-dwh-<DB>.xml

You can modify the default configuration in the respective configuration file:

ConSol CM only or ConSol CM with CMRF/DWH: <JBOSS_HOME>/bin/cm6-config.properties
Standalone CMRF: <CMRF_HOME>/cmrf.properties

For configuring the logging behavior, the following section of the configuration file is relevant:

<subsystem xmlns="urn:jboss:domain:logging:3.0">

Within the section of this subsystem, the file handlers are defined, each in a separate subsection. By default, periodic size rotating file handlers are used. One log file is created for every day. If the maximum size of 50 MB is exceeded, a new file is created for this day. 10 files are kept as backup.

Example from the index.log section:

<periodic-size-rotating-file-handler name="INDEX_FILE" autoflush="true">
  <level name="${handler.indexfile.level:INFO}"/>
  <formatter>
    <pattern-formatter pattern="%d %-5.5p [%30.-30c] [%X{username}-%X{context}-%X{sessionId}] %m%n"/>
  </formatter>
  <file relative-to="jboss.server.log.dir" path="index.log"/>
  <suffix value=".yyyy.MM.dd"/>
  <max-backup-index value="${handler.indexfile.max.backup.index:10}"/>
  <rotate-size value="${handler.indexfile.rotate.size:50m}"/>
  <append value="true"/>
</periodic-size-rotating-file-handler>

Below the file handlers, the loggers are defined. For each logger, the target file(s) and the log level are provided.

<logger category="com.consol.cmas.core.index" use-parent-handlers="false">
  <level name="${logger.com.consol.cmas.core.index.level:INFO}"/>
  <handlers>
    <handler name="INDEX_FILE"/>
  </handlers>
</logger>

This means that the logger for classes belonging to com.consol.cmas.core.index writes into the file INDEX_FILE, which is defined in the file handler section above.

The variables in the syntax ${setting:value}, e.g. ${handler.indexfile.level:INFO}, indicate parameters which can be overridden in the <JBOSS_HOME>/bin/cm6-config.properties file.

Changing default settings

Please proceed as follows to modify logging settings:

Locate the logging configuration in the cm6-<DB>.xml file or cm6-dwh-<DB>.xml
Add entries with the desired values to the cm6-config.properties file.

The following example shows how to change default settings using the cm6-config.properties file.

Goal: You want to change the log level of the index.log file to DEBUG.

Locate the respective handler in the configuration file (example from cm6-mysql-5.xml).

 <periodic-size-rotating-file-handler name="INDEX_FILE" autoflush="true">
   <level name="${handler.indexfile.level:INFO}"/>
   <formatter>
     <pattern-formatter pattern="%d %-5.5p [%30.-30c] [%X{username}-%X{context}-%X{sessionId}] %m%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="index.log"/>
   <suffix value=".yyyy.MM.dd"/>
   <max-backup-index value="${handler.indexfile.max.backup.index:10}"/>
   <rotate-size value="${handler.indexfile.rotate.size:50m}"/>
   <append value="true"/>
 </periodic-size-rotating-file-handler>

Locate the variable for the log level. This is ${handler.indexfile.level:INFO}.
Add an entry for this variable to cm6-config.properties.

  # logging overrides
  handler.indexfile.level=DEBUG

Other changes you can make:

Change the size of the single log files: Set the value (in MB) of the parameter rotate-size, e.g. handler.indexfile.rotate.size=50.
Change the number of copies which are saved: Set the value of the parameter max-backup-index, e.g. handler.indexfile.max.backup.index=1.
Debug a certain module: Set the log level to DEBUG for the respective logger, e.g. logger.com.consol.cmas.core.index.level=INFO

If there is no variable for a setting which you want to modify, you can edit the cm6-<DB>.xml or cm6-dwh-<DB>.xml file directly. This is required for example if you want to change the pattern for the log file entries (pattern-formatter attribute).

Activating the access.log file

In a default installation, the following lines in the configuration file, cm6-<DB>.xml or cm6-dwh-<DB>.xml are commented out. By commenting them in, you can start access logging in your ConSol CM system.

<server name="default-server">
  <http-listener name="default" max-post-size="${max-post-size-bytes:104857600}"
    socket-binding="http"
    redirect-socket="https"
    enable-http2="true"/>
  <ajp-listener name="ajp" socket-binding="ajp"
    max-post-size="${max-post-size-bytes:104857600}"/>
  <https-listener name="https" max-post-size="${max-post-size-bytes:104857600}"
    socket-binding="https"
    ssl-context="applicationSSC"
    enable-http2="true"/>
  <host name="default-host" alias="localhost"><!--
    <access-log pattern="%h %l %u %t %r %s %b %{Referer}i %{User-Agent}i %S %T" directory="${jboss.server.log.dir}" prefix="access" suffix=".log" worker="default"/>
    --><location name="/" handler="welcome-content"/>
  <http-invoker/>
  </host>
</server>

Introduction to log files in ConSol CM​

Definitions​

Purpose and usage​

Available log files​

Structure of log files​

Basic tasks​

Accessing the log files using the Web Admin Suite.​

Add logging to scripts​

Advanced tasks​

Configuring logging​

Changing default settings​

Activating the access.log file​