Skip to end of metadata
Go to start of metadata


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:


Per-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:

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
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 15, 2012

    It would be useful to have a section which explains the role that

    /standalone/configuration/logging.properties

    has and whether it overrides the standalone.xml logging configuration.

    The standalone.bat file includes the system property

    -Dlogging.configuration=....../standalone/configuration/logging.properties

    which suggests it does play a role?

    1. May 30, 2012

      Hello Peter

      The answer is in this same page: Why is there a logging.properties file?

  2. Mar 09, 2013

    Hi

    Can i use logback db appender as a custom -handler..?

    1. Mar 10, 2013

      The forums are really a better place to ask questions like this, https://community.jboss.org/en/jbossas7. That said, no you cannot use logback appenders, but you can use log4j appenders as a custom-handler.

  3. Jul 15, 2013

    Attribute name is missing from syslog-handler table.

    The XML should look like:

    <syslog-handler name="MySyslogHandlerName" >

    ....

    </syslog-handler> 

  4. Nov 14, 2013

    Would love an explanation of the relation between the logging levels in the <root-logger>, the <logger> and the different handlers.

    Is the relation that the root-logger sets the default level unless otherwise defined for any logger when logging to any of the handlers referred in the root-logger? And that the handlers' levels are filters that discards anything with a less significant level, regardless of root-logger and logger settings?

    1. Nov 14, 2013

      You got it. The root-logger is somewhat of a default logger. If you have not defined a specific category in the configuration, the root-logger configuration will be used.

      If a message is said to be loggable by the logger, then the handler checks and only publishes the record if the handler also determines the message is loggable.

  5. Dec 11, 2013

    I would like to add per deployment logging. I can see how you add an entry to the deployments MANIFEST.MF, but don't know how to then create the corresponding profile. Presumably it will be an XML file containing similar XML defined for the <subsystem xmlns="urn:jboss:domain:logging:1.2"> element in the standalone.xml?

    What would the xml file be called? Where would it be placed?

    Note: we dumped log4j when we switched to JBoss 7.

    Any extra info would be appreciated.

  6. Jun 02, 2014

    The following configuration files are allowed:

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

    It seems clear that files log4j.properties, log4j.xml and jboss-log4j.xml should contain the log4j configuration syntax, being the properties or XML syntax according to the file name suffix.

    What syntax is used to configure the application using files logging.properties and jboss-logging.properties ?