WildFly Logging Subsystem Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(45 intermediate revisions by the same user not shown)
Line 11: Line 11:
The logging subsystem is based on JBoss LogManager and supports several third-party application logging frameworks, in addition to JBoss Logging: Apache Commons Logging, Simple Logging Facade for Java (SLF4J), Apache log4j and Java SE logging (java.util.logging).
The logging subsystem is based on JBoss LogManager and supports several third-party application logging frameworks, in addition to JBoss Logging: Apache Commons Logging, Simple Logging Facade for Java (SLF4J), Apache log4j and Java SE logging (java.util.logging).


=Category=
=Default Configuration=


A log category defines what messages to capture.
<pre>
<subsystem xmlns="urn:jboss:domain:logging:1.5">
    <console-handler name="CONSOLE">
        <level name="INFO"/>
        <formatter>
            <named-formatter name="COLOR-PATTERN"/>
        </formatter>
    </console-handler>
    <periodic-rotating-file-handler name="FILE" autoflush="true">
        <formatter>
            <named-formatter name="PATTERN"/>
        </formatter>
        <file relative-to="jboss.server.log.dir" path="server.log"/>
        suffix value=".yyyy-MM-dd"/>
        <append value="true"/>
    </periodic-rotating-file-handler>
    <logger category="com.arjuna">
        <level name="WARN"/>
    </logger>
    ...
    <root-logger>
        <level name="INFO"/>
        <handlers>
            <handler name="CONSOLE"/>
            <handler name="FILE"/>
        </handlers>
    </root-logger>
    <formatter name="PATTERN">
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
    <formatter name="COLOR-PATTERN">
        <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
</subsystem>
</pre>
 
=Logger=
 
==Root Logger==
 
The root logger captures all log messages (of a specified level) ''that are not captured by a log category''.
 
==Category==
 
A log category defines what messages to capture, and optionally, a log handler to process those messages. If no log handler is explicitly specified, the category will send logging to the handlers configured on the root logger. The log messages to capture are defined by their Java package of origin.
 
