= 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.

====
