Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 12. Logging with JBoss EAP

JBoss EAP 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 supports several third-party application logging frameworks in addition to JBoss Logging.

12.1. About Server Logging

12.1.1. Server Logging

By default, all JBoss EAP log entries are written to the server.log file. The location of this file depends on your operating mode.

  • Standalone server: EAP_HOME/standalone/log/server.log
  • Managed domain: EAP_HOME/domain/servers/SERVER_NAME/log/server.log

This file is often referred to as the server log. For more information, see the Root Logger section.

12.1.2. Bootup Logging

During bootup, JBoss EAP logs information about the Java environment and the startup of each service. This log can be useful when troubleshooting. By default, all log entries are written to the server log.

Bootup logging configuration is specified in the logging.properties configuration file, which is active until the JBoss EAP logging subsystem is started and takes over. The location of this file depends on your operating mode.

  • Standalone server: EAP_HOME/standalone/configuration/logging.properties
  • Managed domain:

    There is a logging.properties file for the domain controller and for each server.

    • Domain controller: EAP_HOME/domain/configuration/logging.properties
    • Server: EAP_HOME/domain/servers/SERVER_NAME/data/logging.properties
Warning

It is recommended that you do not directly edit the logging.properties file unless you know of a specific use case that requires it. Before doing so, it is recommended that you open a support case from the Red Hat Customer Portal.

Changes made manually to the logging.properties file are overwritten on startup.

12.1.2.1. View Bootup Errors

When troubleshooting JBoss EAP, checking for errors that occurred during bootup should be one of the first steps taken. You can then use the information provided to diagnose and resolve their causes. Open a support case for assistance in troubleshooting bootup errors.

There are two methods of viewing bootup errors, each with its advantages. You can examine the server.log file or read the boot errors using the read-boot-errors management CLI command.

Examine the Server Log File

You can open the server.log file to view any errors that occurred during bootup.

This method allows you to see each error message together with possibly related messages, allowing you to get more information about why an error might have occurred. It also allows you to see error messages in plain text format.

  1. Open the file server.log in a file viewer.
  2. Navigate to the end of the file.
  3. Search backward for the WFLYSRV0049 message identifier, which marks the start of the latest bootup sequence.
  4. Search the log from that point onward for instances of ERROR. Each instance will include a description of the error and list the modules involved.

The following is an example error description from the server.log log file.

2016-03-16 14:32:01,627 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-7) MSC000001: Failed to start service jboss.undertow.listener.default: org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
        at org.wildfly.extension.undertow.ListenerService.start(ListenerService.java:142)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1948)
        at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1881)
        at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
        at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
        at java.lang.Thread.run(Thread.java:745)
Caused by: java.net.BindException: Address already in use
        ...
Read the Boot Errors from the Management CLI

You can use the read-boot-errors management CLI command to view errors if a server starts but reported errors during bootup.

This method does not require access to the server’s file system, which is useful for anyone responsible for monitoring for errors who does not have file system access. Since it is a management CLI command, it can be used in a script. For example, you could write a script that starts multiple JBoss EAP instances, then checks for errors that occurred on bootup.

Run the following management CLI command.

/core-service=management:read-boot-errors

Any errors that occurred during bootup will be listed.

