Chapter 11. The Logging Subsystem
11.1. Introduction
11.1.1. Overview of Logging
JBoss Enterprise Application Platform 6 provides highly configurable logging facilities for both its own internal use and for use by deployed applications. The logging subsystem is based on JBoss LogManager and it supports several third party application logging frameworks in addition to JBoss Logging.
The logging subsystem is configured using a system of log categories and log handlers. Log categories define what messages to capture, and log handlers define how to deal with those messages (write to disk, send to console etc).
All of this configuration can be performed in the Management Console or by using the CLI tool.
11.1.2. Application Logging Frameworks Supported By JBoss LogManager
JBoss LogManager supports the following logging frameworks:
- JBoss Logging - included with JBoss Enterprise Application Platform 6
- Apache Commons Logging - http://commons.apache.org/logging/
- Simple Logging Facade for Java (SLF4J) - http://www.slf4j.org/
- Apache log4j - http://logging.apache.org/log4j/1.2/
- Java SE Logging (java.util.logging) - http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html
11.1.3. Configure Boot Logging
The boot log is the record of events that occur while the server is starting up (or "booting").
The boot log can be configured by editing the
logging.properties
file. This file is a standard Java properties file and can be edited in a text editor. Each line in the file has the format of property=value
.
Depending on whether you run the JBoss Enterprise Application Platform as a managed domain or standalone server, the full path to the
logging.properties
file is either EAP_HOME/domain/configuration/logging.properties
or EAP_HOME/standalone/configuration/logging.properties
.
11.1.4. Default Log File Locations
These are the log files that get created for the default logging configurations. The default configuration writes the server log files using periodic log handlers
Table 11.1. Default Log Files for a standalone server
Log File | Description |
---|---|
EAP_HOME/standalone/log/boot.log |
The server boot log. Contains log messages related to the startup of the server.
|
EAP_HOME/standalone/log/server.log |
The Server Log. Contains all log messages once the server has launched.
|
Table 11.2. Default Log Files for a managed domain
Log File | Description |
---|---|
EAP_HOME/domain/log/host-controller/boot.log |
Host Controller boot log.Contains log messages related to the startup of the host controller.
|
EAP_HOME/domain/log/process-controller/boot.log |
Process controller boot log. Contains log messages related to the startup of the process controller.
|
EAP_HOME/domain/servers/SERVERNAME/log/boot.log |
Server Boot log for the named server. Contains log messages related to the startup of the specified server.
|
EAP_HOME/domain/servers/SERVERNAME/log/server.log |
The server log for the named server. Contains all log messages for that server once it has launched.
|
11.1.5. About Log Levels
Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message. The level of a given log message is specified by the developer using the appropriate methods of their chosen logging framework to send the message.
JBoss Enterprise Application Platform 6 supports all the log levels used by the supported application logging frameworks. The most commonly used six log levels are (in order of lowest to highest):
TRACE
, DEBUG
, INFO
, WARN
, ERROR
and FATAL
.
Log levels are used by log categories and handlers to limit the messages they are responsible for. Each log level has an assigned numeric value which indicates its order relative to other log levels. Log categories and handlers are assigned a log level and they only process log messages of that level or higher. For example a log handler with the level of
WARN
will only record messages of the levels WARN
, ERROR
and FATAL
.
11.1.6. Supported Log Levels
Table 11.3. Supported Log Levels
Log Level | Value | Description |
---|---|---|
FINEST | 300 |
-
|
FINER | 400 |
-
|
TRACE | 400 |
Use for messages that provide detailed information about the running state of an application. Log messages of
TRACE are usually only captured when debugging an application.
|
DEBUG | 500 |
Use for messages that indicate the progress individual requests or activities of an application. Log messages of
DEBUG are usually only captured when debugging an application.
|
FINE | 500 |
-
|
CONFIG | 700 |
-
|
INFO | 800 |
Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.
|
WARN | 900 |
Use to indicate a situation that is not in error but is not considered ideal. May indicate circumstances that may lead to errors in the future.
|
WARNING | 900 |
-
|
ERROR | 1000 |
Use to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.
|
FATAL | 1100 |
Use to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss Enterprise Application Platform 6 to shutdown.
|
11.1.7. About Log Categories
Log categories define a set of log messages to capture and one or more log handlers which will process the messages.
The log messages to capture are defined by their Java package of origin and log level. Messages from classes in that package and of that log level or lower are captured by the log category and sent to the specified log handlers.
Log categories can optionally use the log handlers of the root logger instead of their own handlers.
11.1.8. About the Root Logger
The root logger captures all log messages sent to the server (of a specified level) that are not captured by a log category. These messages are then sent to one or more log handlers.
By default the root logger is configured to use a console and a periodic log handler. The periodic log handler is configured to write to the file
server.log
. This file is sometimes referred to as the server log.
11.1.9. About Log Handlers
Log handlers define how captured log messages are recorded by JBoss Enterprise Application Platform. There are six types of log handler that can be configured:
Console
, File
, Periodic
, Size
, Async
and Custom
.
11.1.10. Types of Log Handlers
- Console
- Console log handlers write log messages to either the host operating system’s standard out (stdout) or standard error (stderr) stream. These messages are displayed when JBoss Enterprise Application Platform 6 is run from a command line prompt. The messages from a Console log handler are not saved unless the operating system is configured to captured the standard out or standard error stream.
- File
- File log handlers are the simplest log handlers that write log messages to a specified file.
- Periodic
- Periodic file handlers write log messages to a named file until a specified period of time has elapsed. Once the time period has past then the file is renamed by appending the specified timestamp and the handler continues to write into a newly created log file with the original name.
- Size
- Size log handlers write log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric prefix and the handler continues to write into a newly created log file with the original name. Each size log handler must specify the maximum number of files to be kept in this fashion.
- Async
- Async log handlers are wrapper log handlers that provide asynchronous behaviour for one or more other log handlers. These are useful for log handlers that may have high latency or other performance problems such as writing a log file to a network file system.
- Custom
- Custom log handlers enable to you to configure new types of log handlers that have been implemented. A custom handler must be implemented as a Java class that extends
java.util.logging.Handler
and be contained in a module.
11.1.11. About Log Formatters
A log formatter is the configuration property of a log handler that defines the appearance of log messages from that handler. It is a string that uses a syntax based on
java.util.Formatter
class.
For example the log formatter string from the default configuration,
%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n
, creates log messages that look like:
15:53:26,546 INFO [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990
11.1.12. Log Formatter Syntax
Table 11.4. Log Formatter Syntax
Symbol | Description |
---|---|
%c | The category of the logging event |
%p | The level of the log entry (info/debug/etc) |
%P | The localized level of the log entry |
%d | The current date/time (yyyy-MM-dd HH:mm:ss,SSS form) |
%r | The relative time (milliseconds since the log was initialised) |
%z | The time zone |
%k | A log resource key (used for localization of log messages) |
%m | The log message (including exception trace) |
%s | The simple log message (no exception trace) |
%e | The exception stack trace (no extended module information) |
%E | The exception stack trace (with extended module information) |
%t | The name of the current thread |
%n | A newline character |
%C | The class of the code calling the log method (slow) |
%F | The filename of the class calling the log method (slow) |
%l | The source location of the code calling the log method (slow) |
%L | The line number of the code calling the log method (slow) |
%M | The method of the code calling the log method (slow) |
%x | The Log4J Nested Diagnostic Context |
%X | The Log4J Message Diagnostic Context |
%% | A literal percent character (escaping) |