vy commented on code in PR #2797: URL: https://github.com/apache/logging-log4j2/pull/2797#discussion_r1705421334
########## src/site/antora/modules/ROOT/pages/manual/appenders/message-queue.adoc: ########## @@ -0,0 +1,1211 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Message Queue Appenders Review Comment: ```suggestion = Message queue appenders ``` ########## src/site/antora/modules/ROOT/pages/manual/appenders/message-queue.adoc: ########## @@ -0,0 +1,1211 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Message Queue Appenders +:open-book: 📖 + Review Comment: ```suggestion This page guides you through message queue xref:manual/appenders.adoc[appenders] that forward log events to a message broker. ``` ########## src/site/antora/modules/ROOT/pages/manual/appenders/message-queue.adoc: ########## Review Comment: This is missing in `nav.adoc`. ########## src/site/antora/modules/ROOT/pages/manual/appenders.adoc: ########## @@ -212,603 +213,360 @@ See xref:manual/configuration.adoc#lazy-property-substitution[runtime property s Log4j bundles several predefined appenders to assist in several common deployment use cases. They are documented in separate pages based on their target resource: -[#file-appenders] -=== File appenders - -File appenders write logs to the filesystem. -They can be further split into: - -Single file appenders::: -See xref:manual/appenders/file.adoc[] for details. +[#ConsoleAppender] +=== Console Appender -Rolling file appenders::: -See xref:manual/appenders/rolling-file.adoc[] for details. - -[#database-appenders] -=== Database appenders - -The appenders write log events directly to a database. +As one might expect, the Console Appender writes its output to either the standard output or standard error output. +The appender supports four different ways to access the output streams: -xref:manual/appenders/database.adoc#CassandraAppender[Cassandra appender]:: -Sends log events to -https://cassandra.apache.org/_/index.html[Apache Cassandra] - -xref:manual/appenders/database.adoc#JdbcAppender[JDBC appender]:: -Sends log events to a JDBC driver - -xref:manual/appenders/database.adoc#JpaAppender[JPA appender]:: -Uses Jakarta Persistence API to deliver log events to a database - -xref:manual/appenders/database.adoc#NoSqlAppender[NoSQL appender]:: -Store log events to a document-oriented database - -See xref:manual/appenders/database.adoc[] for details. +`direct`:: +This mode gives the best performance. +It can be enabled by setting the <<ConsoleAppender-attr-direct,`direct`>> attribute to `true`. -[#network-appenders] -=== Network appenders - -These appenders use simple network protocols to transmit log events to a remote host. -The supported network protocols are: - -`UDP`:: -`TCP`:: -These are handled by the xref:manual/appenders/network.adoc#SocketAppender[Socket Appender]. - -`HTTP`:: -This is handled by the xref:manual/appenders/network.adoc#HttpAppender[HTTP Appender]. - -`SMTP`:: -This is handled by the xref:manual/appenders/network.adoc#HttpAppender[SMTP Appender]. - -See xref:manual/appenders/network.adoc[] for details. - -[#delegating-appenders] -=== Delegating appenders - -Delegating appenders are intended to decorate other appenders: - -xref:manual/appenders/delegating.adoc#AsyncAppender[Asynchronous appender]:: -Perform all I/O on a dedicated thread - -xref:manual/appenders/delegating.adoc#FailoverAppender[Failover appender]:: -Provide a backup appender in case an appender fails +`default`:: +By default, the Console appender uses the values of `System.out` or `System.err` present at **configuration time**. +Any changes to those streams at runtime will be ignored. -xref:manual/appenders/delegating.adoc#RewriteAppender[Rewrite appender]:: -Modify log events prior to delivering them to the target +`follow`:: +This mode always uses the **current** value of the `System.out` and `System.err` streams. +It can be enabled by setting the <<ConsoleAppender-attr-follow,`follow`>> attribute to `true`. ++ +[TIP] +==== +This setting might be useful in multi-application environments. +Some application servers modify `System.out` and `System.err` to always point to the currently running application. +==== -xref:manual/appenders/delegating.adoc#RoutingAppender[Routing appender]:: -Dynamically choose a different appender for each log event +`JANSI`:: +If the application is running on Windows and the +https://fusesource.github.io/jansi/[JANSI library] +is available, the Console appender will use JANSI to emulate ANSI sequence support. +This mode can be disabled by setting the +xref:manual/systemproperties.adoc#log4j2.skipJansi[`log4j2.skipJansi`] +configuration attribute to `true`. ++ +Additional runtime dependencies are required to use JANSI: ++ +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<dependency> + <groupId>org.fusesource.jansi</groupId> + <artifactId>jansi</artifactId> + <version>{jansi-version}</version> +</dependency> -See xref:manual/appenders/delegating.adoc[] for details. +---- -[id=consoleappender] -=== [[ConsoleAppender]] ConsoleAppender - -As one might expect, the ConsoleAppender writes its output to either -`System.out` or `System.err` with `System.out` being the default target. -A Layout must be provided to format the LogEvent. - -.ConsoleAppender Parameters -[cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|filter |Filter |A Filter to determine if the event should be handled by -this Appender. More than one Filter may be used by using a -CompositeFilter. - -|layout |Layout |The Layout to use to format the LogEvent. If no layout -is supplied the default pattern layout of "%m%n" will be used. - -|follow |boolean |Identifies whether the appender honors reassignments -of `System.out` or `System.err` via `System.setOut` or `System.setErr` made -after configuration. Note that the follow attribute cannot be used with -Jansi on Windows. Cannot be used with `direct`. - -|direct |boolean |Write directly to `java.io.FileDescriptor` and bypass -`java.lang.System.out/.err`. Can give up to 10x performance boost when -the output is redirected to a file or other process. Cannot be used with -Jansi on Windows. Cannot be used with `follow`. The output will not respect -`java.lang.System.setOut()/.setErr()` and may get intertwined with other -output to `java.lang.System.out/.err` in a multi-threaded application. -_New since 2.6.2. Be aware that this is a new addition, and it has only -been tested with Oracle JVM on Linux and Windows so far._ - -|name |String |The name of the Appender. - -|ignoreExceptions |boolean |The default is `true`, causing exceptions -encountered while appending events to be internally logged and then -ignored. When set to `false` exceptions will be propagated to the -caller, instead. You must set this to `false` when wrapping this -Appender in a <<FailoverAppender>>. - -|target |String |Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is -"SYSTEM_OUT". -|======================================================================= - -A typical Console configuration might look like: - -[source,xml,prettyprint,linenums] +Gradle:: ++ +[source,groovy,subs="+attributes"] ---- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <Console name="STDOUT" target="SYSTEM_OUT"> - <PatternLayout pattern="%m%n"/> - </Console> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="STDOUT"/> - </Root> - </Loggers> -</Configuration> +runtimeOnly 'org.fusesource.jansi:jansi:{jansi-version}' ---- -[#FlumeAppender] -=== FlumeAppender - -_This is an optional component supplied in a separate jar._ +==== -https://flume.apache.org/index.html[Apache Flume] is a distributed, reliable, and available system for efficiently collecting, aggregating, and moving large amounts of log data from many different sources to a centralized data store. -The FlumeAppender takes LogEvents and sends them to a Flume agent as serialized Avro events for consumption. +[#ConsoleAppender-attributes] +.Console Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description -The Flume Appender supports three modes of operation. +4+h| Required -1. It can act as a remote Flume client which sends Flume events via Avro to a Flume Agent configured with an Avro Source. -2. It can act as an embedded Flume Agent where Flume events pass directly into Flume for processing. -3. It can persist events to a local BerkeleyDB data store and then asynchronously send the events to Flume, similar to the embedded Flume Agent but without most of the Flume dependencies. +| [[ConsoleAppender-attr-name]]name +| `String` +| +| The name of the appender. -Usage as an embedded agent will cause the messages to be directly passed to the Flume Channel and then control will be immediately returned to the application. -All interaction with remote agents will occur asynchronously. -Setting the "type" attribute to "Embedded" will force the use of the embedded agent. -In addition, configuring agent properties in the appender configuration will also cause the embedded agent to be used. +4+h| Optional -.FlumeAppender Parameters -[width="100%",cols="20%,20%,60%",options="header",] -|======================================================================= -|Parameter Name |Type |Description -|agents |Agent[] |An array of Agents to which the logging events should -be sent. If more than one agent is specified the first Agent will be the -primary and subsequent Agents will be used in the order specified as -secondaries should the primary Agent fail. Each Agent definition -supplies the Agent's host and port. The specification of agents and -properties are mutually exclusive. If both are configured an error will -result. +| [[ConsoleAppender-attr-bufferSize]]bufferSize +| `int` +| xref:manual/systemproperties.adoc#log4j2.encoderByteBufferSize[`8192`] +a| +The size of the +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/ByteBuffer.html[`ByteBuffer`] +internally used by the appender. -|agentRetries |integer |The number of times the agent should be retried -before failing to a secondary. This parameter is ignored when -`type="persistent"` is specified (agents are tried once before failing to -the next). +See <<buffering,Buffering>> for more details. -|batchSize |integer |Specifies the number of events that should be sent -as a batch. The default is 1. _This parameter only applies to the Flume -Appender._ +| [[ConsoleAppender-attr-direct]]direct +| `boolean` +| `false` +a| +If set to `true`, log events will be written directly to either +https://docs.oracle.com/javase/8/docs/api/java/io/FileDescriptor.html#out[`FileDescriptor.out`] +or +https://docs.oracle.com/javase/8/docs/api/java/io/FileDescriptor.html#err[`FileDescriptor.err`]. -|compress |boolean |When set to true the message body will be compressed -using gzip +This setting bypasses the buffering of `System.out` and `System.err` and might provide a performance comparable to a xref:manual/appenders/file.adoc[file appender]. -|connectTimeoutMillis |integer |The number of milliseconds Flume will -wait before timing out the connection. +[CAUTION] +==== -|dataDir |String |Directory where the Flume write-ahead log should be -written. Valid only when embedded is set to true and Agent elements are -used instead of Property elements. +If other logging backends or the application itself uses `System.out/System.err`, setting this to `true` might cause interleaved output. -|filter |Filter |A Filter to determine if the event should be handled by -this Appender. More than one Filter may be used by using a -CompositeFilter. +==== -|eventPrefix |String |The character string to prepend to each event -attribute to distinguish it from MDC attributes. The default is -an empty string. +This setting is incompatible with the +<<ConsoleAppender-attr-follow,`follow` attribute>> +and +xref:manual/systemproperties.adoc#log4j2.skipJansi[JANSI support]. + +| [[ConsoleAppender-attr-follow]] +follow +| `boolean` +| `false` +| +If set to `true`, the appender will honor reassignments of `System.out` (resp. `System.err`) via +https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#setOut-java.io.PrintStream-[`System.setOut`] +(resp. +https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#setOut-java.io.PrintStream-[`System.setErr`]). + +Otherwise, the value of `System.out` (resp. `System.err`) at configuration time will be used. + +This setting is incompatible with the +<<ConsoleAppender-attr-direct,`direct` attribute>> +and +xref:manual/systemproperties.adoc#log4j2.skipJansi[JANSI support]. + +| [[ConsoleAppender-attr-ignoreExceptions]] +ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +Logging exceptions are always also logged to xref:manual/status-logger.adoc[] + +| [[ConsoleAppender-attr-immediateFlush]] +immediateFlush +| `boolean` +| `true` +| +If set to `true`, the appender will flush its internal buffer and the buffer of the `System.out/System.err` stream after each log event. + +See xref:manual/appenders.adoc#buffering[Buffering] for more details. + +| [[ConsoleAppender-attr-target]] +target +| link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/ConsoleAppender.Target.html[`Target`] +| link:../javadoc/log4j-core/org/apache/logging/log4j/core/appender/ConsoleAppender.Target.html#SYSTEM_OUT[`SYSTEM_OUT`] +a| +It specifies which standard output stream to use: + +`SYSTEM_OUT`:: +It uses the standard output. + +`SYSTEM_ERR`:: +It uses the standard error output. -|flumeEventFactory |FlumeEventFactory |Factory that generates the Flume -events from Log4j events. The default factory is the FlumeAvroAppender -itself. +|=== -|layout |Layout |The Layout to use to format the LogEvent. If no layout -is specified RFC5424Layout will be used. +[#ConsoleAppender-elements] +.Common nested elements +[cols="1m,1,4"] +|=== -|lockTimeoutRetries |integer |The number of times to retry if a -LockConflictException occurs while writing to Berkeley DB. The default -is 5. +| Type | Multiplicity | Description -|maxDelayMillis |integer |The maximum number of milliseconds to wait for -batchSize events before publishing the batch. +| [[ConsoleAppender-element-Filter]] +xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. -|mdcExcludes |String |A comma-separated list of mdc keys that should be -excluded from the FlumeEvent. This is mutually exclusive with the -mdcIncludes attribute. +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. -|mdcIncludes |String |A comma-separated list of mdc keys that should be -included in the FlumeEvent. Any keys in the MDC not found in the list -will be excluded. This option is mutually exclusive with the mdcExcludes -attribute. +| [[ConsoleAppender-element-Layout]] +xref:manual/layouts.adoc[`Layout`] +| zero or one +| +Formats log events. -|mdcRequired |String |A comma-separated list of `mdc` keys that must be -present in the MDC. If a key is not present a LoggingException will be -thrown. +See xref:manual/layouts.adoc[] for more information. -|mdcPrefix |String |A string that should be prepended to each MDC key to distinguish it from event attributes. The default string is -"mdc:". +|=== -|name |String |The name of the Appender. +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-ConsoleAppender[{open-book} Plugin reference for `Console`] -|properties |Property[] a| -One or more Property elements that are used to configure the Flume -Agent. The properties must be configured without the agent name (the -appender name is used for this) and no sources can be configured. -Interceptors can be specified for the source using -"sources.log4j-source.interceptors". All other Flume configuration -properties are allowed. Specifying both Agent and Property elements will -result in an error. +[#ConsoleAppender-examples] +==== Configuration examples -When used to configure in Persistent mode the valid properties are: +A typical configuration in a **development** environment might look like: -1. `keyProvider` to specify the name of the plugin to provide the -secret key for encryption. +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-dev.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/console-dev.xml[tag=appender] +---- -|requestTimeoutMillis |integer |The number of milliseconds Flume will -wait before timing out the request. +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-dev.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/console-dev.json[tag=appender] +---- -|ignoreExceptions |boolean |The default is `true`, causing exceptions -encountered while appending events to be internally logged and then -ignored. When set to `false` exceptions will be propagated to the -caller, instead. You must set this to `false` when wrapping this -Appender in a <<FailoverAppender>>. - -|type |enumeration |One of "Avro", "Embedded", or "Persistent" to -indicate which variation of the Appender is desired. -|======================================================================= - -A sample FlumeAppender configuration that is configured with a primary and a secondary agent compresses the body and formats the body using the RFC5424Layout: +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-dev.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/console-dev.yaml[tag=appender] +---- -[source,xml] +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-dev.properties[`log4j2.properties`] +[source,properties,indent=0] ---- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <Flume name="eventLogger" compress="true"> - <Agent host="192.168.10.101" port="8800"/> - <Agent host="192.168.10.102" port="8800"/> - <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> - </Flume> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="eventLogger"/> - </Root> - </Loggers> -</Configuration> +include::example$manual/appenders/console-dev.properties[tag=appender] ---- +==== -A sample FlumeAppender configuration that is configured with a primary and a secondary agent compresses the body, formats the body using the RFC5424Layout, and persists encrypted events to disk: +A typical configuration for a **production** environment might look like -[source,xml] +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-prod.xml[`log4j2.xml`] +[source,xml,indent=0] ---- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <Flume name="eventLogger" compress="true" type="persistent" dataDir="./logData"> - <Agent host="192.168.10.101" port="8800"/> - <Agent host="192.168.10.102" port="8800"/> - <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> - <Property name="keyProvider">MySecretProvider</Property> - </Flume> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="eventLogger"/> - </Root> - </Loggers> -</Configuration> +include::example$manual/appenders/console-prod.xml[tag=appender] ---- -A sample FlumeAppender configuration that is configured with a primary and a secondary agent compresses the body, and formats the body using RFC5424Layout and passes the events to an embedded Flume Agent. - -[source,xml] +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-prod.json[`log4j2.json`] +[source,json,indent=0] ---- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <Flume name="eventLogger" compress="true" type="Embedded"> - <Agent host="192.168.10.101" port="8800"/> - <Agent host="192.168.10.102" port="8800"/> - <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> - </Flume> - <Console name="STDOUT"> - <PatternLayout pattern="%d [%p] %c %m%n"/> - </Console> - </Appenders> - <Loggers> - <Logger name="EventLogger" level="info"> - <AppenderRef ref="eventLogger"/> - </Logger> - <Root level="warn"> - <AppenderRef ref="STDOUT"/> - </Root> - </Loggers> -</Configuration> +include::example$manual/appenders/console-prod.json[tag=appender] ---- -A sample FlumeAppender configuration that is configured with a primary and a secondary agent using Flume configuration properties compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent. +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-prod.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/console-prod.yaml[tag=appender] +---- -[source,xml] +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/console-prod.properties[`log4j2.properties`] +[source,properties,indent=0] ---- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="error" name="MyApp"> - <Appenders> - <Flume name="eventLogger" compress="true" type="Embedded"> - <Property name="channels">file</Property> - <Property name="channels.file.type">file</Property> - <Property name="channels.file.checkpointDir">target/file-channel/checkpoint</Property> - <Property name="channels.file.dataDirs">target/file-channel/data</Property> - <Property name="sinks">agent1 agent2</Property> - <Property name="sinks.agent1.channel">file</Property> - <Property name="sinks.agent1.type">avro</Property> - <Property name="sinks.agent1.hostname">192.168.10.101</Property> - <Property name="sinks.agent1.port">8800</Property> - <Property name="sinks.agent1.batch-size">100</Property> - <Property name="sinks.agent2.channel">file</Property> - <Property name="sinks.agent2.type">avro</Property> - <Property name="sinks.agent2.hostname">192.168.10.102</Property> - <Property name="sinks.agent2.port">8800</Property> - <Property name="sinks.agent2.batch-size">100</Property> - <Property name="sinkgroups">group1</Property> - <Property name="sinkgroups.group1.sinks">agent1 agent2</Property> - <Property name="sinkgroups.group1.processor.type">failover</Property> - <Property name="sinkgroups.group1.processor.priority.agent1">10</Property> - <Property name="sinkgroups.group1.processor.priority.agent2">5</Property> - <RFC5424Layout enterpriseNumber="18060" includeMDC="true" appName="MyApp"/> - </Flume> - <Console name="STDOUT"> - <PatternLayout pattern="%d [%p] %c %m%n"/> - </Console> - </Appenders> - <Loggers> - <Logger name="EventLogger" level="info"> - <AppenderRef ref="eventLogger"/> - </Logger> - <Root level="warn"> - <AppenderRef ref="STDOUT"/> - </Root> - </Loggers> -</Configuration> +include::example$manual/appenders/console-prod.properties[tag=appender] ---- +==== -[#jms-appender] -=== [[JMSAppender]]JMS Appender +<1> Improve performance by setting <<ConsoleAppender-attr-direct,`direct`>> to `true`. +<2> Use a structured layout. +Additional dependencies are required, see xref:manual/json-template-layout.adoc[]. -The JMS Appender sends the formatted log event to a JMS Destination. +[#file-appenders] +=== File appenders -The JMS Appender requires JNDI support so as of release 2.17.0, this appender will not function unless `log4j2.enableJndiJms=true` is configured as a system property or environment variable. -See the https://logging.apache.org/log4j/2.x/manual/configuration.html#enableJndiJms[enableJndiJms] system property. +File appenders write logs to the filesystem. +They can be further split into: -Note that in Log4j 2.0, this appender was split into a JMSQueueAppender and a JMSTopicAppender. -Starting in Log4j 2.1, these appenders were combined into the JMS Appender, which makes no distinction between queues and topics. -However, configurations written for 2.0 that use the `<JMSQueue/>` or `<JMSTopic/>` elements will continue to work with the new `<JMS/>` configuration element. +Single file appenders::: +See xref:manual/appenders/file.adoc[] for details. -.JMS Appender Parameters -[cols="1,1,1,3",options="header"] -|=== -| Parameter Name | Type | Default | Description - -| factoryBindingName -| String -| _Required_ -| The name to locate in the Context that provides the -https://jakarta.ee/specifications/platform/8/apidocs/javax/jms/connectionfactory[ConnectionFactory]. -This can be any subinterface of `ConnectionFactory` as well. - -| factoryName -| String -| _Required_ -| The fully qualified class name that should be used to define the Initial Context Factory as defined in https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY[`INITIAL_CONTEXT_FACTORY`]. If a `factoryName` is specified without a `providerURL`, a warning message will be logged as this is likely to cause problems. - -| filter -| Filter -| null -| A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter. - -| layout -| Layout -| _Required_ -| The Layout to use to format the LogEvent. _New since 2.9, in previous versions SerializedLayout was default._ - -| name -| String -| _Required_ -| The name of the Appender. - -| password -| String -| null -| The password to use to create the JMS connection. - -| providerURL -| String -| _Required_ -| The URL of the provider to use as defined by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Context.html#PROVIDER_URL[PROVIDER_URL]. From Log4j 2.17, only the `java:` protocol is supported. - -| destinationBindingName -| String -| _Required_ -| The name to use to locate the -https://jakarta.ee/specifications/platform/8/apidocs/javax/jms/destination[Destination]. -This can be a `Queue` or `Topic`, and as such, the attribute names `queueBindingName` and `topicBindingName` are aliases to maintain compatibility with the Log4j 2.0 JMS appenders. - -| securityPrincipalName -| String -| null -| The name of the identity of the Principal as specified by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL[SECURITY_PRINCIPAL]. If a securityPrincipalName is specified without `securityCredentials`, a warning message will be logged as this is likely to cause problems. - -| securityCredentials -| String -| null -| The security credentials for the principal as specified by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS[SECURITY_CREDENTIALS]. - -| ignoreExceptions -| boolean -| true -| When `true`, exceptions caught while appending events are internally logged and then ignored. When `false` exceptions are propagated to the caller. You must set this to `false` when wrapping this Appender in a FailoverAppender. - -| immediateFail -| boolean -| false -| When set to true, log events will not wait to try to reconnect and will fail immediately if the JMS resources are not available. New in 2.9. - -| reconnectIntervalMillis -| long -| 5000 -| If set to a value greater than 0, after an error, the JMSManager will attempt to reconnect to the broker after waiting the specified number of milliseconds. If the reconnect fails then an exception will be thrown (which can be caught by the application if `ignoreExceptions` is set to `false`). New in 2.9. - -| urlPkgPrefixes -| String -| null -| A colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory as defined by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES[URL_PKG_PREFIXES]. - -| userName -| String -| null -| The user ID used to create the JMS connection. -|=== +Rolling file appenders::: +See xref:manual/appenders/rolling-file.adoc[] for details. -Here is a sample JMS Appender configuration: +[#database-appenders] +=== Database appenders -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <JMS name="jmsQueue" destinationBindingName="MyQueue" - factoryBindingName="MyQueueConnectionFactory"> - <JsonLayout properties="true"/> - </JMS> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="jmsQueue"/> - </Root> - </Loggers> -</Configuration> ----- +The appenders write log events directly to a database. -To map your Log4j `MapMessage` to JMS `javax.jms.MapMessage`, set the layout of the appender to `MessageLayout` with `<MessageLayout />` (Since 2.9.): +xref:manual/appenders/database.adoc#CassandraAppender[Cassandra appender]:: +Sends log events to +https://cassandra.apache.org/_/index.html[Apache Cassandra] -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration status="warn" name="MyApp"> - <Appenders> - <JMS name="jmsQueue" destinationBindingName="MyQueue" - factoryBindingName="MyQueueConnectionFactory"> - <MessageLayout /> - </JMS> - </Appenders> - <Loggers> - <Root level="error"> - <AppenderRef ref="jmsQueue"/> - </Root> - </Loggers> -</Configuration> ----- +xref:manual/appenders/database.adoc#JdbcAppender[JDBC appender]:: +Sends log events to a JDBC driver -[[KafkaAppender]] -=== KafkaAppender +xref:manual/appenders/database.adoc#JpaAppender[JPA appender]:: +Uses Jakarta Persistence API to deliver log events to a database -The KafkaAppender logs events to an https://kafka.apache.org/[Apache Kafka] topic. -Each log event is sent as a Kafka record. +xref:manual/appenders/database.adoc#NoSqlAppender[NoSQL appender]:: +Store log events to a document-oriented database -[cols="1m,1m,5"] -|=== -|Parameter Name |Type |Description - -|topic -|String -|The Kafka topic to use. Required. - -|[[KafkaAppender-attr-key]]key -|String -|The key that will be sent to Kafka with every message. - -Supports -xref:manual/configuration.adoc#lazy-property-substitution[runtime property substitution] -and is evaluated in the -xref:manual/lookups.adoc#event-context[_context of the current event_]. - -|filter -|Filter -|A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter. - -|layout -|Layout -|The Layout to use to format the LogEvent. Required, there is no default. _New since 2.9, in previous versions `<PatternLayout pattern="%m"/>` was default._ - -|name -|String -|The name of the Appender. Required. - -|ignoreExceptions -|boolean -|The default is `true`, causing exceptions encountered while appending events to be internally logged and then ignored. When set to `false` exceptions will be propagated to the caller, instead. You must set this to `false` when wrapping this Appender in a <<FailoverAppender>>. - -|syncSend -|boolean -|The default is `true`, causing sends to block until the record has been acknowledged by the Kafka server. When set to `false`, sends a return immediately, allowing for lower latency and significantly higher throughput. _New since 2.8. Be aware that this is a new addition, and it has not been extensively tested. -Any failure sending to Kafka will be reported as an error to xref:manual/status-logger.adoc[] and the log event will be dropped (the ignoreExceptions parameter will not be effective). -Log events may arrive out of order on the Kafka server._ - -|properties -|Property[] -|You can set properties in https://kafka.apache.org/documentation.html#producerconfigs[Kafka producer properties]. You need to set the `bootstrap.servers` property, there are sensible default values for the others. Do not set the `value.serializer` nor `key.serializer` properties. -|=== +See xref:manual/appenders/database.adoc[] for details. -Here is a sample KafkaAppender configuration snippet: +[#network-appenders] +=== Network appenders -[source,xml] ----- -<?xml version="1.0" encoding="UTF-8"?> -<Configuration> - <!-- ... --> - <Appenders> - <Kafka name="Kafka" topic="log-test"> - <PatternLayout pattern="%date %message"/> - <Property name="bootstrap.servers">localhost:9092</Property> - </Kafka> - </Appenders> - <!-- ... --> -</Configuration> ----- +These appenders use simple network protocols to transmit log events to a remote host. +The supported network protocols are: + +`UDP`:: +`TCP`:: +These are handled by the xref:manual/appenders/network.adoc#SocketAppender[Socket Appender]. + +`HTTP`:: +This is handled by the xref:manual/appenders/network.adoc#HttpAppender[HTTP Appender]. + +`SMTP`:: +This is handled by the xref:manual/appenders/network.adoc#HttpAppender[SMTP Appender]. -This appender is synchronous by default and will block until the record has been acknowledged by the Kafka server, timeout for this can be set with the `timeout.ms` property (defaults to 30 seconds). -Wrap with https://logging.apache.org/log4j/2.x/manual/appenders.html#AsyncAppender[Async appender] and/or set syncSend to `false` to log asynchronously. +See xref:manual/appenders/network.adoc[] for details. -This appender requires the https://kafka.apache.org/[Kafka client library]. -Note that you need to use a version of the Kafka client library matching the Kafka server used. +[#message-queue-appenders] +=== Message queue appenders -_Note:_ Make sure to not let `org.apache.kafka` log to a Kafka appender on DEBUG level, since that will cause recursive logging: +Message queue appenders forward log events to a message broker to provide guaranteed delivery over the network. Review Comment: _"to provide guaranteed delivery over the network"_ is an appender-specific feature that we should not generalize for the group: ```suggestion Message queue appenders forward log events to a message broker. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
