Monitoring Logs

Logging is one of the most important aspects of a production-grade server. A properly configured logging system is vital for identifying errors, security threats, and usage patterns.

See the following topics for details:

Log types in WSO2 products

Listed below are the various log types that are used in WSO2 products.

• Carbon logs: All WSO2 products are shipped with log4j logging capabilities that generate administrative activities and server side logs. The Carbon log (wso2carbon.log) is a log file that covers all the management features of a product. Carbon logs are configured in the log4j.properties  file (stored in the  <PRODUCT_HOME>/repository/conf  directory).  

• Audit logs:  Audit logs are used for tracking the sequence of actions that affect a particular task carried out on the server. These are also configured in the  log4j.properties  file.

• HTTP access logs: HTTP requests/responses are logged in access logs to monitor the activities related to an application's usage. These logs are configured in the catalina-server.xml file (stored in the <PRODUCT_HOME>/repository/conf/tomcat/ directory).

• Patch logs: These logs contain details related to patches applied to the product. Patch logs cannot be customized. See WSO2 Patch Application Process for more information.

• Service/Event logs: These are logs that are enabled in some WSO2 products for tracing services and events using a separate log file (wso2-<product>-trace.log). If server/event tracing logs are used in your WSO2 product, you can configure them in the log4j.properties file.

• Product-specific logs: Each WSO2 product may generate other log files in addition to the Carbon logs, Audit logs, HTTP access logs, Patch logs and Service/Event logs. See the product's documentation for descriptions of these log files and instructions on how to configure and use them.

Configuring products for log monitoring

See the following information on configuring Carbon logs, Audit logs, HTTP access logs, and Service/Event logs for your WSO2 product.

• Configuring Carbon logs

  You can easily configure Carbon logs using the management console of your product, or you can manually edit the log4j.properties file. It is recommended to use the management console to configure logging because all changes made to log4j through the management console persists in the WSO2 Registry. Therefore, those changes will be available after the server restarts and will get priority over what is defined in the log4j.properties file. Also, note that the logging configuration you define using the management console will apply at run time.  However, if you modify the log4j.properties file and restart the server, the earlier log4j configuration that persisted in the registry will be overwritten. There is also an option in the management console to restore the original log4j configuration from the log4j.properties file. The log levels that can be configured are listed below.

  Identifying forged messages: 

  The log pattern defines the output format of the log file. From Carbon 4.4.3 onwards, the conversion character 'K' can be used in the pattern layout to log a UUID. For example, the log pattern can be [%K] [%T] [%S] [%d] %P%5p {%c} - %x %m {%c}%n, where [%K] is the UUID.

  The UUID can be used for identifying forged messages in the log. By default, the UUID will be generated every time the server starts. If required, you can configure the UUID regeneration period by manually adding the following property to the log4j.properties file (stored in the <PRODUCT_HOME>/repository/conf directory):

  log4j.appender.CARBON_LOGFILE.layout.LogUUIDUpdateInterval=<number_of_hours>

  See the following topics for instructions:

  • Configuring Log4j Properties

  • Configuring the Log Provider

• Configuring Audit logs

  Audit logs are enabled in WSO2 products by default. You can change the following default configuration by manually updating the the log4j.properties file. The log levels that can be configured are listed below.

  log4j.logger.AUDIT_LOG=INFO, AUDIT_LOGFILE # Appender config to AUDIT_LOGFILE log4j.appender.AUDIT_LOGFILE=org.wso2.carbon.utils.logging.appenders.CarbonDailyRollingFileAppender log4j.appender.AUDIT_LOGFILE.File=${carbon.home}/repository/logs/audit.log log4j.appender.AUDIT_LOGFILE.Append=true log4j.appender.AUDIT_LOGFILE.layout=org.wso2.carbon.utils.logging.TenantAwarePatternLayout log4j.appender.AUDIT_LOGFILE.layout.ConversionPattern=[%d] %P%5p {%c}- %x %m %n log4j.appender.AUDIT_LOGFILE.layout.TenantPattern=%U%@%D [%T] [%S] log4j.appender.AUDIT_LOGFILE.threshold=INFO log4j.additivity.AUDIT_LOG=false

• Configuring HTTP access logs

  See HTTP Access Logging for instructions on how to configure and use HTTP access logs.

• Configuring Service/Event tracing logs
  A separate log file for tracing services/events are enabled for certain WSO2 products in the log4j.properties file using a specific appender. These logs are published to a file named wso2-<product>-trace.log. See the table given below for instructions relevant to your product:

Setting the Log4j log level

The log level can be set specifically for each appender in the log4j.properties file by setting the threshold value. If a log level is not specifically given for an appender as explained below, the root log level (INFO) will apply to all appenders by default.

For example, shown below is how the log level is set to DEBUG for the CARBON_LOGFILE appender (Carbon log):

Listed below are the log levels that can be configured:

Managing log growth

See the following content on managing the growth of Carbon logs and Audit logs:

Managing the growth of Carbon logs

Log growth (in Carbon logs) can be managed by the following configurations in the <PRODUCT_HOME>/repository/conf/ log4j.properties file.

• Configurable log rotation: By default, log rotation is on a daily basis.

• Log rotation based on time as opposed to size: This helps to inspect the events that occurred during a specific time.

• Log files are archived to maximise the use of space.

The log4j-based logging mechanism uses appenders to append all the log messages into a file. That is, at the end of the log rotation period, a new file will be created with the appended logs and archived. The name of the archived log file will always contain the date on which the file is archived. 

Limiting the size of Carbon log files

You can limit the size of the <PRODUCT_HOME>/repository/logs/wso2carbon.log file by following the steps given below. This is useful if you want to archive the logs and get backups periodically.

1. Change the log4j.appender.CARBON_LOGFILE=org.wso2.carbon.utils.logging.appenders.CarbonDailyRollingFileAppenderappender in the <PRODUCT_HOME>/repository/conf/ log4j.properties file as follows:

   log4j.appender.CARBON_LOGFILE=org.apache.log4j.RollingFileAppender

2. Add the following two properties under RollingFileAppender

   • log4j.appender.CARBON_LOGFILE.MaxFileSize=10MB 

   • log4j.appender.CARBON_LOGFILE.MaxBackupIndex=20