このコンテンツは選択した言語では利用できません。

Chapter 3. Set Up Logging

3.1. About Logging

Red Hat JBoss Data Grid provides highly configurable logging facilities for both its own internal use and for use by deployed applications. The logging subsystem is based on JBossLogManager and it supports several third party application logging frameworks in addition to JBossLogging.

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).

After a JBoss Data Grid cache is configured with operations such as eviction and expiration, logging tracks relevant activity (including errors or failures).

When set up correctly, logging provides a detailed account of what occurred in the environment and when. Logging also helps track activity that occurred just before a crash or problem in the environment. This information is useful when troubleshooting or when attempting to identify the source of a crash or error.

3.2. Supported Application Logging Frameworks

3.2.1. Supported Application Logging Frameworks

Red Hat JBoss LogManager supports the following logging frameworks:

JBoss Logging, which is included with Red Hat JBoss Data Grid 7.
Apache Commons Logging
Simple Logging Facade for Java (SLF4J)
Apache log4j
Java SE Logging (java.util.logging)

3.2.2. About JBoss Logging

JBoss Logging is the application logging framework that is included in JBoss Enterprise Application Platform 7. As a result of this inclusion, Red Hat JBoss Data Grid 7 also uses JBoss Logging.

JBoss Logging provides an easy way to add logging to an application. Add code to the application that uses the framework to send log messages in a defined format. When the application is deployed to an application server, these messages can be captured by the server and displayed and/or written to file according to the server’s configuration.

3.2.3. JBoss Logging Features

JBossLogging includes the following features:

Provides an innovative, easy to use typed logger.
Full support for internationalization and localization. Translators work with message bundles in properties files while developers can work with interfaces and annotations.
Build-time tooling to generate typed loggers for production, and runtime generation of typed loggers for development.

3.3. Boot Logging

3.3.1. Boot Logging

The boot log is the record of events that occur while the server is starting up (or booting). Red Hat JBoss Data Grid also includes a server log, which includes log entries generated after the server concludes the boot process.

3.3.2. Configure Boot Logging

Edit the logging.properties file to configure the boot log. 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.

In Red Hat JBoss Data Grid, the logging.properties file is available in the $JDG_HOME/standalone/configuration folder.

3.3.3. Default Log File Locations

The following table provides a list of log files in Red Hat JBoss Data Grid and their locations:

Table 3.1. Default Log File Locations
Log File	Location	Description
boot.log	$JDG_HOME/standalone/log/	The Server Boot Log. Contains log messages related to the start up of the server. By default this file is prepended to the server.log . This file may be created independently of the server.log by defining the `org.jboss.boot.log` property in logging.properties .
server.log	$JDG_HOME/standalone/log/	The Server Log. Contains all log messages once the server has launched.

3.4. Logging Attributes

3.4.1. 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.

Red Hat JBoss Data Grid supports all the log levels used by the supported application logging frameworks. The six most commonly used log levels are (ordered by lowest to highest severity):

TRACE
DEBUG
INFO
WARN
ERROR
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 numeric value or higher. For example a log handler with the level of WARN will only record messages of the levels WARN, ERROR and FATAL.

3.4.2. Supported Log Levels

The following table lists log levels that are supported in Red Hat JBoss Data Grid. Each entry includes the log level, its value and description. The log level values indicate each log level’s relative value to other log levels. Additionally, log levels in different frameworks may be named differently, but have a log value consistent to the provided list.

Table 3.2. Supported Log Levels
Log Level	Value	Description
FINEST	300	-
FINER	400	-
TRACE	400	Used for messages that provide detailed information about the running state of an application. `TRACE` level log messages are captured when the server runs with the `TRACE` level enabled.
DEBUG	500	Used for messages that indicate the progress of individual requests or activities of an application. `DEBUG` level log messages are captured when the server runs with the `DEBUG` level enabled.
FINE	500	-
CONFIG	700	-
INFO	800	Used for messages that indicate the overall progress of the application. Used for application start up, shut down and other major lifecycle events.
WARN	900	Used to indicate a situation that is not in error but is not considered ideal. Indicates circumstances that can lead to errors in the future.
WARNING	900	-
ERROR	1000	Used 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.
SEVERE	1000	-
FATAL	1100	Used to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss Data Grid to shut down.

3.4.3. 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 higher (with greater or equal numeric value) are captured by the log category and sent to the specified log handlers. As an example, the WARNING log level results in log values of 900, 1000 and 1100 are captured.

Log categories can optionally use the log handlers of the root logger instead of their own handlers.

3.4.4. 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.

3.4.5. About Log Handlers

Log handlers define how captured log messages are recorded by Red Hat JBoss Data Grid. The six types of log handlers configurable in JBoss Data Grid are:

Console
File
Periodic
Size
Async
Custom

Log handlers direct specified log objects to a variety of outputs (including the console or specified log files). Some log handlers used in JBoss Data Grid are wrapper log handlers, used to direct other log handlers' behavior.

Log handlers are used to direct log outputs to specific files for easier sorting or to write logs for specific intervals of time. They are primarily useful to specify the kind of logs required and where they are stored or displayed or the logging behavior in JBoss Data Grid.

