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.
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 written by the product. The logging component is not capable of capturing messages that are written directly by the JVM process, such as -verbose:gc output.
There are three primary log files for a server:
- console.log - containing the redirected standard output and standard error from the JVM process, this console output is intended for direct human consumption. The console output contains
major events and errors if we use the default consoleLogLevel configuration.
The console output also contains any messages that are written to the System.out and System.err streams if we use the default copySystemStreams configuration.
The console output always contains 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 using the LOG_DIR environment variable.
See Administer the Liberty profile from the command prompt.
- messages.log - containing all messages except
trace 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 - containing all messages that are written or captured by the product. This file is created only if we enable additional 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 server.xml. Occasionally, we might need to configure trace to diagnose a problem that occurs before server.xml is processed. In this case, the equivalent configuration properties can be specified in bootstrap.properties. If a configuration property is specified in both bootstrap.properties and server.xml, the value in bootstrap.properties is used until server.xml is processed. Then, the value in server.xml is used. Avoid specifying different values for the same configuration property in both the bootstrap.properties and server.xml.
| Attribute | Equivalent property | Description |
|---|---|---|
| logDirectory |
com.ibm.ws.logging .log.directory | This attribute sets the 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 we 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 the configuration. The logDirectory attribute might be used to dynamically update the logs to the specified directory while the server is running. |
| 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 profile 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.
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 log 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, we might have 10 message logs, 10 trace logs, and 10 exception summaries in the ffdc/ directory. By default, the value is 2.
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.log file.
The valid values are INFO, AUDIT, WARNING, ERROR, and OFF. By default, the level is AUDIT.
Note Before changing this value, consider the information in section "Unable to interact with the Liberty profile 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 the Liberty profile is ENHANCED. We can also use BASIC and ADVANCED formats as in the full profile. |
| hideMessage |
| We can use the hideMessage attribute to configure the messages 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 we use this attribute, consider the information givenn under the Unable to recognize the start of the server when the hideMessage attribute is used to suppress the messages section in the Developer Tools known restrictions topic. |
We 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 is:
- <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 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.classloader.JarClassLoader
- JarClassLoader class only.
| v6 and later 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 needed to debug problems |
| all | All events are logged. If we 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 property that we can change is consoleLogLevel. If we are concerned about the increasing size of the console.log file, we can disable the console.log file and use the message log file instead. The same data, in a different format, is written to the message log file, and we can control the size and number of message log files using the maxFileSize and maxFiles attributes. For example, the following bootstrap.properties file results in an empty console.log file and a maximum of three rolling 1 MB loggingMessages.log files. However, messages from the underlying JVM can still be written to the console.log. 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.logThe console.log file is reset when the server is restarted.
On all platforms, logs are written in the default system encoding.
-
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 platforms, all log files use the default encoding.
Parent topic: Troubleshooting tips
Tasks: