Logging and Trace

The product has a unified logging component that handles messages that are written by the product and provides First Failure Data Capture (FFDC) services.

Open Liberty In version 20.0.0.7 and later, see the Open Liberty website for Liberty logging documentation.

Additionally, the logging component captures messages that are written to System.out, System.err, java.util.logging, and OSGi logging. The logging component unifies the handling of these messages with other messages that are written by the product. The logging component does not capture or control the destination of messages that are written directly by the JVM process, such as -verbose:gc output. These messages are routed to the file system according to the active JVM settings

A server has the following three primary log files:
  1. console.log - This file contains the redirected standard output and standard error streams from the JVM process. This console output is intended for direct human consumption. The logging component writes major events to the standard output stream and errors to the standard error stream if you use the default consoleLogLevel configuration. If you use the default copySystemStreams configuration, the logging component also copies any messages that are written to the System.out stream to the standard output stream and any messages that are written to the System.err stream to the standard error stream. The standard output and standard error streams always contain messages that are written directly by the JVM process, such as -verbose:gc output. This file is created only if the server start command is used, and its location can be altered only by using the LOG_DIR environment variable. For more information, see Administering Liberty from the command line.
  2. messages.log - This file contains all messages that are written or captured by the logging component. All messages that are written to this file contain additional information such as the message time stamp and the ID of the thread that wrote the message. This file does not contain messages that are written directly by the JVM process.
  3. trace.log - This file is created only if you enable trace. It contains all the content of messages.log file plus any enabled trace. This file does not contain messages that are written directly by the JVM process.

Logging configuration

The logging component can be controlled through the server configuration. The primary location for the logging configuration is in the server.xml file. Occasionally, you might need to configure trace to diagnose a problem that occurs before the server.xml file is processed. In this case, the equivalent configuration properties can be specified in the bootstrap.properties file. If a configuration property is specified in both the bootstrap.properties file and the server.xml file, the value in bootstrap.properties is used until the server.xml file is processed. Then, the value in the server.xml file is used. Avoid specifying different values for the same configuration property in both the bootstrap.properties and the server.xml file.
Table 1. Logging properties for the Liberty component. Column 1 contains attributes that can be set in the server.xml file. Column 2 contains equivalent properties that can be used in the bootstrap.properties file. Column 3 provides a description of each logging property.
Attribute Equivalent property Description
logDirectory
com.ibm.ws.logging
.log.directory
You can use this attribute to set a directory for all log files, excluding the console.log file, but including FFDC. By default, logDirectory is set to the LOG_DIR environment variable. The default LOG_DIR environment variable path is WLP_OUTPUT_DIR/serverName/logs.
Avoid trouble: Use the LOG_DIR environment variable or com.ibm.ws.logging.log.directory property rather than the logDirectory attribute to configure the directory in which you want all the messages to be written. Otherwise, a few messages are written initially in the logs directory by default, and then the remaining messages are written to the specified directory based on your configuration. The logDirectory attribute might be used to dynamically update the logs to the specified directory while the server is running.
isoDateFormat
com.ibm.ws.logging.isoDateFormat
The date and time use the locale format or the ISO-8601 format. You can specify true or false for the value of the attribute or the value of the equivalent property. The default value is false.

If you specify a value of true, the ISO-8601 format is used in the messages.log file, the trace.log file, and the FFDC logs. The format is yyyy-MM-dd'T'HH:mm:ss.SSSZ.

If you specify a value of false, the date and time are formatted according to the default locale set in the system. If the default locale is not found, the format is dd/MMM/yyyy HH:mm:ss:SSS z.

