= Handlers
:author:            James R. Perkins
:email:             jperkins@redhat.com

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

== Overview

Handlers define how log messages are recorded. If a message is said to be
{oracle-javadocs}/java.logging/java/util/logging/Logger.html#isLoggable-java.util.logging.Level-[loggable] by a
<<Logging_Loggers,logger>> the message is then processed by the log handler.

The following are the available handlers for {appservername};

* <<async-handler,async-handler>>
* <<console-handler,console-handler>>
* <<custom-handler,custom-handler>>
* <<file-handler,file-handler>>
* <<periodic-rotating-file-handler,periodic-rotating-file-handler>>
* <<periodic-size-rotating-file-handler,periodic-size-rotating-file-handler>>
* <<size-rotating-file-handler,size-rotating-file-handler>>
* <<socket-handler,socket-handler>>
* <<syslog-handler,syslog-handler>>

=== async-handler

An `async-handler` is a handler that asynchronously writes log messages to it's child handlers. This type of
handler is generally used to wrap other handlers that take a substantial time to write messages.

=== console-handler

A `console-handler` is a handler that writes log messages to the console. Generally this writes to `stdout`,
but can be set to write to `stderr`.

=== custom-handler

A `custom-handler` allows you to define any {oracle-javadoc}/java.logging/java/util/logging/Handler.html[handler] as a handler that
can be assigned to a logger or a <<async-handler,`async-handler`>>.

=== file-handler

A `file-handler` is a handler that writes log messages to the specified file.

=== periodic-rotating-file-handler

A `periodic-rotating-file-handler` is a handler that writes log messages to the specified file. The file rotates on
the date pattern specified in the `suffix` attribute. The suffix must be a valid pattern recognized by the
{oracle-javadoc}/java.base/java/text/SimpleDateFormat.html[`java.text.SimpleDateFormat`] and must not rotate on seconds or
milliseconds.

NOTE: The rotate happens before the next message is written by the handler.

=== periodic-size-rotating-file-handler

A `periodic-size-rotating-file-handler` is a handler that writes log messages to the specified file. The file rotates on
the date pattern specified in the `suffix` attribute or the `rotate-size` attribute. The suffix must be a valid
pattern recognized by the {oracle-javadoc}/java.base/java/text/SimpleDateFormat.html[`java.text.SimpleDateFormat`] and must
not rotate on seconds or milliseconds.

The `max-backup-index` works differently on this handler than the
<<size-rotating-file-handler,`size-rotating-file-handler`>>. The date suffix of the file to be rotated must be the
same as the current expected suffix. For example with a suffix pattern of `yyyy-MM` and a `rotate-size` of `10m` the
file will be rotated with the current month each time the 10Mb size is reached.

NOTE: The rotate happens before the next message is written by the handler.

=== size-rotating-file-handler

A `size-rotating-file-handler` is a handler that writes log messages to the specified file. The file rotates when
the file size is greater than the `rotate-size` attribute. The rotated file will be kept and the index appended
to the name moving previously rotated file indexes up by 1 until the `max-backup-index` is reached. Once the
`max-backup-index` is reached, the indexed files will be overwritten.

NOTE: The rotate happens before the next message is written by the handler.

=== socket-handler

A `socket-handler` is a handler which sends messages over a socket. This can be a TCP or UDP socket and must be
defined in a <<socket-binding-groups,socket binding group>> under the `local-destination-outbound-socket-binding` or
`remote-destination-outbound-socket-binding` resource.

During the boot logging messages will be queued until the socket binding is configured and the `logging` subsystem is
added. This is important to note because setting the level of the handler to `DEBUG` or `TRACE` could result in
large memory consumption during boot.

[IMPORTANT]
====
A server booted in `--admin-only` mode will discard messages rather than send them over a socket.
====

.CLI Example
[source,options="nowrap"]
----
# 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 handler
/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server)
# Add the handler to the root logger
/subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)
----

.Add a UDP Example
[source,options="nowrap"]
----
/subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=UDP)
----

.Add SSL Example
[source,options="nowrap"]
----
# Add the socket binding
/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)

# Add the Elytron key store
/subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.pkcs12, type=PKCS12, credential-reference={clear-text=mypassword})
# Add the Elytron 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 a json-formatter
/subsystem=logging/json-formatter=json:add
# Add the socket 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)
# Add the handler to the root logger
/subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)
----

TIP: Wrapping a `socket-handler` in a <<async-handler,`async-handler`>> may improve performance.

=== syslog-handler

A `syslog-handler` is a handler that writes to a syslog server via UDP. The handler support
http://www.ietf.org/rfc/rfc3164.txt[RFC3164] or http://www.ietf.org/rfc/rfc5424.txt[RFC5424] formats.

[TIP]
====

The syslog-handler is missing some configuration properties that may be
useful in some scenarios like setting a formatter. Use the
`org.jboss.logmanager.handlers.SyslogHandler` in module
`org.jboss.logmanager` as a
<<custom-handler,custom-handler>> to exploit
these benefits. Additional attributes will be added at some point so
this will no longer be necessary.

====