{
    "outcome" => "success",
    "result" => [
        {
            "failed-operation" => {
                "operation" => "add",
                "address" => [
                    ("subsystem" => "undertow"),
                    ("server" => "default-server"),
                    ("http-listener" => "default")
                ]
            },
            "failure-description" => "{\"WFLYCTL0080: Failed services\" => {\"jboss.undertow.listener.default\" => \"org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use\"}}",
            "failed-services" => {"jboss.undertow.listener.default" => "org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
    Caused by: java.net.BindException: Address already in use"}
        }
        ...
    ]
}

12.1.3. Garbage Collection Logging

Garbage collection logging logs all garbage collection activity to plain text log files. These log files can be useful for diagnostic purposes. Garbage collection logging is enabled by default for a JBoss EAP standalone server on all supported configurations except IBM Java development kit.

The location of the garbage collection log is EAP_HOME/standalone/log/gc.log.DIGIT.current. Garbage collection logs are limited to 3 MB each, and up to five files are rotated.

12.1.4. Default Log File Locations

The following log files are created for the default logging configurations. The default configuration writes the server log files using periodic log handlers.

Table 12.1. Default Log File for a Standalone Server

Log FileDescription

EAP_HOME/standalone/log/server.log

Contains server log messages, including server startup messages.

EAP_HOME/standalone/log/gc.log.DIGIT.current

Contains garbage collection details.

Table 12.2. Default Log Files for a Managed Domain

Log FileDescription

EAP_HOME/domain/log/host-controller.log

Contains log messages related to the startup of the host controller.

EAP_HOME/domain/log/process-controller.log

Contains log messages related to the startup of the process controller.

EAP_HOME/domain/servers/SERVER_NAME/log/server.log

Contains log messages for the named server, including server startup messages.

12.1.5. Set the Default Locale of the Server

You can configure the default locale for JBoss EAP by setting JVM properties in the appropriate startup configuration file. The startup configuration file is EAP_HOME/bin/standalone.conf for a standalone server or EAP_HOME/bin/domain.conf for a managed domain.

Note

For Windows Server, the JBoss EAP startup configuration files are standalone.conf.bat and domain.conf.bat.

Log messages that have been internationalized and localized will use this default locale. See the JBoss EAP Development Guide for information on creating internationalized log messages.

Set the Language

Specify the language by setting the user.language property using the JAVA_OPTS variable. For example, add the following line to the startup configuration file to set a French locale.

JAVA_OPTS="$JAVA_OPTS -Duser.language=fr"

Log messages that have been internationalized and localized will now output in French.

Set the Language and Country

In addition to the language, it may also be necessary to specify the country by setting the user.country property. For example, add the following line to the startup configuration file to set the Portuguese locale for Brazil.

JAVA_OPTS="$JAVA_OPTS -Duser.language=pt -Duser.country=BR"

Log messages that have been internationalized and localized will now output in Brazilian Portuguese.

Set the Server Locale Using the org.jboss.logging.locale Property

You can configure the org.jboss.logging.locale property to override the locale for messages logged using JBoss Logging, including any messages from JBoss EAP and its owned dependencies. Other dependencies, such as JSF, cannot get an overridden locale.

To start the JBoss EAP server with a different locale than the system default, you can edit EAP_HOME/bin/standalone.conf or the EAP_HOME/bin/domain.conf file, depending on your operating mode, and append the following command to set the JVM parameter for the required locale. The value of the property must be specified in the BCP 47 format. For example, to set Brazilian Portuguese, use pt-BR.

JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.logging.locale=pt-BR"

12.2. Viewing Log Files

Viewing server and application logs is important in order to help diagnose errors, performance problems, and other issues. Some users may prefer to view logs directly on the server file system. For those who do not have direct access to the file system, or who prefer a graphical interface, JBoss EAP allows you to view logs from the management console. You can also view logs using the management CLI.

For a log to be accessible from one of the management interfaces, it must be located in the directory specified by the server’s jboss.server.log.dir property and be defined as a file, periodic rotating, size rotating, or periodic size rotating log handler. RBAC role assignments are also honored, so a user logged in to the management console or CLI can only view logs that they are authorized to access.

View Logs from the Management Console

You can view logs directly from the management console.

  • Select the Runtime tab.
  • Select Standalone Server. If you are running in a managed domain, select the appropriate server.
  • Select Log Files and click View.

Once you choose a log file from the list, you can view and search the log contents directly in the management console. You can also download a log file to your local file system.

Warning

The management console log viewer is not intended to be a text editor replacement for viewing very large log files, for example, greater than 100MB. You will be prompted for confirmation if you attempt to open a log file that is larger than 15MB. Opening a very large file in the management console could crash your browser, so you should always download large log files locally and open them in a text editor.

View Logs from the Management CLI

You can read the contents of log files from the management CLI using the read-log-file command. By default, this displays the last 10 lines of the specified log file.

/subsystem=logging/log-file=LOG_FILE_NAME:read-log-file
Note

In a managed domain, precede this command with /host=HOST_NAME/server=SERVER_NAME.

You can use the following parameters to customize the log output.

encoding
The character encoding used to read the file.
lines
The number of lines to read from the file. A value of -1 will read all log lines. The default is 10.
skip
The number of lines to skip before reading. The default is 0.
tail
Whether to read from the end of the file. Defaults to true.

For example, the following management CLI command reads the first 5 lines from the top of the server.log log file.

/subsystem=logging/log-file=server.log:read-log-file(lines=5,tail=false)

This produces the following output.

{
    "outcome" => "success",
    "result" => [
        "2016-03-24 08:49:26,612 INFO  [org.jboss.modules] (main) JBoss Modules version 1.5.1.Final-redhat-1",
        "2016-03-24 08:49:26,788 INFO  [org.jboss.msc] (main) JBoss MSC version 1.2.6.Final-redhat-1",
        "2016-03-24 08:49:26,863 INFO  [org.jboss.as] (MSC service thread 1-7) WFLYSRV0049: JBoss EAP 7.0.0.GA (WildFly Core 2.0.13.Final-redhat-1) starting",
        "2016-03-24 08:49:27,973 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0039: Creating http management service using socket-binding (management-http)",
        "2016-03-24 08:49:27,994 INFO  [org.xnio] (MSC service thread 1-1) XNIO version 3.3.4.Final-redhat-1"
    ]
}

12.3. About the Logging Subsystem

The JBoss EAP logging subsystem is configured using a system of log categories and log handlers. Log categories define what messages to capture. Log handlers define how to deal with those messages, for example, writing to a disk or sending to the console.

Logging profiles allow uniquely-named sets of logging configuration to be created and assigned to applications independent of any other logging configuration. The configuration of logging profiles is almost identical to the main logging subsystem.

12.3.1. Root Logger

The JBoss EAP root logger captures all log messages, of the specified log level or higher, sent to the server that are not captured by a log category.

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 server.log file. This file is often referred to as the server log.

See Configuring the Root Logger for more information.

12.3.2. Log Categories

A log category defines a set of log messages to capture and one or more log handlers that will process the messages.

The log messages to capture are defined by the specified Java package of origin and log level. Messages from classes in that package and of that log level or higher are captured by the log category and sent to the specified log handlers.

Note

Although the log category is typically the Java package and class name, it can be any name specified by the Logger.getLogger(LOGGER_NAME) method.

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

See Configuring Log Categories for more information.

12.3.3. Log Handlers

Log handlers define how captured log messages are recorded. The available log handler types are console, file, periodic, size, periodic size, syslog, custom, and async.

Note

A log handler must be added to at least one logger in order to be active.

Log Handler Types
Console
A console log handler writes log messages to either the host operating system’s standard out (stdout) or standard error (stderr) stream. These messages are displayed when JBoss EAP is run from a command line prompt. 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
A file log handler writes log messages to a specified file.
Periodic
A periodic log handler writes log messages to a named file until a specified period of time has elapsed. Once the time period has passed, 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
A size log handler writes 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 suffix 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.
Periodic Size

A periodic size log handler writes log messages to a named file until the file reaches the specified size or the specified time period has passed. Then, the file is renamed and the handler continues to write to a newly created log file with the original name.

This is a combination of the periodic and size log handlers and supports their combined attributes.

Syslog
A syslog handler can be used to send messages to a remote logging server. This allows multiple applications to send their log messages to the same server, where they can all be parsed together.
Custom
A custom log handler enables 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. You can also use a Log4J appender as a custom log handler.
Async
An async log handler is a wrapper log handler that provides asynchronous behavior for one or more other log handlers. This is useful for log handlers that may have high latency or other performance problems such as writing a log file to a network file system.

For details on configuring each of these log handlers, see the Configuring Log Handlers section.

12.3.4. Log Levels

A log level is an enumerated value that indicates the nature and severity of a log message. As a developer, you can specify the level of a given log message using the appropriate method of your chosen logging framework to send the message.

JBoss EAP supports all the log levels used by the supported application logging frameworks. The most commonly used log levels from lowest to highest are 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 that 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.

Supported Log Levels
Log LevelValueDescription

ALL

Integer.MIN_VALUE

Provides all log messages.

FINEST

300

-

FINER

400

-

TRACE

400

TRACE level log messages provide detailed information about the running state of an application and are usually only captured during debugging.

DEBUG

500

DEBUG level log messages indicate the progress of individual requests or application activities and are usually only captured during debugging.

FINE

500

-

CONFIG

700

-

INFO

800

INFO level log messages indicate the overall progress of the application. Often used for application startup, shutdown, and other major lifecycle events.

WARN

900

WARN level log messages indicate a situation that is not in error, but is not considered ideal. WARN log messages can indicate circumstances that could lead to errors in the future.

WARNING

900

-

ERROR

1000

ERROR level log messages 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

FATAL level log messages indicate events that could cause critical service failure and application shutdown and could cause JBoss EAP to shutdown.

OFF

Integer.MAX_VALUE

Does not display any log message.

Note

ALL is the lowest log level and includes messages of all log levels. This provides the most amount of logging.

FATAL is the highest log level and only includes messages of that level. This provides the least amount of logging.

12.3.5. Log Formatters

A log formatter defines the appearance of log messages from that handler. It is a string that uses a syntax based on java.util.logging.Formatter class.

For example, the default configuration uses the following log formatter string for logging messages to the server log: %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. This will create log messages like the one shown below.

2016-03-18 15:49:32,075 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990

For more information on configuring log formatters, see Configure a Named Pattern Formatter or Configure a Custom Log Formatter.

See the table below for the syntax used in log formatter strings.

Log Formatter Syntax
SymbolDescription

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

%r

The relative time (milliseconds since the log was initialized).

%z

The time zone, which must be specified before the date (%d). For example, %z{GMT}%d{HH:mm:ss,SSS}.

%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 Nested Diagnostic Context.

%X

The Message Diagnostic Context.

%%

A literal percent (%) character (escaping).

12.3.6. Filter Expressions

Filter expressions, configured using the filter-spec attribute, are used to record log messages based on various criteria. Filter checking is always done on a raw unformatted message. You can include a filter for a logger or handler, but the logger filter takes precedence over the filter put on a handler.

Note

A filter-spec specified for the root logger is not inherited by other loggers. Instead a filter-spec must be specified per handler.

Table 12.3. Filter Expressions for Logging

Filter ExpressionDescription

accept

Accept all log messages.

deny

Deny all log messages.

not[filter expression]

Returns the inverted value of a single filter expression. For example:

not(match("WFLY"))

all[filter expression]

Returns concatenated value from a comma-separated list of filter expressions. For example:

all(match("WFLY"),match("WELD"))

any[filter expression]

Returns one value from a comma-separated list of filter expressions. For example:

any(match("WFLY"),match("WELD"))

levelChange[level]

Updates the log record with the specified level. For example:

levelChange(WARN)

levels[levels]

Filters log messages with a level listed in the comma-separated list of levels. For example:

levels(DEBUG,INFO,WARN,ERROR)

levelRange[minLevel,maxLevel]

Filters log messages within the specified level range. The [ and ] characters are used to indicate an inclusive level. The ( and ) characters are used to indicate an exclusive level. For example:

  • levelRange[INFO,ERROR]

    • The minimum level must be greater than or equal to INFO and the maximum level must be less than or equal to ERROR.
  • levelRange[DEBUG,ERROR)

    • The minimum level must be greater than or equal to DEBUG and the maximum level must be less than ERROR.

match["pattern"]

Filters log messages using the provided regular expression. For example:

match("WFLY\d+")

substitute["pattern","replacement value"]

A filter that replaces the first match to the pattern (first argument) with the replacement text (second argument). For example:

substitute("WFLY","EAP")

substituteAll["pattern","replacement value"]

A filter which replaces all matches of the pattern (first argument) with the replacement text (second argument). For example:

substituteAll("WFLY","EAP")

Note

When configuring the filter expression using the management CLI, be sure to escape commas and quotation marks in the filter text so that the value is correctly processed as a string. You must precede commas and quotation marks with a backslash (\) and wrap the entire expression in quotation marks. Below is an example that properly escapes substituteAll("WFLY","YLFW").

/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"WFLY\"\,\"YLFW\")")

