Logging Configuration - JBoss AS 7.2

Overview

The overall server logging configuration is represented by the logging subsystem. It consists of four notable parts: handler configurations, logger, the root logger declarations (aka log categories) and logging profiles. Each logger does reference a handler (or set of handlers). Each handler declares the log format and output:

<subsystem xmlns="urn:jboss:domain:logging:1.0">
   <console-handler name="CONSOLE" autoflush="true">
       <level name="DEBUG"/>
       <formatter>
           <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
       </formatter>
   </console-handler>
   <periodic-rotating-file-handler name="FILE" autoflush="true">
       <formatter>
           <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
       </formatter>
       <file relative-to="jboss.server.log.dir" path="server.log"/>
       <suffix value=".yyyy-MM-dd"/>
   </periodic-rotating-file-handler>
   <logger category="com.arjuna">
       <level name="WARN"/>
   </logger>
   [...]
   <root-logger>
       <level name="DEBUG"/>
       <handlers>
           <handler name="CONSOLE"/>
           <handler name="FILE"/>
       </handlers>
   </root-logger>
</subsystem>

deployment Logging

Per-deployment logging allows you to add a logging configuration file to your deployment and have the logging for that deployment configured according to the configuration file. In an EAR the configuration should be in the META-INF directory. In a WAR or JAR deployment the configuration file can be in either the META-INF or WEB-INF/classes directories.

The following configuration files are allowed:

logging.properties
jboss-logging.properties
log4j.properties
log4j.xml
jboss-log4j.xml

You can also disable this functionality system wide by adding the -Dorg.jboss.as.logging.per-deployment=false system property.

Logging Profiles

Logging profiles are like additional logging subsystems. Each logging profile constists of three of the four notable parts listed above: handler configurations, logger and the root logger declarations.

You can assign a logging profile to a deployment via the deployments manifest. Add a Logging-Profile entry to the MANIFEST.MF file with a value of the logging profile id. For example a logging profile defined on /subsystem=logging/logging-profile=ejbs the MANIFEST.MF would look like:

Manifest-Version: 1.0
Logging-Profile: ejbs

A logging profile can be assigned to any number of deployments. Using a logging profile also allows for runtime changes to the configuration. This is an advantage over the per-deployment logging configuration as the redeploy is not required for logging changes to take affect.

Why is there a logging.properties file?

You may have noticed that there is a logging.properties file in the configuration directory. This is logging configuration is used when the server boots up until the logging subsystem kicks in. If the logging subsystem is not included in your configuration, then this would act as the logging configuration for the entire server.

In the future this file may go away or be automatically generated from the logging subsystem. For most users this file should not be modified.

Default Log File Locations

Managed Domain

In a managed domain two types of log files do exist: Controller and server logs. The controller components govern the domain as whole. It's their responsibility to start/stop server instances and execute managed operations throughout the domain. Server logs contain the logging information for a particular server instance. They are co-located with the host the server is running on.

For the sake of simplicity we look at the default setup for managed domain. In this case, both the domain controller components and the servers are located on the same host:

Process	Log File
Host Controller	./domain/log/host-controller/boot.log
Process Controller	./domain/log/process-controller/boot.log
"Server One"	./domain/servers/server-one/log/boot.log
"Server One"	./domain/servers/server-one/log/server.log
"Server Three"	./domain/servers/server-three/log/boot.log
"Server Three"	./domain/servers/server-three/log/server.log

The server logs as you know it from previous JBoss AS versions are located in the servers subdirectory: I.e. ./domain/servers/server-three/log/server.log

Standalone Server

The default log files for a standalone server can be found in the log subdirectory of the distribution:

Process	Log File
Server	./standalone/log/boot.log
Server	./standalone/log/server.log

Filter Expressions

