Red Hat JBoss Enterprise Application Platform Administration I

Developers use logging extensively in source code as a means of communicating the status of the application based on certain events. Not all log events are a sign of application issues. Log events can communicate that something worked successfully.

In Red Hat JBoss Enterprise Application Platform (JBoss EAP), the following filters are applicable to log events:

The logger category defines the source of the event. It is the standard convention to use a fully qualified Java class name as the logger category, but the category name can be any string that makes sense to the developer.

The logger level defines the severity of the event. For example, a log level of FATAL might indicate an error from which the application could not recover.

A logger is defined by using the <logger> tag within the logging subsystem configuration the format is as follows:

<logger category="`java_class_and/or_package_name`">
    <level name="log_level"/>
</logger>

Logger categories follow a hierarchical rule. If a category is defined for a certain package, then all classes in that package and any subpackages are included in the category. For example, the following logger sets the log level to WARN for any Java class in the org.jboss.jca package:

<logger category="org.jboss.jca">
    <level name="WARN"/>
</logger>

The following management CLI command creates an equivalent logger.

/profile=default/subsystem=logging/logger=org.jboss.jca:add(\
    category=org.jboss.jca,level=WARN)

A category is as specific as desired, including for a single class. For example, the following logger sets the log level to DEBUG for just the org.jboss.jca.core.naming.JndiBinder class:

<logger category="org.jboss.jca.core.naming.JndiBinder">
    <level name="DEBUG"/>
</logger>

The following management CLI command creates an equivalent logger.

/profile=default/subsystem=logging/logger=org.jboss.jca.core.naming.JndiBinder:\
    add(category=org.jboss.jca.core.naming.JndiBinder,level=DEBUG)

When using the JBoss EAP management console, loggers are configured and managed within the Configuration → Subsytems → Logging section. Click Configuration, then click View to navigate to the log handler configuration page.

Figure 7.2: Log handler configuration page

A logger can also specify which handler to use.

<logger category="org.jboss.as"> 
    <level name="INFO"/> 
    <handlers>
        <handler name="FILE"/> 
    </handlers>
</logger>

Loggers are organized in a tree-like hierarchy based on category. A dot (.) separates hierarchy levels, following Java package naming rules. If a logger is a subpackage of another logger, then it becomes a child of that logger. For example, com.mycompany.onlinestore is a child logger of com.mycompany.

At runtime, applications and JBoss EAP components always instantiate the specific child logger they require. Following the previous example, an application Java class called com.mycompany.onlinestore.CheckOut creates a logger by using its name as the category.

If a logger is not explicitly configured, then its parent logger configuration is used. If the parent logger is also not configured, then the grandparent configuration is used, and so on. The root logger serves as the parent of all loggers and provides default configuration.

Because settings from ancestor loggers are inherited, only configure as specific of a logger as necessary.

In the following example configuration, generic JBoss EAP log events are filtered at a WARN level, but the JBeret subsystem gets a lower level of INFO, so it has more events sent:

<logger category="org.wildfly">
    <level name="WARN"/>
</logger>
<logger category="org.wildfly.jberet">
    <level name="INFO"/>
</logger>

A logger always inherits all parent handlers unless this behavior is turned off by changing the use-parent-handlers attribute of the logger.

For example, the following example sends all events from the online store application to the handler named STORE_APP_HANDLER and to handlers configured by the root logger:

<logger category="com.mycompany.onlinestore">
    <level name="INFO"/>
    <handlers>
        <handler name="STORE_APP_HANDLER"/>
    </handlers>
</logger>

Log events generated by the application classes might go to multiple handlers even if the logger configuration names only a single handler.

If the intent is to have all log events sent only to the STORE_APP_HANDLER handler and not to the handlers configured by the root logger, then set the use-parent-handlers attribute to false:

<logger category="com.mycompany.onlinestore" use-parent-handlers="false">
    <level name="INFO"/>
    <handlers>
        <handler name="STORE_APP_HANDLER"/>
    </handlers>
</logger>

The root logger's settings are associated with every log event that is not specifically associated with a child logger. Because the root logger resides at the top of the logger hierarchy, the settings of the root logger are inherited by all other loggers, unless a logger overrides a setting.

The following excerpt shows the root logger configuration in the JBoss EAP server configuration files:

<root-logger>
    <level name="INFO"/>
    <handlers>
        <handler name="CONSOLE"/>
        <handler name="FILE"/>
    </handlers>
</root-logger>

Notice that INFO is the default log level of all events. These events are logged at the console and with the FILE handler, which is the server.log file.

The root logger itself is configurable. For example, on a production server, logs are set to the ERROR level, but it should disable logging to the console. The following configuration satisfies such requirements:

<root-logger>
    <level name="ERROR"/>
    <handlers>
        <handler name="FILE"/>
    </handlers>
</root-logger>

The logging subsystem has several management CLI operations pertaining to the root logger. The following commands are available in the /subsystem=logging/root-logger=ROOT: namespace of the management CLI:

For example, the following command changes the root logger level to ERROR in the default profile:

/profile=default/subsystem=logging/root-logger=ROOT:change-root-log-level(level=ERROR)

Of course, level and handler attributes are directly modifiable without resorting to these specialized commands. The commands make some modifications simpler, such as adding or removing a single handler.

Configure and manage the root logger by using the same management page as regular log handlers.

Each log event is tagged with a specific level. Log levels are arranged in decreasing order of verbosity. In other words, lower levels in the priority ordering result in more verbose logs.

From higher to lower, the following are the log level priorities:

In general, production servers should only have WARN levels and above enabled to avoid potential I/O bottlenecks. Whenever an issue is to be investigated, temporarily set the log levels to a lower level, collect and observe log messages, and then reset to the ERROR or WARN level when finished troubleshooting. If possible, add category loggers corresponding to the application package namespace or the subsystem of JBoss EAP under investigation rather than change the root logger level.