12.3.7. Implicit Logging Dependencies

By default, the JBoss EAP logging subsystem adds implicit logging API dependencies to deployments. You can control whether these implicit dependencies are added to deployments by using the add-logging-api-dependencies attribute, which is true by default.

Using the management CLI, you can set the add-logging-api-dependencies attribute to false so that the implicit logging API dependencies will not be added to deployments.

/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

For information on the implicit dependencies for the logging subsystem, see the Implicit Module Dependencies section in the JBoss EAP Development Guide.

12.4. Configuring Log Categories

This section shows you how to configure log categories using the management CLI. You can also configure log categories using the management console by navigating to the Logging subsystem from the Configuration tab and selecting the Log Categories tab.

The main tasks you will perform to configure a log category are:

Important

If you are configuring this log category for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Log Category

The log category name is defined by the Java package of origin. Messages from classes in that package will be captured as long as they adhere to the other settings, for example, the log level.

/subsystem=logging/logger=LOG_CATEGORY:add

Configure Log Category Settings

Depending on your needs, you may need to set one or more of the following log category attributes. For a full list of available log category attributes and their descriptions, see Log Category Attributes.

  • Set the log level.

    Set the appropriate log level for the log category. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=level,value=LEVEL)
  • Set whether this category should use the log handlers of the root logger.

    By default, log categories will use the handlers of the root logger in addition to its own. Set the use-parent-handlers attribute to false if the log category should use only its assigned handlers.

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=use-parent-handlers,value=USE_PARENT_HANDLERS)
  • Set the filter expression.

    Set the expression for filtering log messages for the log category. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign a Handler