maxFileSize
com.ibm.ws.logging
.max.file.size
The maximum size (in MB) that a log file can reach before it is rolled. The Liberty runtime does only size-based log rolling. To disable this attribute, set the value to 0. The maximum file size is approximate. By default, the value is 20.
Note: maxFileSize does not apply to the console.log file.
maxFiles
com.ibm.ws.logging
.max.files
If an enforced maximum file size exists, this setting is used to determine how many of each of the logs files are kept. This setting also applies to the number of exception logs that summarize exceptions that occurred on any particular day. So if this number is 10, you might have 10 message logs, 10 trace logs, and 10 exception summaries in the ffdc/ directory. By default, the value is 2.
Note: maxFiles does not apply to the console.log file.
consoleLogLevel
com.ibm.ws.logging
.console.log.level
This filter controls the granularity of messages that go to the console. The valid values are INFO, AUDIT, WARNING, ERROR, and OFF. By default, the consoleLogLevel is set to the WLP_LOGGING_CONSOLE_LOGLEVEL environment variable (if set) or AUDIT.
For distributed platformsNote: Before you change this value, consider the information in section "Unable to interact with the Liberty server after modifying the console log level settings" in the topic Developer Tools known restrictions.
copySystemStreams
com.ibm.ws.logging.
copy.system.streams
If true, messages that are written to the System.out and System.err streams are copied to console.log. If false, those messages are written to configured logs such as messages.log or trace.log, but they are not copied to console.log. The default value is true.
messageFileName
com.ibm.ws.logging
.message.file.name
The message log has a default name of messages.log. This file always exists, and contains INFO and other (AUDIT, WARNING, ERROR, FAILURE) messages in addition to System.out and System.err. This log also contains time stamps and the issuing thread ID. If the log file is rolled over, the names of earlier log files have the format messages_timestamp.log
suppressSensitiveTrace   The server trace can expose sensitive data when it traces untyped data, such as bytes received over a network connection. This attribute, when set to true, prevents potentially sensitive information from being exposed in log and trace files. The default value is false.
traceFileName
com.ibm.ws.logging
.trace.file.name
The trace.log file is only created if additional or detailed trace is enabled. stdout is recognized as a special value, and causes trace to be directed to the original standard out stream.
traceSpecification
com.ibm.ws.logging
.trace.specification
The trace string is used to selectively enable trace. The default is *=info.
traceFormat
com.ibm.ws.logging
.trace.format
This attribute controls the format of the trace log. The default format for Liberty is ENHANCED. You can also use BASIC and ADVANCED formats as in the WebSphere Application Server traditional.
hideMessage
com.ibm.ws.logging.hideMessage
You can use this attribute to configure the messages that you want to hide from the console.log and message.log files. If the messages are configured to be hidden, then they are redirected to the trace.log file.
For distributed platformsNote: Before you use this attribute, consider the information that is given under the Unable to recognize the start of the server when the hideMessage attribute is used to suppress the message section in the Developer Tools known restrictions topic.
messageSource
com.ibm.ws.logging.message.source
The list of comma-separated sources that route to the messages.log file. This property applies only when messageFormat=json. Valid values are message, trace, accessLog, ffdc, and audit. By default, messageSource is set to the environment variable WLP_LOGGING_MESSAGE_SOURCE (if set), or message.
Note: To use the audit source, enable the Liberty audit feature.
messageFormat
com.ibm.ws.logging.message.format
The required format for the messages.log file. Valid values are basic or json format. By default, messageFormat is set to the environment variable WLP_LOGGING_MESSAGE_FORMAT (if set) or basic.
consoleSource
com.ibm.ws.logging.console.source
The list of comma-separated sources that route to the console. This property applies only when consoleFormat=json. Valid values are message, trace, accessLog, ffdc, and audit. By default, consoleSource is set to the environment variable WLP_LOGGING_CONSOLE_SOURCE (if set), or message.
Note: To use the audit source, enable the Liberty audit feature.
consoleFormat
com.ibm.ws.logging.console.format
The required format for the console. Valid values are basic or json format. By default, consoleFormat is set to the environment variable WLP_LOGGING_CONSOLE_FORMAT (if set) or basic.
 
com.ibm.ws.logging.newLogsOnStart
By default, when Liberty restarts, any existing messages.log or trace.log files are rolled over and logging writes to a new messages.log or trace.log file. Alternatively, specify
com.ibm.ws.logging.newLogsOnStart=false
in bootstrap.properties to disable automatic rollover of existing messages.log or trace.log files on restart.
You can set logging properties in the server configuration file by selecting Logging and Tracing in the Server Configuration view in the developer tools. Or by adding a logging element to the server configuration file as follows:
<logging traceSpecification="*=audit:com.myco.mypackage.*=finest"/>
The format of the log detail level specification:
<component> = <level>