Filter Type	Expression	Description	Parameter(s)	Examples
accept	accept	Accepts all log messages.	None	accept
deny	deny	enies all log messages.	None	deny
not	not(filterExpression)	Accepts a filter as an argument and inverts the returned value.	The expression takes a single filter for it's argument.	not(match("JBAS"))
all	all(filterExpressions)	A filter consisting of several filters in a chain. If any filter find the log message to be unloggable, the message will not be logged and subsequent filters will not be checked.	The expression takes a comma delimited list of filters for it's argument.	all(match("JBAS"), match("WELD"))
any	any(filterExpressions)	A filter consisting of several filters in a chain. If any filter fins the log message to be loggable, the message will be logged and the subsequent filters will not be checked.	The expression takes a comma delimited list of filters for it's argument.	any(match("JBAS"), match("WELD"))
levelChange	levelChange(level)	A filter which modifies the log record with a new level.	The expression takes a single string based level for it's argument.	levelChange(WARN)
levels	levels(levels)	A filter which includes log messages with a level that is listed in the list of levels.	The expression takes a comma delimited list of string based levels for it's argument.	levels(DEBUG, INFO, WARN, ERROR)
levelRange	levelRange([minLevel,maxLevel])	A filter which logs records that are within the level range.	The filter expression uses a "[" to indicate a minimum inclusive level and a "]" to indicate a maximum inclusive level. Otherwise use "(" or ")" respectively indicate exclusive. The first argument for the expression is the minimum level allowed, the second argument is the maximum level allowed.	minimum level must be greater than DEBUG and the maximum level must be less than to ERROR levelRange(DEBUG, ERROR) minimum level must be greater than or equal to DEBUG and the maximum level must be less than ERROR levelRange[DEBUG, ERROR) minimum level must be greater than or equal to INFO and the maximum level must be less than or equal to ERROR levelRange[INFO, ERROR]
match	match("pattern")	A regular-expression based filter. The raw unformatted message is used against the pattern.	The expression takes a regular expression for it's argument. match("JBAS\d+")
substitute	substitute("pattern", "replacement value")	A filter which replaces the first match to the pattern with the replacement value.	The first argument for the expression is the pattern the second argument is the replacement text.	substitute("JBAS", "EAP")
substituteAll	substituteAll("pattern", "replacement value")	A filter which replaces all matches of the pattern with the replacement value.	The first argument for the expression is the pattern the second argument is the replacement text.	substituteAll("JBAS", "EAP")

Logging Subsystem Descriptions

async-handler

Defines a handler which writes to the sub-handlers in an asynchronous thread. Used for handlers which introduce a substantial amount of lag.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
overflow-action	Specify what action to take when the overflowing. The valid options are 'block' and 'discard'	STRING	false	true	read-write	no-services	BLOCK	BLOCK DISCARD
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
queue-length	The queue length to use before flushing writing	INT	false	true	read-write	resource-services	null	Any
subhandlers	The Handlers associated with this async handler.	LIST	true	false	read-write	no-services	null	Any
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any

console-handler

Defines a handler which writes to the console.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
autoflush	Automatically flush after each write.	BOOLEAN	true	true	read-write	no-services	true	Any
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any
target	Defines the target of the console handler. The value can either be SYSTEM_OUT or SYSTEM_ERR.	STRING	true	true	read-write	no-services	System.out	System.out System.err

custom-handler

Defines a custom logging handler. The custom handler must extend java.util.logging.Handler.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
module	The module that the logging handler depends on.	STRING	false	false	read-only		null	Any
class	The logging handler class to be used.	STRING	false	false	read-only		null	Any
properties	Defines the properties used for the logging handler. All properties must be accessible via a setter method.	OBJECT	true	true	read-write	no-services	null	Any
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any

file-handler

Defines a handler which writes to a file.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
append	Specify whether to append to the target file.	BOOLEAN	true	true	read-write	resource-services	true	Any
autoflush	Automatically flush after each write.	BOOLEAN	true	true	read-write	no-services	true	Any
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
file	The file description consisting of the path and optional relative to path.	OBJECT	true	false	read-write	no-services	null	Any
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any