Assign a log handler to the log category.

/subsystem=logging/logger=LOG_CATEGORY:add-handler(name=LOG_HANDLER_NAME)

Remove a Log Category

A log category can be removed with the remove operation.

/subsystem=logging/logger=LOG_CATEGORY:remove

12.5. Configuring Log Handlers

Log handlers define how captured log messages are recorded. See the appropriate section for configuring the type of log handler that you need.

12.5.1. Configure a Console Log Handler

This section shows you how to configure a console log handler using the management CLI. You can also configure console log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Console from the left-hand menu.

The main tasks you will perform to configure a console log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Console Log Handler
/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:add
Configure Console Log Handler Settings

Depending on your needs, you may need to set one or more of the following console log handler attributes. For a full list of available console log handler attributes and their descriptions, see Console Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the target.

    Set the target for the handler, which can be one of System.out, System.err, or console. The default is System.out.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=target,value=TARGET)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Console Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the console log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=CONSOLE_HANDLER_NAME)

The following management CLI command assigns the console log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=CONSOLE_HANDLER_NAME)
Remove a Console Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:remove

12.5.2. Configure a File Log Handler

This section shows you how to configure a file log handler using the management CLI. You can also configure file log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting File from the left-hand menu.

The main tasks you will perform to configure a file log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a File Log Handler

When adding a file log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

/subsystem=logging/file-handler=FILE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
Configure File Log Handler Settings

Depending on your needs, you may need to set one or more of the following file log handler attributes. For a full list of available file log handler attributes and their descriptions, see File Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the File Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the file log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=FILE_HANDLER_NAME)

The following management CLI command assigns the file log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=FILE_HANDLER_NAME)
Remove a File Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/file-handler=FILE_HANDLER_NAME:remove