where <component> is the component for which to set a log detail level, and <level> is one of the valid logger levels (off, fatal, severe, warning, audit, info, config, detail, fine, finer, finest, all). Separate multiple log detail level specifications with colons (:).

Attention: For a given logger, the level is determined by the most specific trace specification that applies to that logger.
Components correspond to Java™ packages and classes, or to collections of Java packages. Use an asterisk (*) as a wildcard to indicate components that include all the classes in all the packages that are contained by the specified component. For example:
*
Specifies all traceable code that is running in the application server, including the product system code and customer code.
com.ibm.ws.*
Specifies all classes with the package name beginning with com.ibm.ws.
com.ibm.ws.classloading.AppClassLoader
Specifies the AppClassLoader class only.
Table 2. Valid logging levels. The following table lists the valid levels for Liberty application servers.
Logging level Content / Significance
off Logging is turned off.
fatal Task cannot continue and component, application, and server cannot function.
severe Task cannot continue but component, application, and server can still function. This level can also indicate an impending unrecoverable error.
warning Potential error or impending error. This level can also indicate a progressive failure (for example, the potential leaking of resources).
audit Significant event that affects server state or resources
info General information that outlines overall task progress
config Configuration change or status
detail General information that details subtask progress
fine Trace information - General trace + method entry, exit, and return values
finer Trace information - Detailed trace
finest Trace information - A more detailed trace that includes all the detail that is needed to debug problems
all All events are logged. If you create custom levels, all includes those levels, and can provide a more detailed trace than finest.

The console.log file does not have the same level of management as other log files. The only properties that you can change are consoleLogLevel, consoleSource, and consoleFormat. If you are concerned about the increasing size of the console.log file, you can set the console.log file to OFF and use the message log file instead. All the server logging messages that are sent to the console log file are written to the message log file, and you can control the size and number of message log files by using the maxFileSize and maxFiles attributes. However, when you set the console log level to OFF, messages from the underlying JVM and any messages that are written to the native standard out or standard error streams are still written to the console.log file.

For example, the following bootstrap.properties file results in a console.log file with no server logging messages and a maximum of three rolling 1 MB loggingMessages.log files. Settings in the bootstrap.properties file take effect before the message log file is created, so the message log file is initially created as loggingMessages.log and not the default messages.log.
   com.ibm.ws.logging.max.file.size=1
   com.ibm.ws.logging.max.files=3
   com.ibm.ws.logging.console.log.level=OFF
   com.ibm.ws.logging.message.file.name=loggingMessages.log
The console.log file is reset when the server is restarted.
Note: On all operating systems, logs are written in the default system encoding.
  • For Windows platformsOn Windows systems, there are two types of encoding: OEM code page, which is used for console output, and ANSI code page, which is used to read and write files. The console.log file uses the OEM code page, and all other logs use the ANSI code page.
  • For distributed platformsOn all other operating systems, all log files use the default encoding.
The following samples illustrate example configurations for JSON logging:
  • To set messages.log to JSON format in the server.xml file.
    <logging messageFormat="json" messageSource="message,trace,accessLog,ffdc,audit" />
  • To set the console to JSON format in the server.env file.
    WLP_LOGGING_CONSOLE_FORMAT=json
    WLP_LOGGING_CONSOLE_LOGLEVEL=info
    WLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc,audit
  • To set the console to JSON format in the bootstrap.properties file.
    com.ibm.ws.logging.console.format=json
    com.ibm.ws.logging.console.log.level=info
    com.ibm.ws.logging.console.source=message,trace,accessLog,ffdc,audit
  • To set the console to JSON format when running a Liberty Docker image:
    docker run -e "WLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc" -e 
    "WLP_LOGGING_CONSOLE_FORMAT=json" -e "WLP_LOGGING_CONSOLE_LOGLEVEL=info" websphere-liberty