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.

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:

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.
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.
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.

Tip: You can use the user.timezone property to set the time zone for your application environments. Set the user.timezone property in the jvm.properties file. The updated time zone information is displayed in the messages.log file and the trace.log file. The following example shows how to set the time zone.

-Duser.timezone=time_zone_code

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.

Tip: For the latest logging property descriptions, see the Open Liberty logging documentation or the WebSphere Liberty server configuration documentation for Logging (logging). The latest information might not be in Table 1.

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
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`.
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. Note: 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.
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.
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.
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. Note: 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.
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.
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.
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.
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.
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
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`.
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.
rolloverInterval	`com.ibm.ws.logging.rollover.interval`	The time interval in between log rollovers, in minutes if a unit of time is not specified. Specify a positive integer followed by a unit of time, which can be days (`d`), hours (`h`), or minutes (`m`). For example, specify 5 hours as `5h` and 30 minutes as `30m`. You can include multiple values in a single entry. For example, `1d5h` is equivalent to 1 day and 5 hours. The default value is `-1`. The bootstrap property default is the `WLP_LOGGING_ROLLOVER_INTERVAL` environment variable, if rolloverStartTime is specified. If rolloverStartTime is specified, the default value of rolloverInterval is 1 day. If both rolloverInterval and rolloverStartTime are unspecified, time-based log rollover is disabled. Note: rolloverInterval does not apply to the console.log file.
rolloverStartTime	`com.ibm.ws.logging.rollover.start.time`	The scheduled time of day for logs to first roll over. The rollover interval duration begins at rollover start time. Valid values follow a 24-hour ISO-8601 datetime format of HH:MM, where `00:00` represents midnight. Padding zeros are required. The bootstrap property default is the `WLP_LOGGING_ROLLOVER_START_TIME` environment variable, if rolloverInterval is specified. rolloverStartTime has no default value unless rolloverInterval is specified. If rolloverInterval is specified, the default value of rolloverStartTime is `00:00`, midnight at start of day. If both rolloverInterval and rolloverStartTime are unspecified, time-based log rollover is disabled. Note: rolloverStartTime does not apply to the console.log file.
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.
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.
traceSpecification	`com.ibm.ws.logging.trace.specification`	The trace string is used to selectively enable trace. The default is *=info.

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.

On z/OS® systems, the console.log file uses the default code page, and all other log files uses ISO8859-1 encoding and are tagged as text files with that encoding. If the z/OS UNIX System Services (USS) automatic code page conversion feature is active, you can use standard editors and text utilities to view the log files that are encoded with ISO8859-1.
On 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.
On 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