12.5.3. Configure a Periodic Rotating Log Handler

This section shows you how to configure a periodic rotating log handler using the management CLI. You can also configure periodic log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Periodic from the left-hand menu.

The main tasks you will perform to configure a periodic log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Periodic Log Handler

When adding a periodic log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

You must also set the suffix for rotated logs using the suffix attribute. This must be in a format that can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH. The period of the rotation is automatically calculated based on this suffix.

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
Configure Periodic Log Handler Settings

Depending on your needs, you may need to set one or more of the following periodic log handler attributes. For a full list of available periodic log handler attributes and their descriptions, see Periodic Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Periodic Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the periodic log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_HANDLER_NAME)

The following management CLI command assigns the periodic log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_HANDLER_NAME)
Remove a Periodic Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:remove

12.5.4. Configure a Size Rotating Log Handler

This section shows you how to configure a size rotating log handler using the management CLI. You can also configure size log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Size from the left-hand menu.

The main tasks you will perform to configure a size log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Size Log Handler

When adding a size log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
Configure Size Log Handler Settings

Depending on your needs, you may need to set one or more of the following size log handler attributes. For a full list of available size log handler attributes and their descriptions, see Size Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the suffix for rotated logs.

    Set the suffix string, which is in a format which can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH . The period of the rotation is automatically calculated based on this suffix.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=suffix, value=SUFFIX)
  • Set the rotation size.

    Set the maximum size that the file can reach before being rotated. The default is 2m for 2 megabytes.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • Set the maximum number of backup logs to keep.

    Set the number of backups to keep. The default is 1.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • Set whether to rotate the log on boot.

    By default, a new log file is not created on server restart. You can set this to true to rotate the log on server restart.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Size Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the size log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=SIZE_HANDLER_NAME)

The following management CLI command assigns the size log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=SIZE_HANDLER_NAME)
Remove a Size Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:remove

12.5.5. Configure a Periodic Size Rotating Log Handler

This section shows you how to configure a periodic size rotating log handler using the management CLI. You can also configure periodic size log handlers using the management console by navigating to the Logging subsystem, selecting the Handler tab, and selecting Periodic Size from the left-hand menu.

The main tasks you will perform to configure a periodic size log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Periodic Size Log Handler

When adding a periodic size log handler, you must specify the file path using the file attribute, which is comprised of the path and relative-to attributes. Use the path attribute to set the file path for the log, including the name, for example my-log.log. Optionally, use the relative-to attribute to set that the path is relative to a named path, for example jboss.server.log.dir.

You must also set the suffix for rotated logs using the suffix attribute. This must be in a format that can be understood by java.text.SimpleDateFormat, for example .yyyy-MM-dd-HH. The period of the rotation is automatically calculated based on this suffix.

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
Configure Periodic Size Log Handler Settings

Depending on your needs, you may need to set one or more of the following periodic size log handler attributes. For a full list of available periodic size log handler attributes and their descriptions, see Periodic Size Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the rotation size.

    Set the maximum size that the file can reach before being rotated. The default is 2m for 2 megabytes.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
  • Set the maximum number of backup logs to keep.

    Set the number of backups to keep. The default is 1.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
  • Set whether to rotate the log on boot.

    By default, a new log file is not created on server restart. You can set this to true to rotate the log on server restart.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
  • Set the append behavior.

    By default, JBoss EAP will append log messages to the same file when the server is restarted. You can set the append attribute to false to have the file overwritten upon server restart.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set auto flush.

    Set whether to automatically flush after each write. The default value is true.

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Periodic Size Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the periodic size log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)

The following management CLI command assigns the periodic size log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)
Remove a Periodic Size Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:remove

12.5.6. Configure a Syslog Handler

This section shows you how to configure a syslog handler using the management CLI, which can be used to send messages to a remote logging server that supports the Syslog protocol (RFC-3164 or RFC-5424). You can also configure syslog handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Syslog from the left-hand menu.

The main tasks you will perform to configure a syslog handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Syslog Handler
/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:add
Configure Syslog Handler Settings

Depending on your needs, you may need to set one or more of the following syslog handler attributes. For a full list of available syslog handler attributes and their descriptions, see Syslog Handler Attributes.

  • Set the log level for the handler. The default level is ALL. See Log Levels for all available options.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the name of the application that is logging. The default name is java.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=app-name,value=APP_NAME)
  • Set the address of the syslog server. The default address is localhost.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=server-address,value=SERVER_ADDRESS)
  • Set the port of the syslog server. The default port is 514.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=port,value=PORT)
  • Set the syslog format, as defined by an RFC specification. The default format is RFC5424.

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=syslog-format,value=SYSLOG_FORMAT)
Assign the Syslog Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the syslog handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=SYSLOG_HANDLER_NAME)

The following management CLI command assigns the syslog handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=SYSLOG_HANDLER_NAME)
Remove a Syslog Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:remove

12.5.7. Configure a Custom Log Handler