3.4.6. Log Handler Types

The following table lists the different types of log handlers available in Red Hat JBoss Data Grid:

Table 3.3. Log Handler Types
Log Handler Type	Description	Use Case
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 Data Grid is run from a command line prompt.	The Console log handler is preferred when JBoss Data Grid is administered using the command line. In such a case, the messages from a Console log handler are not saved unless the operating system is configured to capture the standard out or standard error stream.
File	File log handlers are the simplest log handlers. Their primary use is to write log messages to a specified file.	File log handlers are most useful if the requirement is to store all log entries according to the time in one place.
Periodic	Periodic file handlers write log messages to a named file until a specified period of time has elapsed. Once the time period has elapsed, the specified time stamp is appended to the file name. The handler then continues to write into the newly created log file with the original name.	The Periodic file handler can be used to accumulate log messages on a weekly, daily, hourly or other basis depending on the requirements of the environment.
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.	The Size handler is best suited to an environment where the log file size must be consistent.
Async	Async log handlers are wrapper log handlers that provide asynchronous behavior for one or more other log handlers. These are useful for log handlers that have high latency or other performance problems such as writing a log file to a network file system.	The Async log handlers are best suited to an environment where high latency is a problem or when writing 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.	Custom log handlers create customized log handler types and are recommended for advanced users.

3.4.7. Selecting Log Handlers

The following are the most common uses for each of the log handler types available for Red Hat JBoss Data Grid:

The Console log handler is preferred when JBoss Data Grid is administered using the command line. In such a case, errors and log messages appear on the console window and are not saved unless separately configured to do so.
The File log handler is used to direct log entries into a specified file. This simplicity is useful if the requirement is to store all log entries according to the time in one place.
The Periodic log handler is similar to the File handler but creates files according to the specified period. As an example, this handler can be used to accumulate log messages on a weekly, daily, hourly or other basis depending on the requirements of the environment.
The Size log handler also writes log messages to a specified file, but only while the log file size is within a specified limit. Once the file size reaches the specified limit, log files are written to a new log file. This handler is best suited to an environment where the log file size must be consistent.
The Async log handler is a wrapper that forces other log handlers to operate asynchronously. This is best suited to an environment where high latency is a problem or when writing to a network file system.
The Custom log handler creates new, customized types of log handlers. This is an advanced log handler.

3.4.8. About Log Formatters

A log formatter is the configuration property of a log handler. The log formatter defines the appearance of log messages that originate from the relevant log handler. The log formatter is a string that uses the same syntax as the java.util.Formatter class.

See http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html for more information.

3.5. Logging Sample Configurations

3.5.1. Logging Sample Configuration Location

All of the sample configurations presented in this section should be placed inside the server’s configuration file, typically either standalone.xml or clustered.xml for standalone instances, or domain.xml for managed domain instances.

3.5.2. Sample XML Configuration for the Root Logger

The following procedure demonstrates a sample configuration for the root logger.

Procedure: Configure the Root Logger

The level property sets the maximum level of log message that the root logger records.

<subsystem xmlns="urn:jboss:domain:logging:3.0">
   <root-logger>
      <level name="INFO"/>

handlers is a list of log handlers that are used by the root logger.

<subsystem xmlns="urn:jboss:domain:logging:3.0">
     <root-logger>
        <level name="INFO"/>
        <handlers>
           <handler name="CONSOLE"/>
           <handler name="FILE"/>
        </handlers>
     </root-logger>
  </subsystem>

3.5.3. Sample XML Configuration for a Log Category

The following procedure demonstrates a sample configuration for a log category.

Configure a Log Category

<subsystem xmlns="urn:jboss:domain:logging:3.0">
   <logger category="com.company.accounts.rec" use-parent-handlers="true">
      <level name="WARN"/>
      <handlers>
         <handler name="accounts-rec"/>
      </handlers>
   </logger>
</subsystem>

Use the category property to specify the log category from which log messages will be captured.
The use-parent-handlers is set to "true" by default. When set to "true", this category will use the log handlers of the root logger in addition to any other assigned handlers.
Use the level property to set the maximum level of log message that the log category records.
The handlers element contains a list of log handlers.

3.5.4. Sample XML Configuration for a Console Log Handler

The following procedure demonstrates a sample configuration for a console log handler.

Configure the Console Log Handler

<subsystem xmlns="urn:jboss:domain:logging:3.0">
   <console-handler name="CONSOLE" autoflush="true">
      <level name="INFO"/>
      <encoding value="UTF-8"/>
      <target name="System.out"/>
      <filter-spec value="not(match(&quot;JBAS.*&quot;))"/>
      <formatter>
         <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
      </formatter>
   </console-handler>
</subsystem>

Add the Log Handler Identifier Information
The name property sets the unique identifier for this log handler.
When autoflush is set to "true" the log messages will be sent to the handler’s target immediately upon request.
Set the level Property
The level property sets the maximum level of log messages recorded.
Set the encoding Output
Use encoding to set the character encoding scheme to be used for the output.
Define the target Value
The target property defines the system output stream where the output of the log handler goes. This can be System.err for the system error stream, or System.out for the standard out stream.
Define the filter-spec Property
The filter-spec property is an expression value that defines a filter. The example provided defines a filter that does not match a pattern: not(match("JBAS.*")).
Specify the formatter
Use formatter to list the log formatter used by the log handler.

