Logging is one of the most crucial tasks performed by an application server. Gathering and analyzing log files is an important task for a Red Hat JBoss Enterprise Application Platform (JBoss EAP) administrator to help diagnose, troubleshoot and analyze issues in production. Sometimes, there might also be a business requirement to store logging information from applications to meet regulatory and compliance related laws.

Consistent with the modular design of JBoss EAP, logging is handled by a subsystem. The logging configuration is represented by the logging subsystem, and is configured in the domain.xml in managed domain mode and standalone.xml in a standalone server.

The JBoss EAP logging subsystem has three main components:

A handler is activated only if one or more loggers reference it. Loggers can reference more than one handler or none at all. The root logger captures all log messages of the specified log level, that are not captured by a log category.

The default log level is INFO, and the following two handlers are enabled:

Earlier versions of JBoss EAP had a single log directory. JBoss EAP 7 has multiple log file locations depending on whether it is running as a standalone server or managed domain mode.

For example, if JBoss EAP is running as a standalone server, then the log files are found in the standalone/log directory within the base directory.

The standalone/log directory contains two log files:

If JBoss EAP is running in managed domain mode, then logging occurs in multiple locations relative to the base directory:

Notice that each server on a host has its own directory for log files. For example, if a host has a server on it named dev-server-one, then the log file for that server is domain/servers/dev-server-one/log/server.log

The <server-name>/log/server.log is analogous to server.log the one from a standalone server, and is a good place to start looking for issues on a server. This file is appended to each time the server starts, so it is a good practice to rotate server.log on an hourly or daily basis, or when the file reaches a certain size.

JBoss EAP comes with the six following built-in handlers:

Handlers are configured within the logging subsystem section of the server configuration file. For example, the standalone.xml file and most of the profiles in the domain.xml file come preconfigured with a <console-handler> definition.

The management CLI definition looks like the following:

[standalone@localhost:9990]$ /subsystem=logging/console-handler=CONSOLE:read-resource
{
  "outcome" => "success",
  "result" => {
    "autoflush" => true,
    "enabled" => true,
    "encoding" => undefined,
    "filter" => undefined,
    "filter-spec" => undefined,
    "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n",
    "level" => "INFO",
    "name" => "CONSOLE",
    "named-formatter" => "COLOR-PATTERN",
    "target" => "System.out"
  }
}

The corresponding XML looks like:

<subsystem xmlns="urn:jboss:domain:logging:8.0">
    <console-handler name="CONSOLE"> 
        <level name="INFO"/> 
        <formatter> 
            <named-formatter name="COLOR-PATTERN"/> 
        </formatter>
    </console-handler>
    ...output omitted...
</subsystem>

Use the periodic-rotating-file-handler to automatically rotate the log files based on a certain amount of elapsed time. For example, the default FILE handler is set to roll over the server.log file every 24 hours. The definition of the handler is as follows:

<periodic-rotating-file-handler name="FILE" autoflush="true"> 
    <formatter>
        <named-formatter name="PATTERN"/>
    </formatter>
    <file relative-to="jboss.server.log.dir" path="server.log"/> 
    <suffix value=".yyyy-MM-dd"/> 
    <append value="true"/>
</periodic-rotating-file-handler>

The suffix value is a date-time format, and the pattern specifies how often the log file rotates. For example, if a log file should rotate every hour, set the suffix to yyyy-MM-dd.HH.

Similarly, monthly rotation is set by using the suffix yyyy-MM.

The periodic-rotating-file-handler is managed by using the management console in the Configuration → Subsystems → Logging section.

The management CLI can also define a new handler by using the add operation. For example, the following CLI command adds a new periodic-rotating-file-handler called MY_HANDLER:

/profile=default/subsystem=logging/periodic-rotating-file-handler=MY_HANDLER:add(
      autoflush=true,
      append=true,
      named-formatter=PATTERN,
      file={
            path=mylog.log,
            relative-to=jboss.server.log.dir
      },
      level=INFO,
      suffix=.yyyy-DD-mm-HH
)

Use the size-rotating-file-handler to automatically rotate log files based on the size of the log file. This handler is useful in scenarios where the number of log files generated within a period is too large. The handler is configured to rotate the log file after a set rotate-size value.

The following is a sample definition of this handler:

<size-rotating-file-handler name="FILE_BY_SIZE"> 
   <level name="INFO"/> 
   <formatter>
        <named-formatter name="PATTERN"/> 
    </formatter>
   <file relative-to="jboss.server.log.dir" path="production-server.log"/>  
   <rotate-size value="1m"/> 
   <max-backup-index value="3"/> 
</size-rotating-file-handler>

Size rotating file handlers can be defined in the management console in the Configuration → Subsystems → Logging → Configuration → View section.

The async-handler provides a simple way to accomplish asynchronous logging, but it does not write log events to a file or the console. Instead, the async-handler sits in front of an existing handler and adds the asynchronous behavior. Use the <subhandler> element to define which handler the asynchronous behavior is being added to.

The following is an example definition for an asynchronous handler:

<async-handler name="ASYNC"> 
    <level name="INFO"/> 
    <queue-length value="1024"/> 
    <overflow-action value="BLOCK"/> 
    <subhandlers>
        <handler name="FILE"/> 
    </subhandlers>
</async-handler>

Adding the asynchronous behavior to logging can improve performance on high-volume servers. If a request is made to the server that causes a log event to occur, a response can be sent back to the client without making the client wait for the actual writing of the log event to the handler.

The syslog-handler provides a simple way to send events to a remote logging server. This allows multiple applications to send their log messages to a central SYSLOG server. On a central server, logs can be stored, analyzed, and archived simultaneously to simplify backups.

The following is an example definition of the syslog-handler handler:

<syslog-handler name="SYSLOG"> 
    <level name="INFO"/> 
    <server-address value="172.25.2.9"/> 
    <hostname value="workstation.lab.example.com"/> 
    <port value="514"/> 
    <app-name value="MY_APP"/>
</syslog-handler>

This handler formats the log message according to the RFC5424 (SYSLOG protocol) specification. Any remote server that complies with this specification can accept these log messages. The log messages on the remote server are parsed and filtered based on this attribute.