This section shows you how to configure a custom log handler using the management CLI. You can also configure custom log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Custom from the left-hand menu.

The main tasks you will perform to configure a custom log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add a Custom Log Handler

When adding a custom log handler, you must specify the Java class of the handler and the JBoss EAP module in which it is contained. The class must extend java.util.logging.Handler.

Note

You must have already created a module containing the custom logger or this command will fail.

/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:add(class=CLASS_NAME,module=MODULE_NAME)
Configure Custom Log Handler Settings

Depending on your needs, you may need to set one or more of the following custom log handler attributes. For a full list of available custom log handler attributes and their descriptions, see Custom Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the properties.

    Set the necessary properties for the log handler. The properties must be accessible using a setter method.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  • Set the encoding.

    Set the encoding for the handler, for example, utf-8.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
  • Set the log formatter.

    Set the formatter string for the handler. For example, the default format string is %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n. Be sure to enclose the FORMAT value in quotation marks.

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
    Note

    Use the named-formatter attribute if you want to reference a saved formatter.

  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Custom Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the custom log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=CUSTOM_HANDLER_NAME)

The following management CLI command assigns the custom log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=CUSTOM_HANDLER_NAME)
Remove a Custom Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger or async log handler.

/subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:remove

12.5.8. Configure an Async Log Handler

This section shows you how to configure an async log handler using the management CLI. You can also configure async log handlers using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Handler tab, and selecting Async from the left-hand menu.

The main tasks you will perform to configure an async log handler are:

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Add an Async Log Handler

When adding an async log handler, you must specify the queue length. This is the maximum number of log requests that can be held in queue.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add(queue-length=QUEUE_LENGTH)
Add a Sub-handler

You can add one or more handlers as sub-handlers for this async log handler. Note that the handlers must already exist in the configuration or this command will fail.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add-handler(name=HANDLER_NAME)
Configure Async Log Handler Settings

Depending on your needs, you may need to set one or more of the following async log handler attributes. For a full list of available async log handler attributes and their descriptions, see Async Log Handler Attributes.

  • Set the log level.

    Set the appropriate log level for the handler. The default is ALL. See Log Levels for all available options.

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
  • Set the overflow action.

    Set the action to take when overflowing. The default value is BLOCK, which means that threads will block in the event of a full queue. You can change this value to DISCARD, which means that log messages will be discarded in the event of a full queue.

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=overflow-action,value=OVERFLOW_ACTION)
  • Set the filter expression.

    Set the expression for filtering log messages for the handler. Be sure to escape any commas and quotation marks and surround with quotation marks. For example, the FILTER_EXPRESSION replaceable variable below would need to be replaced with "not(match(\"WFLY\"))" for a filter expression of not(match("WFLY")).

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)

    See the Filter Expressions section for more information on available filter expressions.

Assign the Async Log Handler to a Logger

In order for a log handler to be active, you must assign it to a logger.

The following management CLI command assigns the async log handler to the root logger.

/subsystem=logging/root-logger=ROOT:add-handler(name=ASYNC_HANDLER_NAME)

The following management CLI command assigns the async log handler to a logger whose name is specified by CATEGORY.

/subsystem=logging/logger=CATEGORY:add-handler(name=ASYNC_HANDLER_NAME)
Remove an Async Log Handler

A log handler can be removed with the remove operation. A log handler cannot be removed if it is currently assigned to a logger.

/subsystem=logging/async-handler=ASYNC_HANDLER_NAME:remove

12.6. Configuring the Root Logger

The root logger captures all log messages, of the specified log level or higher, sent to the server that are not captured by a log category.

This section shows you how to configure the root logger using the management CLI. You can also configure the root logger using the management console by navigating to the Logging subsystem from the Configuration tab and selecting the Root Logger tab.

Configure the Root Logger

Important

If you are configuring this log handler for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

  1. Assign log handlers to the root logger.

    Add a log handler.

    /subsystem=logging/root-logger=ROOT:add-handler(name=LOG_HANDLER_NAME)

    Remove a log handler.

    /subsystem=logging/root-logger=ROOT:remove-handler(name=LOG_HANDLER_NAME)
  2. Set the log level.

    /subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=LEVEL)

For a full list of available root logger attributes and their descriptions, see Root Logger Attributes.

12.7. Configuring Log Formatters

A log formatter defines the appearance of log messages from that handler. You can configure a named pattern formatter or a custom log formatter.

12.7.1. Configure a Named Pattern Formatter

You can create a named pattern formatter that can be used across log handlers to format log messages.

This section shows you how to configure a log formatter using the management CLI. You can also configure log formatters using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Formatter tab, and selecting Pattern from the left-hand menu.

Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

Create a Named Formatter

When defining a formatter, you provide a pattern string to use to format log messages. See log formatters for more information on the pattern syntax.

/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:add(pattern=PATTERN_STRING)