3.5.5. Sample XML Configuration for a File Log Handler

The following procedure demonstrates a sample configuration for a file log handler.

Configure the File Log Handler

<file-handler name="accounts-rec-trail" autoflush="true">
    <level name="INFO"/>
    <encoding value="UTF-8"/>
    <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/>
    <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
    <append value="true"/>
</file-handler>

Add the File Log Handler Identifier Information
The name property sets the unique identifier for this log handler.
When autoflush is set to "true" the log messages will be sent to the handler’s target immediately upon request.
Set the level Property
The level property sets the maximum level of log message that the root logger records.
Set the encoding Output
Use encoding to set the character encoding scheme to be used for the output.
Set the file Object
The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.
Specify the formatter
Use formatter to list the log formatter used by the log handler.
Set the append Property
When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

3.5.6. Sample XML Configuration for a Periodic Log Handler

The following procedure demonstrates a sample configuration for a periodic log handler.

Configure the Periodic Log Handler

<periodic-rotating-file-handler name="FILE" autoflush="true">
   <level name="INFO"/>
   <encoding value="UTF-8"/>
   <formatter>
      <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="server.log"/>
   <suffix value=".yyyy-MM-dd"/>
   <append value="true"/>
</periodic-rotating-file-handler>

Add the Periodic Log Handler Identifier Information
The name property sets the unique identifier for this log handler.
When autoflush is set to "true" the log messages will be sent to the handler’s target immediately upon request.
Set the level Property
The level property sets the maximum level of log message that the root logger records.
Set the encoding Output
Use encoding to set the character encoding scheme to be used for the output.
Specify the formatter
Use formatter to list the log formatter used by the log handler.
Set the file Object
The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.
Set the suffix Value
The suffix is appended to the filename of the rotated logs and is used to determine the frequency of rotation. The format of the suffix is a dot (.) followed by a date string, which is parsable by the java.text.SimpleDateFormat class. The log is rotated on the basis of the smallest time unit defined by the suffix. For example, yyyy-MM-dd will result in daily log rotation. See http://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html
Set the append Property
When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

3.5.7. Sample XML Configuration for a Size Log Handler

The following procedure demonstrates a sample configuration for a size log handler.

Configure the Size Log Handler

<size-rotating-file-handler name="accounts_debug" autoflush="false">
   <level name="DEBUG"/>
   <encoding value="UTF-8"/>
   <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
   <rotate-size value="500k"/>
   <max-backup-index value="5"/>
   <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
   <append value="true"/>
</size-rotating-file-handler>

Add the Size Log Handler Identifier Information
The name property sets the unique identifier for this log handler.
When autoflush is set to "true" the log messages will be sent to the handler’s target immediately upon request.
Set the level Property
The level property sets the maximum level of log message that the root logger records.
Set the encoding Object
Use encoding to set the character encoding scheme to be used for the output.
Set the file Object
The file object represents the file where the output of this log handler is written to. It has two configuration properties: relative-to and path.
The relative-to property is the directory where the log file is written to. JBoss Enterprise Application Platform 6 file path variables can be specified here. The jboss.server.log.dir variable points to the log/ directory of the server.
The path property is the name of the file where the log messages will be written. It is a relative path name that is appended to the value of the relative-to property to determine the complete path.
Specify the rotate-size Value
The maximum size that the log file can reach before it is rotated. A single character appended to the number indicates the size units: b for bytes, k for kilobytes, m for megabytes, g for gigabytes. For example: 50m for 50 megabytes.
Set the max-backup-index Number
The maximum number of rotated logs that are kept. When this number is reached, the oldest log is reused.
Specify the formatter
Use formatter to list the log formatter used by the log handler.
Set the append Property
When the append property is set to "true", all messages written by this handler will be appended to an existing file. If set to "false" a new file will be created each time the application server launches. Changes to append require a server reboot to take effect.

3.5.8. Sample XML Configuration for a Async Log Handler

The following procedure demonstrates a sample configuration for an async log handler

Configure the Async Log Handler

<async-handler name="Async_NFS_handlers">
   <level name="INFO"/>
   <queue-length value="512"/>
   <overflow-action value="block"/>
   <subhandlers>
      <handler name="FILE"/>
      <handler name="accounts-record"/>
   </subhandlers>
</async-handler>

The name property sets the unique identifier for this log handler.
The level property sets the maximum level of log message that the root logger records.
The queue-length defines the maximum number of log messages that will be held by this handler while waiting for sub-handlers to respond.
The overflow-action defines how this handler responds when its queue length is exceeded. This can be set to BLOCK or DISCARD. BLOCK makes the logging application wait until there is available space in the queue. This is the same behavior as an non-async log handler. DISCARD allows the logging application to continue but the log message is deleted.
The subhandlers list is the list of log handlers to which this async handler passes its log messages.