Chapter 9. Logging and tracing
Open Liberty has a unified logging component that handles messages that are written by applications and the runtime, and provides First Failure Data Capture (FFDC) capability. Logging data written by applications using System.out
, System.err
, or java.util.logging.Logger
are combined into the server logs.
There are three primary log files for a server:
-
console.log
- This file is created by theserver start
command. It contains the redirected standard output and standard error streams from the JVM process. This console output is intended for direct human consumption so lacks some information useful for automated log analysis. -
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 is suitable for automated log analysis. This file does not contain messages that are written directly by the JVM process. -
trace.log
- This file contains all messages that are written or captured by the logging component and any additional trace. This file is created only if you enable additional trace. This file does not contain messages that are written directly by the JVM process.
9.1. Logging configuration
The logging component can be controlled through the server configuration. The logging component can be fully configured in server.xml
using the logging
element. However, logging is initialized before server.xml
has been processed so configuring logging through server.xml
can result in early log entries using a different log configuration from later ones. For this reason it is also possible to provide much of the logging configuration using boostrap.properties
and in some cases using environment variables.
9.2. Example logging configuration
Some common logging configuration examples are given in the following sections.
9.2.1. Managing log file storage
The console.log
file is created by redirecting the process stdout
and stderr
to a file. As a result, Liberty is unable to offer the same level of management, like log rollover, as it offers for messages.log
. If you are concerned about the increasing size of the console.log
file, you can disable the console.log
file and use the messages.log
file instead. All the log messages sent to console.log
are written to the messages.log
file, and you can configure file rollover.
To disable the console log, and configure messages.log
to roll over three times at 100Mb, use the following configuration:
com.ibm.ws.logging.max.file.size=100 com.ibm.ws.logging.max.files=3 com.ibm.ws.logging.console.log.level=OFF com.ibm.ws.logging.copy.system.streams=false
9.2.2. JSON logging
When feeding log files into modern log aggregation and management tools it can be advantageous to have the log files stored using JSON format. This can be done in one of three ways:
Using the
bootstrap.properties
file:com.ibm.ws.logging.message.format=json com.ibm.ws.logging.message.source=message,trace,accessLog,ffdc,audit
Using environment variables:
WLP_LOGGING_MESSAGE_FORMAT=json WLP_LOGGING_MESSAGE_SOURCE=message,trace,accessLog,ffdc,audit
Using the
server.xml
file:<logging messageFormat="json" messageSource="message,trace,accessLog,ffdc,audit" />
When using
server.xml
to configure json format some log lines are written in the default non-JSON format prior toserver.xml
startup which can cause issues with some tools. For example,jq
would have trouble understanding the log files.
9.2.3. Configuring logging for a Docker image
It is common in Docker environments to disable messages.log
and instead format the console output as JSON. This can be done using environment variables:
WLP_LOGGING_MESSAGE_FORMAT=json WLP_LOGGING_MESSAGE_SOURCE= WLP_LOGGING_CONSOLE_FORMAT=json WLP_LOGGING_CONSOLE_LOGLEVEL=info WLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc,audit
This can be simply set when running the docker run
command by using -e
to set the envrionment variables:
docker run -e "WLP_LOGGING_CONSOLE_SOURCE=message,trace,accessLog,ffdc" -e "WLP_LOGGING_CONSOLE_FORMAT=json" -e "WLP_LOGGING_CONSOLE_LOGLEVEL=info" -e "WLP_LOGGING_MESSAGE_FORMAT=json" -e "WLP_LOGGING_MESSAGE_SOURCE=" open-liberty
9.2.4. Binary logging
Liberty has a high performance binary log format option that significantly reduces the overhead of writing trace files. Generally, when configuring binary logging, the console.log
is disabled for best performance. This must be enabled using bootstrap.properties
:
websphere.log.provider=binaryLogging-1.0 com.ibm.ws.logging.console.log.level=OFF com.ibm.ws.logging.copy.system.streams=false
The binaryLog
command line tool can be used to convert the binary log to a text file:
binaryLog view defaultServer
9.3. Configuration settings by source
The table below shows the equivalent server.xml
, bootstrap.properties
, and environment variable configurations along with brief descriptions. Full configuration documentation is available in the config reference for the logging element.
Server XML Attribute | bootstrap property | Env var | Description |
---|---|---|---|
hideMessage | com.ibm.ws.logging.hideMessage |
You can use this attribute to configure the messages keys that you want to hide from the | |
logDirectory | com.ibm.ws.logging.log.directory | LOG_DIR |
You can use this attribute to set a directory for all log files, excluding the |
Console Log Config | |||
consoleFormat | com.ibm.ws.logging.console.format | WLP_LOGGING_CONSOLE_FORMAT |
The required format for the console. Valid values are |
consoleLogLevel | com.ibm.ws.logging.console.log.level | WLP_LOGGING_CONSOLE_LOGLEVEL | This filter controls the granularity of messages that go to the console. The valid values are INFO, AUDIT, WARNING, ERROR, and OFF. The default is AUDIT. If using with the Eclipse developer tools this must be set to the default. |
consoleSource | com.ibm.ws.logging.console.source | WLP_LOGGING_CONSOLE_SOURCE |
The list of comma-separated sources that route to the console. This property applies only when |
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 process | |
Message Log Config | |||
com.ibm.ws.logging.newLogsOnStart |
If set to true when Liberty starts, any existing | ||
isoDateFormat | com.ibm.ws.logging.isoDateFormat | Specifies whether to use ISO-8601 formatted dates in log files. The default value is false.
If set to true, the ISO-8601 format is used in the
If you specify a value of | |
maxFiles | com.ibm.ws.logging.max.files |
How many of each of the logs files are kept. This setting also applies to the number of exception summary logs for FFDC. So if this number is | |
maxFileSize | com.ibm.ws.logging.max.file.size |
The maximum size (in MB) that a log file can reach before it is rolled. Setting the value to | |
messageFileName | com.ibm.ws.logging.message.file.name |
The message log has a default name of | |
messageFormat | com.ibm.ws.logging.message.format | WLP_LOGGING_MESSAGE_FORMAT |
The required format for the |
messageSource | com.ibm.ws.logging.message.source | WLP_LOGGING_MESSAGE_SOURCE |
The list of comma-separated sources that route to the |
Trace Config | |||
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 | ||
traceFileName | com.ibm.ws.logging.trace.file.name |
The | |
traceFormat | com.ibm.ws.logging.trace.format |
This attribute controls the format of the trace log. The default format for Liberty is | |
traceSpecification | com.ibm.ws.logging.trace.specification | The trace string is used to selectively enable trace. The format of the log detail level specification: component = level
where A component can be a logger name, trace group or class name. An asterisk * acts as a wildcard to match multiple components based on a prefix. For example:
|