You can also define a color map to assign a color to different log levels. The format is a comma-separated list of LEVEL:COLOR.

  • Valid levels: finest, finer, fine, config, trace, debug, info, warning, warn, error, fatal, severe
  • Valid colors: black, green, red, yellow, blue, magenta, cyan, white, brightblack, brightred, brightgreen, brightblue, brightyellow, brightmagenta, brightcyan, brightwhite
/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:write-attribute(name=color-map,value="LEVEL:COLOR,LEVEL:COLOR")
Assign a Named Formatter to a Log Handler

The following management CLI command assigns a pattern formatter to be used by a periodic rotating file handler.

/subsystem=logging/periodic-rotating-file-handler=FILE_HANDLER_NAME:write-attribute(name=named-formatter,value=PATTERN_FORMATTER_NAME)

12.7.2. Configure a Custom Log Formatter

You can create a custom log formatter that can be used across log handlers to format log messages.

This section shows you how to configure a custom log formatter using the management CLI. You can also configure log formatters using the management console by navigating to the Logging subsystem from the Configuration tab, selecting the Formatter tab, and selecting Custom from the left-hand menu.

Configure a Custom Log Formatter
Important

If you are configuring this log formatter for a logging profile, the start of the command would be /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ instead of /subsystem=logging/.

Additionally, if you are running in a managed domain, precede the commands with /profile=PROFILE_NAME.

  1. Add the custom log formatter.

    When adding a custom log formatter, you must specify the Java class of the formatter and the JBoss EAP module in which it is contained. The class must extend java.util.logging.Formatter.

    Note

    You must have already created a module containing the custom formatter or this command will fail.

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:add(class=CLASS_NAME, module=MODULE_NAME)
  2. Set the necessary properties for the log formatter.

    The properties must be accessible using a setter method.

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
  3. Assign the custom formatter to a log handler.

    The following management CLI command assigns a custom formatter to be used by a periodic rotating file handler.

    /subsystem=logging/periodic-rotating-file-handler=FILE_HANDLER_NAME:write-attribute(name=named-formatter, value=CUSTOM_FORMATTER_NAME)
Example Custom XML Formatter

The following example configures a custom XML formatter. It uses the java.util.logging.XMLFormatter class provided in the org.jboss.logmanager module and assigns it to the console log handler.

/subsystem=logging/custom-formatter=custom-xml-formatter:add(class=java.util.logging.XMLFormatter, module=org.jboss.logmanager)
/subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter, value=custom-xml-formatter)

A log message using this formatter would be formatted as below.

<record>
  <date>2016-03-23T12:58:13</date>
  <millis>1458752293091</millis>
  <sequence>93963</sequence>
  <logger>org.jboss.as</logger>
  <level>INFO</level>
  <class>org.jboss.as.server.BootstrapListener</class>
  <method>logAdminConsole</method>
  <thread>22</thread>
  <message>WFLYSRV0051: Admin console listening on http://%s:%d</message>
  <param>127.0.0.1</param>
  <param>9990</param>
</record>

12.8. About Application Logging

Logging for applications can be configured using the JBoss EAP logging subsystem or on a per-deployment basis.

See About the Logging Subsystem for using JBoss EAP log categories and handlers for capturing log messages.

For more information on application logging, such as supported application logging frameworks and configuring per-deployment logging, see the Logging chapter in the JBoss EAP Development Guide.

12.8.1. Per-deployment Logging

Per-deployment logging allows a developer to configure the logging configuration for their application in advance. When the application is deployed, logging begins according to the defined configuration. The log files created through this configuration contain information only about the behavior of the application.

Note

If the per-deployment logging configuration is not done, the configuration from logging subsystem is used for all the applications as well as the server.

This approach has advantages and disadvantages over using system-wide logging. An advantage is that the administrator of the JBoss EAP instance does not need to configure any other logging than the server logging. A disadvantage is that the per-deployment logging configuration is read only on server startup, and so cannot be changed at runtime.

For instructions on using per-deployment logging in your applications, see Add Per-deployment Logging to an Application in the JBoss EAP Development Guide.

12.8.1.1. Disable Per-deployment Logging

You can disable per-deployment logging in one of the following ways:

  • Set the use-deployment-logging-config attribute to false.

    The use-deployment-logging-config attribute controls whether or not your deployment is scanned for per-deployment logging. This defaults to true by default. You can set this attribute to false to disable per-deployment logging.

    /subsystem=logging:write-attribute(name=use-deployment-logging-config,value=false)
  • Exclude the logging subsystem using a jboss-deployment-structure.xml file.

    For instructions, see Exclude a Subsystem from a Deployment in the JBoss EAP Development Guide.

12.8.2. Logging Profiles

Logging profiles are independent sets of logging configurations that can be assigned to deployed applications. As with the regular logging subsystem, a logging profile can define handlers, categories, and a root logger, but it cannot refer to configurations in other profiles or the main logging subsystem. The design of logging profiles mimics the logging subsystem for ease of configuration.

Logging profiles allow administrators to create logging configurations that are specific to one or more applications without affecting any other logging configurations. Because each profile is defined in the server configuration, the logging configuration can be changed without requiring that the affected applications be redeployed. However, logging profiles cannot be configured using the management console.

