Chapter 11. 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.
11.1. About Server Logging
11.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.
11.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
-
Domain controller:
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.
11.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.
-
Open the file
server.log
in a file viewer. - Navigate to the end of the file.
-
Search backward for the
WFLYSRV0049
message identifier, which marks the start of the latest bootup sequence. -
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"} } ... ] }
11.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.
It is strongly recommended to leave garbage collection logging enabled as it can be useful in troubleshooting and should have minimal overhead. However, you can disable garbage collection logging for a standalone server by setting the GC_LOG
variable to false
before starting the server. For example:
$ export GC_LOG=false
$ EAP_HOME/bin/standalone.sh
11.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.
Log File | Description |
---|---|
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. |
Log File | Description |
---|---|
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. |
11.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.
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 Jakarta Server Faces, 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"
11.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 and select the appropriate server.
- Select Log Files and choose a log file from the list.
- Click View to view and search log contents, or choose Download from the drop down to download the log file to your local file system.
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
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 is10
. - 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" ] }
11.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.
11.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.
11.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.
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.
11.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.
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.
- Socket
- A socket log handler can be used to send log messages over a socket to a remote logging server. This can be a TCP or UDP socket.
- 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.
11.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 Level | Value | Description |
---|---|---|
ALL | Integer.MIN_VALUE | Provides all log messages. |
FINEST | 300 | - |
FINER | 400 | - |
TRACE | 400 |
|
DEBUG | 500 |
|
FINE | 500 | - |
CONFIG | 700 | - |
INFO | 800 |
|
WARN | 900 |
|
WARNING | 900 | - |
ERROR | 1000 |
|
SEVERE | 1000 | - |
FATAL | 1100 |
|
OFF | Integer.MAX_VALUE | Does not display any log message. |
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.
11.3.5. Log Formatters
Formatters are used to format a log message. A formatter can be assigned to a logging handler using the named-formatter
attribute. For more information on logging handler configuration, see Configuring Log Handlers.
The logging subsystem includes four types of formatters:
Pattern Formatter
A pattern formatter is used to format log messages in plain text. In addition to using the formatter as the named-formatter
attribute of log handlers, it can also be used as a formatter
attribute, without the need to create the formatter resource first. See Format Characters for Pattern Formatter for more information on the pattern syntax.
See Configure a Pattern Formatter for information on how to configure a pattern formatter.
JSON Formatter
A JSON formatter is used to format log messages in JSON.
See Configure a JSON Log Formatter for information on how to configure a JSON formatter.
XML Formatter
The XML log formatter is used to format log messages in XML.
See Configure an XML Log Formatter for information on how to configure an XML log formatter.
Custom Formatter
A custom formatter to be used with handlers. Note that most log records are formatted in the printf format. Formatters may require invocation of the org.jboss.logmanager.ExtLogRecord#getFormattedMessage()
for the message to be properly formatted.
See Configure a Custom Log Formatter for information on how to configure a custom log formatter.
11.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.
A filter-spec
specified for the root logger is not inherited by other loggers. Instead a filter-spec
must be specified per handler.
Filter Expression | Description |
---|---|
accept | Accept all log messages. |
deny | Deny all log messages. |
not[filter expression] | Returns the inverted value of a single filter expression. For example:
|
all[filter expression] | Returns concatenated value from a comma-separated list of filter expressions. For example:
|
any[filter expression] | Returns one value from a comma-separated list of filter expressions. For example:
|
levelChange[level] | Updates the log record with the specified level. For example:
|
levels[levels] | Filters log messages with a level listed in the comma-separated list of levels. For example:
|
levelRange[minLevel,maxLevel] |
Filters log messages within the specified level range. The
|
match["pattern"] | Filters log messages using the provided regular expression. For example:
|
substitute["pattern","replacement value"] | A filter that replaces the first match to the pattern (first argument) with the replacement text (second argument). For example:
|
substituteAll["pattern","replacement value"] | A filter which replaces all matches of the pattern (first argument) with the replacement text (second argument). For example:
|
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\")")
11.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.
11.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 Configuration
The main tasks you will perform to configure a log category are:
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 tofalse
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 ofnot(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
11.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.
11.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 Configuration
The main tasks you will perform to configure a console log handler are:
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
, orconsole
. The default isSystem.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 theFORMAT
value in quotation marks./subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.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 Configuration
The main tasks you will perform to configure a file log handler are:
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 tofalse
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 theFORMAT
value in quotation marks./subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.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 Configuration
The main tasks you will perform to configure a periodic log handler are:
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 tofalse
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 theFORMAT
value in quotation marks./subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.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 Configuration
The main tasks you will perform to configure a size log handler are:
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 tofalse
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 theFORMAT
value in quotation marks./subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.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 Configuration
The main tasks you will perform to configure a periodic size log handler are:
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 tofalse
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 theFORMAT
value in quotation marks./subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.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, either RFC-3164 or RFC-5424. You can also configure syslog handlers using the management console by navigating to Configuration
The main tasks you will perform to configure a syslog handler are:
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)
Specify the
named-formatter
attribute to format the message of the syslog payload./subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=named-formatter, value=FORMATTER_NAME)
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
11.5.7. Configure a Socket Log Handler
This section shows you how to configure a socket log handler using the management CLI, which can be used to send messages over a socket. This can be a TCP or UDP socket. You can also configure socket log handlers using the management console by navigating to Configuration
If the server is started in admin-only mode, log messages are discarded.
The main tasks you will perform to configure a socket log handler are:
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 the Socket Binding
Define either a remote-destination-outbound-socket-binding
or local-destination-outbound-socket-binding
as the socket binding to use.
/socket-binding-group=SOCKET_BINDING_GROUP/remote-destination-outbound-socket-binding=SOCKET_BINDING_NAME:add(host=HOST, port=PORT)
Add the Log Formatter
Define a log formatter to use, such as a JSON formatter.
/subsystem=logging/json-formatter=FORMATTER:add
Add the Socket Log Handler
When adding the socket log handler, you must specify the socket binding and formatter to use.
/subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:add(outbound-socket-binding-ref=SOCKET_BINDING_NAME,named-formatter=FORMATTER)
Configure Socket Log Handler Settings
Depending on your needs, you may need to set one or more of the following socket log handler attributes. For a full list of available socket log handler attributes and their descriptions, see Socket Log Handler Attributes.
Set the protocol.
Set the protocol to use. The default is
TCP
./subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=protocol,value=PROTOCOL)
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/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
NoteDuring server startup, log messages handled by a socket log handler are queued until the socket binding is configured and the
logging
subsystem is initialized. If the log level is set to a low level, such asTRACE
orDEBUG
, this can result in large memory consumption during startup.Set the encoding.
Set the encoding for the handler, for example,
utf-8
./subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
Set auto flush.
Set whether to automatically flush after each write. The default value is
true
./subsystem=logging/socket-handler=SOCKET_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 ofnot(match("WFLY"))
./subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
See the Filter Expressions section for more information on available filter expressions.
Assign the Socket 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 socket log handler to the root logger.
/subsystem=logging/root-logger=ROOT:add-handler(name=SOCKET_HANDLER_NAME)
The following management CLI command assigns the socket log handler to a logger whose name is specified by CATEGORY
.
/subsystem=logging/logger=CATEGORY:add-handler(name=SOCKET_HANDLER_NAME)
Remove a Socket 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/socket-handler=SOCKET_HANDLER_NAME:remove
Send Log Messages Over a Socket Using SSL/TLS
The following steps show an example of how to set up a socket log handler to send log messages over a socket using the SSL_TCP
protocol. This example configures a keystore, trust manager, and client SSL context in the elytron
subsystem to be used by the socket log handler. Log messages from the root logger are sent over the specified socket, formatted by a JSON formatter.
For more information on configuring Elytron components, see Elytron Subsystem in How to Configure Server Security for JBoss EAP.
Configure the Elytron settings.
Add the keystore.
/subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.jks, type=JKS, credential-reference={clear-text=mypassword})
Add the trust manager.
/subsystem=elytron/trust-manager=log-server-tm:add(key-store=log-server-ks)
Add the client SSL context.
/subsystem=elytron/client-ssl-context=log-server-context:add(trust-manager=log-server-tm, protocols=["TLSv1.2"])
Add the socket binding.
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)
Add a JSON formatter.
/subsystem=logging/json-formatter=json:add
Add the socket log handler.
/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=SSL_TCP, ssl-context=log-server-context)
Assign the log handler to the root logger.
/subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)
11.5.8. 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 Configuration
The main tasks you will perform to configure a custom log handler are:
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
.
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 theFORMAT
value in quotation marks./subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
NoteUse 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 ofnot(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
11.5.9. 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 Configuration
The main tasks you will perform to configure an async log handler are:
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 toDISCARD
, 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 ofnot(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
11.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 Configuration
Configure the Root Logger
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
.
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)
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.
11.7. Configuring Log Formatters
A log formatter defines the appearance of log messages from that handler. The logging
subsystem allows you to configure the following types of log formatters:
11.7.1. Configure a Pattern Formatter
You can create a named pattern formatter that can be used across log handlers to format log messages.
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 Pattern Formatter
When defining a pattern formatter, you provide a pattern string to use to format log messages. For more information on the pattern syntax, see Format Characters for Pattern Formatter.
/subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:add(pattern=PATTERN)
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 creates log messages formatted like the one 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
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")
You can also configure pattern log formatters using the management console:
- Open the management console in a browser.
-
Choose Configuration
Subsystems Logging. - Select Configuration and then click View.
- Select Formatter and then choose the Pattern Formatter option.
11.7.2. Configure a JSON Log Formatter
You can create a JSON log formatter to format log messages in JSON.
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
.
Add a JSON Log Formatter
/subsystem=logging/json-formatter=JSON_FORMATTER_NAME:add(pretty-print=true, exception-output-type=formatted)
This creates log messages formatted like the one below.
{ "timestamp": "2018-10-18T13:53:43.031-04:00", "sequence": 62, "loggerClassName": "org.jboss.as.server.logging.ServerLogger_$logger", "loggerName": "org.jboss.as", "level": "INFO", "message": "WFLYSRV0025: JBoss EAP 7.4.0.GA (WildFly Core 15.0.2.Final-redhat-00001) started in 5227ms - Started 317 of 556 services (343 services are lazy, passive or on-demand), "threadName": "Controller Boot Thread", "threadId": 22, "mdc": { }, "ndc": "", "hostName": "localhost.localdomain", "processName": "jboss-modules.jar", "processId": 7461 }
Add a Logstash JSON log formatter
You can modify the JSON log formatter output keys and add static metadata. The primary purpose of the JSON log formatter is to format log messages in JSON. Logstash consumes this JSON output and searches for the fields, @timestamp
and @version
. The following example creates a JSON log formatter that formats messages for Logstash.
/subsystem=logging/json-formatter=logstash:add(exception-output-type=formatted, key-overrides=[timestamp="@timestamp"], meta-data=[@version=1])
You can use the JSON formatter attributes as explained below:
-
The
key-overrides
attribute can be used to override the names of the keys defined. -
The exceptions can be formatted as objects by setting the
exception-output-type
attribute toformatted
. -
The exception stack trace can be included by setting the
exception-output-type
attribute todetailed
. -
The exceptions can be formatted as objects and stack traces can be included by setting the
exception-output-type
todetailed-and-formatted
. -
The metadata can be added to log records using the
meta-data
attribute.
For more information on the JSON formatter attributes, see JSON Log Formatter Attributes.
You can also configure JSON log formatters using the management console:
- Open the management console in a browser.
-
Choose Configuration
Subsystems Logging. - Select Configuration and then click View.
- Select Formatter and then choose the JSON Formatter option.
11.7.3. Configure an XML Log Formatter
You can create an XML log formatter to format log messages in XML.
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
.
Add an XML Log Formatter
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, exception-output-type=detailed-and-formatted)
This creates log message formatted like the one below.
<record> <timestamp>2018-10-18T13:55:53.419-04:00</timestamp> <sequence>62</sequence> <loggerClassName>org.jboss.as.server.logging.ServerLogger_$logger</loggerClassName> <loggerName>org.jboss.as</loggerName> <level>INFO</level> <message>WFLYSRV0025: {ProductCurrentVersionExamples} (WildFly Core 10.0.0.Final-redhat-20190924) started in 6271ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)</message> <threadName>Controller Boot Thread</threadName> <threadId>22</threadId> <mdc> </mdc> <ndc></ndc> <hostName>localhost.localdomain</hostName> <processName>jboss-modules.jar</processName> <processId>7790</processId> </record>
Add a Key Override XML Log Formatter
/subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, print-namespace=true, namespace-uri="urn:custom:1.0", key-overrides={message=msg, record=logRecord, timestamp=date}, print-details=true)
You can use the XML formatter attributes as explained below:
-
The
key-overrides
attribute can be used to override the names of the keys defined. -
The exceptions can be formatted as objects by setting the
exception-output-type
attribute toformatted
. -
The exception stack trace can be included by setting the
exception-output-type
attribute todetailed
. -
The exceptions can be formatted as objects and stack traces can be included by setting the
exception-output-type
todetailed-and-formatted
. -
The metadata can be added to log records using the
meta-data
attribute.
For more information on the XML formatter attributes, see XML Log Formatter Attributes.
You can also configure XML log formatters using the management console:
- Open the management console in a browser.
-
Choose Configuration
Subsystems Logging. - Select Configuration and then click View.
- Select Formatter and then choose the XML Formatter option.
11.7.4. 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.
Configure a Custom Log Formatter
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
.
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
.NoteYou 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)
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)
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>
Configure a Custom Log Formatter Using the Management Console
You can also configure log formatters using the management console.
- Open the management console in a browser.
-
Choose Configuration
Subsystems Logging. - Select Configuration and then click View.
- Select Formatter and then choose the Custom Formatter option.
11.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.
11.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.
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.
11.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 tofalse
.The
use-deployment-logging-config
attribute controls whether or not your deployment is scanned for per-deployment logging. This defaults totrue
by default. You can set this attribute tofalse
to disable per-deployment logging./subsystem=logging:write-attribute(name=use-deployment-logging-config,value=false)
Exclude the
logging
subsystem using ajboss-deployment-structure.xml
file.For instructions, see Exclude a Subsystem from a Deployment in the JBoss EAP Development Guide.
11.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.
Each logging profile can have:
- A unique name. This value is 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.
11.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. Logging profiles can also be configured using the management console by navigating to Configuration
Create the logging profile.
/subsystem=logging/logging-profile=PROFILE_NAME:add
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.
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.
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.
11.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
11.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 thelogging
subsystem. This will output thelogging
subsystem configuration. -
profile-PROFILE_NAME
, if the deployment is using a logging profile defined in thelogging
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)
11.9. Tuning the Logging Subsystem
For tips on monitoring and optimizing performance for the logging
subsystem, see the Logging Subsystem Tuning section of the Performance Tuning Guide.