logger

Defines a logger category.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
use-parent-handlers	Specifies whether or not this logger should send its output to it's parent Logger.	BOOLEAN	true	true	read-write	no-services	true	Any
category	Specifies the category for the logger.	STRING	true	false	read-only		null	Any
handlers	The Handlers associated with this Logger.	LIST	true	false	read-write	no-services	null	Any

periodic-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a time period derived from the given suffix string, which should be in a format understood by java.text.SimpleDateFormat.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
append	Specify whether to append to the target file.	BOOLEAN	true	true	read-write	resource-services	true	Any
autoflush	Automatically flush after each write.	BOOLEAN	true	true	read-write	no-services	true	Any
suffix	Set the suffix string. The string is in a format which can be understood by java.text.SimpleDateFormat. The period of the rotation is automatically calculated based on the suffix.	STRING	false	true	read-write	no-services	null	Any
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
file	The file description consisting of the path and optional relative to path.	OBJECT	true	false	read-write	no-services	null	Any
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any

root-logger

Defines the root logger for this log context.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
handlers	The Handlers associated with this Logger.	LIST	true	false	read-write	no-services	null	Any

size-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a the size of the file grows beyond a certain point and keeping a fixed number of backups.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
append	Specify whether to append to the target file.	BOOLEAN	true	true	read-write	resource-services	true	Any
autoflush	Automatically flush after each write.	BOOLEAN	true	true	read-write	no-services	true	Any
rotate-size	The size at which to rotate the log file.	STRING	false	true	read-write	no-services	2m	Any
formatter	Defines a pattern for the formatter.	STRING	true	true	read-write	no-services	%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n	Any
filter-spec	A filter expression value to define a filter. Example for a filter that does not match a pattern: not(match("JBAS.*"))	STRING	true	true	read-write	no-services	null	See Filter Expression
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
max-backup-index	The maximum number of backups to keep.	INT	true	true	read-write	no-services	1	Any
file	The file description consisting of the path and optional relative to path.	OBJECT	true	false	read-write	no-services	null	Any
name	The handler's name.	STRING	true	false	read-only		null	Any
encoding	The character encoding used by this Handler.	STRING	true	true	read-write	no-services	null	Any

syslog-handler

Defines a syslog handler.

Attribute	Description	Type	Allow Null	Expression Allowed	Access Type	Restart Required	Default Value	Allowed Values
port	The port the syslog server is listening on.	INT	true	true	read-write	no-services	514	Any
app-name	The app name used when formatting the message in RFC5424 format. By default the app name is "java".	STRING	true	true	read-write	no-services	null	Any
enabled	If set to true the handler is enabled and functioning as normal, if set to false the handler is ignored when processing log messages.	BOOLEAN	true	true	read-write	no-services	true	Any
level	The log level specifying which message levels will be logged by this logger. Message levels lower than this value will be discarded.	STRING	true	true	read-write	no-services	ALL	ALL FINEST FINER TRACE DEBUG FINE CONFIG INFO WARN WARNING ERROR FATAL OFF
facility	Facility as defined by RFC-5424 and RFC-3164.	STRING	true	true	read-write	no-services	user-level	kernel user-level mail-system system-daemons security syslogd line-printer network-news uucp clock-daemon security2 ftp-daemon ntp log-audit log-alert clock-daemon2 local-use-0 local-use-1 local-use-2 local-use-3 local-use-4 local-use-5 local-use-6 local-use-7
server-address	The address of the syslog server.	STRING	true	true	read-write	no-services	localhost	Any
hostname	The name of the host the messages are being sent from. For example the name of the host the application server is running on.	STRING	true	true	read-write	no-services	null	Any
syslog-format	Formats the log message according to the RFC specification.	STRING	true	true	read-write	no-services	RFC5424	RFC5424 RFC3164
name	The handler's name	STRING	true	false	read-only		null	Any