Each logging profile can have:

  • A unique name (required)
  • Any number of log handlers
  • Any number of log categories
  • Up to one root logger

An application can specify a logging profile to use in its MANIFEST.MF file, using the Logging-Profile attribute.

12.8.2.1. Configure a Logging Profile

A logging profile can be configured with log handlers, categories, and a root logger. Configuring a logging profile uses the same syntax as configuring the logging subsystem, except for the following differences:

  • The root configuration path is /subsystem=logging/logging-profile=NAME.
  • A logging profile cannot contain other logging profiles.
  • The logging subsystem has the following attributes that are not available for a logging profile:

    • add-logging-api-dependencies
    • use-deployment-logging-config
Creating and Configuring a Logging Profile

The following procedure uses the management CLI to create a logging profile and set a file handler and logger category.

  1. Create the logging profile.

    /subsystem=logging/logging-profile=PROFILE_NAME:add
  2. Create the file handler.

    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:add(file={path=>"LOG_NAME.log", "relative-to"=>"jboss.server.log.dir"})
    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:write-attribute(name="level", value="DEBUG")

    See File Log Handler Attributes for the list of file handler attributes.

  3. Create the logger category.

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add(level=TRACE)

    See Log Category Attributes for the list of log category attributes.

  4. Assign the file handler to the category.

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add-handler(name="FILE_HANDLER_NAME")

You can then set the logging profile to use by an application in its MANIFEST.MF file. For more information, see Specify a Logging Profile in an Application in the JBoss EAP Development Guide.

12.8.2.2. Example Logging Profile Configuration

This example shows the configuration of a logging profile and the application that uses it. It shows the management CLI commands, the resulting XML, and the application’s MANIFEST.MF file.

The example logging profile has the following characteristics:

  • The name is accounts-app-profile.
  • The log category is com.company.accounts.ejbs.
  • The log level TRACE.
  • The log handler is a file handler using the file ejb-trace.log.

Management CLI Session

/subsystem=logging/logging-profile=accounts-app-profile:add

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:write-attribute(name="level", value="DEBUG")

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add-handler(name="ejb-trace-file")

XML Configuration

<logging-profiles>
   <logging-profile name="accounts-app-profile">
      <file-handler name="ejb-trace-file">
         <level name="DEBUG"/>
         <file relative-to="jboss.server.log.dir" path="ejb-trace.log"/>
      </file-handler>
      <logger category="com.company.accounts.ejbs">
         <level name="TRACE"/>
         <handlers>
            <handler name="ejb-trace-file"/>
         </handlers>
      </logger>
   </logging-profile>
</logging-profiles>

Application MANIFEST.MF file

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile

12.8.3. Viewing Deployment Logging Configuration

You can obtain information about the logging configuration for a particular deployment using the following management CLI command.

/deployment=DEPLOYMENT_NAME/subsystem=logging/configuration=CONFIG:read-resource

The logging configuration value (CONFIG) for a deployment can be one of three values:

  • default, if the deployment is using the logging subsystem. This will output the logging subsystem configuration.
  • profile-PROFILE_NAME, if the deployment is using a logging profile defined in the logging subsystem. This will output the logging profile configuration.
  • The path to the configuration file being used, for example, myear.ear/META-INF/logging.properties.

For example, the below management CLI command displays the configuration for the MYPROFILE logging profile, which is used by the specified deployment.

/deployment=mydeployment.war/subsystem=logging/configuration=profile-MYPROFILE:read-resource(recursive=true,include-runtime=true)

This will output the following information.

{
    "outcome" => "success",
    "result" => {
        "error-manager" => undefined,
        "filter" => undefined,
        "formatter" => {
            "MYFORMATTER" => {
                "class-name" => "org.jboss.logmanager.formatters.PatternFormatter",
                "module" => undefined,
                "properties" => {"pattern" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"}
            }
        },
        "handler" => {
            "MYPERIODIC" => {
                "class-name" => "org.jboss.logmanager.handlers.PeriodicRotatingFileHandler",
                "encoding" => undefined,
                "error-manager" => undefined,
                "filter" => undefined,
                "formatter" => "MYFORMATTER",
                "handlers" => [],
                "level" => "ALL",
                "module" => undefined,
                "properties" => {
                    "append" => "true",
                    "autoFlush" => "true",
                    "enabled" => "true",
                    "suffix" => ".yyyy-MM-dd",
                    "fileName" => "EAP_HOME/standalone/log/deployment.log"
                }
            }
        },
        "logger" => {"MYCATEGORY" => {
            "filter" => undefined,
            "handlers" => [],
            "level" => "DEBUG",
            "use-parent-handlers" => true
        }},
        "pojo" => undefined
    }
}

You could also use a recursive read-resource operation to read the logging configuration and other information about a deployment.

/deployment=DEPLOYMENT_NAME/subsystem=logging:read-resource(include-runtime=true, recursive=true)