A log category is assigned a [[#Level|log level]] and it only process log messages of that level or higher.
 
This is how an explicit log handler is specified on a category:
 
<syntaxhighlight lang='xml'>
...
<logger category="com.example">
  <level name="DEBUG"/>
  <handlers>
      <handler name="MY_OWN_HANDLER"/>
  </handlers>
</logger>
...
</syntaxhighlight>
 
The custom handler must be declared in the subsystem.
 
More about categories is available here: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-The_Logging_Subsystem.html#About_Log_Categories


=Handler=
=Handler=


A log handler defines how to deal with generated log messages.
A log handler defines how to deal with generated log messages.  
 
A handler is assigned a [[#Level|log level]] and it only process log messages of that level or higher.
 
The available log handlers are the following:
 
==Console==
 
Console log handlers write log messages to either the host operating system's standard out (stdout) or standard error (stderr) stream. Those messages are not saved by default.
 
==File==
 
==Periodic==
 
Periodic log handlers write 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.
 
Specified as:
 
<pre>
<periodic-size-rotating-file-handler ...>
    ...
</periodic-size-rotating-file-handler>
</pre>
 
For a configuration example and details, see:
 
{{Internal|WildFly_Logging_Subsystem_Configuration#Periodic_Rotating_File_Handler_Configuration|Periodic Rotating File Handler Configuration Example}}
 
==Size==
 
Size log handlers write log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric 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.
 
Specified as:
 
<pre>
<size-rotating-file-handler ...>
  ...
</size-rotating-file-handler>
</pre>
 
{{Internal|WildFly_Logging_Subsystem_Configuration#Size_Rotating_File_Handler_Configuration|Size Rotating File Handler Configuration Example}}
 
==Async==
 
A wrapper that provides asynchronous behavior for one of the available handlers. Used to work around the high latency of the delegate handlers.
 
==syslog==
 
Syslog handlers can be used to send messages to a remote logging server.
 
==Periodic Size==
 
A combination of the [[#Periodic|Periodic]] and [[#Size|Size]] handlers: once the current log file reaches the specified size, or the specified time period has passed, the file is renamed and the handler continues to write to a newly created log file with the original name. Attributes of both handlers are supported
 
==Custom==
 
A custom handler must extend <tt>java.util.logging.Handler</tt> and be contained in a module.
 
=Level=
 
Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message.
 
The level of a given log message is specified by the developer using method specific to chosen logging framework.
 
Log levels are used by log [[#Category|categories]] and [[#Handler|handlers]] to limit the messages they are responsible for. Log categories and handlers are assigned a log level and they only process log messages of that level or higher.
 
JBoss supports all the log levels used by the supported application logging frameworks.
 
==FINEST==
 
Value: 300
 
==FINER==
 
Value: 400
 
==TRACE==
 
Value: 400. Should be used for messages that provide detailed information about the running state of an application, and they should only be captured when debugging the application.
 
==DEBUG==
 
Value: 500.  DEBUG messages should only be captured when debugging an application.
 
==FINE==
 
Value: 500.
 
==CONFIG==
 
Value: 700
 
==INFO==
 
Value: 800. Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.
 
==WARN==
 
Value: 900. Use to indicate a situation that is not in error but is not considered ideal. May indicate circumstances that may lead to errors in the future.
 
==WARNING==
 
Value: 900.
 
==ERROR==
 
Value 1000. Use to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.
 
==SEVERE==
 
Value 1000.
 
==FATAL==
 
Value 1100. Use to indicate events that could cause critical service failure and application shutdown and possibly application server shutdown.
 
=Filter=
 
Filter expressions can be used to filter log messages based on various criteria. The filter is always applied on the raw log message. Filters can be added for a [[#Logger|logger]] or a [[#Handler|handler]]. If a filter is added to a logger ''and'' a handler, the logger filter takes precedence.
 
A filter expression is specified by the <tt>filter-spec</tt> element.
 
=Log Formatter=
 
A log formatter is the configuration property of a [[#Handler|log handler]] that defines the appearance of log messages from that handler. It is a string that uses a syntax based on <tt>java.util.Formatter</tt> class.
 
<blockquote style="background-color: AliceBlue; border: solid thin LightSteelBlue;">
:[https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-The_Logging_Subsystem.html#Log_Formatter_Syntax1 Log Formatter Syntax]<br>
</blockquote>


=Logging Profile=
=Logging Profile=
Line 33: Line 224:
=Garbage Collection Logging=
=Garbage Collection Logging=


GC logging is enabled by default for standalone mode. It generates output to $JBOSS_HOME/standalone/log/gc.log.<digit>. The system uses log rotation with the number of log files limited to 5, and the size of each file limited to 3 MB.
<blockquote style="background-color: #f9f9f9; border: solid thin lightgrey;">
:[[WildFly and Garbage Collection Logging]]
</blockquote>


=Logging Dependencies Exposed to Deployments=
=Logging Dependencies Exposed to Deployments=


Whether logging dependencies are exposed or not to deployments is controlled by the <tt>add-logging-api-dependencies</tt> attribute of the logging subsystem. By default the attribute is set to true.
Whether logging dependencies are exposed or not to deployments is controlled by the <tt>add-logging-api-dependencies</tt> attribute of the logging subsystem. By default the attribute is set to true.

Latest revision as of 17:56, 20 September 2017

External

Internal

Overview

The logging subsystem is based on JBoss LogManager and supports several third-party application logging frameworks, in addition to JBoss Logging: Apache Commons Logging, Simple Logging Facade for Java (SLF4J), Apache log4j and Java SE logging (java.util.logging).

Default Configuration

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

Logger

Root Logger

The root logger captures all log messages (of a specified level) that are not captured by a log category.

Category

A log category defines what messages to capture, and optionally, a log handler to process those messages. If no log handler is explicitly specified, the category will send logging to the handlers configured on the root logger. The log messages to capture are defined by their Java package of origin.

A log category is assigned a log level and it only process log messages of that level or higher.

This is how an explicit log handler is specified on a category:

...
<logger category="com.example">
   <level name="DEBUG"/>
   <handlers>
       <handler name="MY_OWN_HANDLER"/>
   </handlers>
</logger>
...

The custom handler must be declared in the subsystem.

More about categories is available here: https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/chap-The_Logging_Subsystem.html#About_Log_Categories

Handler

A log handler defines how to deal with generated log messages.

A handler is assigned a log level and it only process log messages of that level or higher.

The available log handlers are the following:

Console

Console log handlers write log messages to either the host operating system's standard out (stdout) or standard error (stderr) stream. Those messages are not saved by default.

File

Periodic

Periodic log handlers write 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.

Specified as:

<periodic-size-rotating-file-handler ...>
    ...
</periodic-size-rotating-file-handler>

For a configuration example and details, see:

Periodic Rotating File Handler Configuration Example

Size

Size log handlers write log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric 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.

Specified as:

<size-rotating-file-handler ...>
   ...
</size-rotating-file-handler>
Size Rotating File Handler Configuration Example

Async

A wrapper that provides asynchronous behavior for one of the available handlers. Used to work around the high latency of the delegate handlers.

syslog

Syslog handlers can be used to send messages to a remote logging server.

Periodic Size

A combination of the Periodic and Size handlers: once the current log file reaches the specified size, or the specified time period has passed, the file is renamed and the handler continues to write to a newly created log file with the original name. Attributes of both handlers are supported

Custom

A custom handler must extend java.util.logging.Handler and be contained in a module.

Level

Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message.

The level of a given log message is specified by the developer using method specific to chosen logging framework.

Log levels are used by log categories and handlers to limit the messages they are responsible for. Log categories and handlers are assigned a log level and they only process log messages of that level or higher.

JBoss supports all the log levels used by the supported application logging frameworks.

FINEST

Value: 300

FINER

Value: 400

TRACE

Value: 400. Should be used for messages that provide detailed information about the running state of an application, and they should only be captured when debugging the application.

DEBUG

Value: 500. DEBUG messages should only be captured when debugging an application.

FINE

Value: 500.

CONFIG

Value: 700

INFO

Value: 800. Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.

WARN

Value: 900. Use to indicate a situation that is not in error but is not considered ideal. May indicate circumstances that may lead to errors in the future.

WARNING

Value: 900.

ERROR

Value 1000. Use to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.

SEVERE

Value 1000.

FATAL

Value 1100. Use to indicate events that could cause critical service failure and application shutdown and possibly application server shutdown.

Filter

Filter expressions can be used to filter log messages based on various criteria. The filter is always applied on the raw log message. Filters can be added for a logger or a handler. If a filter is added to a logger and a handler, the logger filter takes precedence.

A filter expression is specified by the filter-spec element.

Log Formatter

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

Log Formatter Syntax

Logging Profile

A logging profile is a named set of logging configurations, which can be created and assigned to applications.

Boot Logging

Details about the Java environment and component service startup are logged during the JBoss instance startup in the server.log file. The configuration of boot logging is specified in the configuration file logging.properties. The location of the configuration file defense on the mode in which JBoss runs ($JBOSS_HOME/standalone/configuration/logging.properties, $JBOSS_HOME/domain/configuration/logging.properties for the domain controller and $JBOSS_HOME/domain/servers/<server-name>/data/logging.properties.

The start of the boot sequence is marked by "JBAS015899".

logging.properties is active until the logging subsystem is started and takes over.

Garbage Collection Logging

WildFly and Garbage Collection Logging

Logging Dependencies Exposed to Deployments

Whether logging dependencies are exposed or not to deployments is controlled by the add-logging-api-dependencies attribute of the logging subsystem. By default the attribute is set to true.