| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/manual/appenders.xml at 2020-02-25 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.1" /> |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="author" content="Gary Gregory" /> |
| <meta name="author" content="Nick Williams" /> |
| <meta name="author" content="Matt SIcker" /> |
| <title>Log4j – Log4j 2 Appenders</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.8.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="../images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="../images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-02-25<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="../build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="none"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li class="active"><a href="#"><span class="icon-chevron-down"></span>Appenders</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/appenders.html#AsyncAppender" title="Async"><span class="none"></span>Async</a></li> |
| <li><a href="../manual/appenders.html#CassandraAppender" title="Cassandra"><span class="none"></span>Cassandra</a></li> |
| <li><a href="../manual/appenders.html#ConsoleAppender" title="Console"><span class="none"></span>Console</a></li> |
| <li><a href="../manual/appenders.html#FailoverAppender" title="Failover"><span class="none"></span>Failover</a></li> |
| <li><a href="../manual/appenders.html#FileAppender" title="File"><span class="none"></span>File</a></li> |
| <li><a href="../manual/appenders.html#FlumeAppender" title="Flume"><span class="none"></span>Flume</a></li> |
| <li><a href="../manual/appenders.html#JDBCAppender" title="JDBC"><span class="none"></span>JDBC</a></li> |
| <li><a href="../manual/appenders.html#JMSAppender" title="JMS"><span class="none"></span>JMS</a></li> |
| <li><a href="../manual/appenders.html#JPAAppender" title="JPA"><span class="none"></span>JPA</a></li> |
| <li><a href="../manual/appenders.html#HttpAppender" title="HTTP"><span class="none"></span>HTTP</a></li> |
| <li><a href="../manual/appenders.html#KafkaAppender" title="Kafka"><span class="none"></span>Kafka</a></li> |
| <li><a href="../manual/appenders.html#MemoryMappedFileAppender" title="Memory Mapped File"><span class="none"></span>Memory Mapped File</a></li> |
| <li><a href="../manual/appenders.html#NoSQLAppender" title="NoSQL"><span class="none"></span>NoSQL</a></li> |
| <li><a href="../manual/appenders.html#NoSQLAppenderMongoDB" title="NoSQL for MongoDB"><span class="none"></span>NoSQL for MongoDB</a></li> |
| <li><a href="../manual/appenders.html#NoSQLAppenderMongoDB2" title="NoSQL for MongoDB 2"><span class="none"></span>NoSQL for MongoDB 2</a></li> |
| <li><a href="../manual/appenders.html#NoSQLAppenderMongoDB3" title="NoSQL for MongoDB 3"><span class="none"></span>NoSQL for MongoDB 3</a></li> |
| <li><a href="../manual/appenders.html#NoSQLAppenderCouchDB" title="NoSQL for CouchDB"><span class="none"></span>NoSQL for CouchDB</a></li> |
| <li><a href="../manual/appenders.html#OutputStreamAppender" title="Output Stream"><span class="none"></span>Output Stream</a></li> |
| <li><a href="../manual/appenders.html#RandomAccessFileAppender" title="Random Access File"><span class="none"></span>Random Access File</a></li> |
| <li><a href="../manual/appenders.html#RewriteAppender" title="Rewrite"><span class="none"></span>Rewrite</a></li> |
| <li><a href="../manual/appenders.html#RollingFileAppender" title="Rolling File"><span class="none"></span>Rolling File</a></li> |
| <li><a href="../manual/appenders.html#RollingRandomAccessFileAppender" title="Rolling Random Access File"><span class="none"></span>Rolling Random Access File</a></li> |
| <li><a href="../manual/appenders.html#RoutingAppender" title="Routing"><span class="none"></span>Routing</a></li> |
| <li><a href="../manual/appenders.html#SMTPAppender" title="SMTP"><span class="none"></span>SMTP</a></li> |
| <li><a href="../manual/appenders.html#ScriptAppenderSelector" title="ScriptAppenderSelector"><span class="none"></span>ScriptAppenderSelector</a></li> |
| <li><a href="../manual/appenders.html#SocketAppender" title="Socket"><span class="none"></span>Socket</a></li> |
| <li><a href="../manual/appenders.html#SSL" title="SSL"><span class="none"></span>SSL</a></li> |
| <li><a href="../manual/appenders.html#SyslogAppender" title="Syslog"><span class="none"></span>Syslog</a></li> |
| <li><a href="../manual/appenders.html#JeroMQAppender" title="ZeroMQ/JeroMQ"><span class="none"></span>ZeroMQ/JeroMQ</a></li> |
| </ul></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="../log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="../log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="../log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="../log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="../dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="../dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="../license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="../changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="../jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="../rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="Appenders"></a>Appenders</h2> |
| |
| <p> |
| Appenders are responsible for delivering LogEvents to their destination. Every Appender must |
| implement the <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html">Appender</a> |
| interface. Most Appenders will extend |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/AbstractAppender.html">AbstractAppender</a> |
| which adds <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/LifeCycle.html">Lifecycle</a> |
| and <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/filter/Filterable.html">Filterable</a> |
| support. Lifecycle allows components to finish initialization after configuration has completed and to |
| perform cleanup during shutdown. Filterable allows the component to have Filters attached to it which are |
| evaluated during event processing. |
| </p> |
| |
| <p> |
| Appenders usually are only responsible for writing the event data to the target destination. In most cases |
| they delegate responsibility for formatting the event to a <a href="layouts.html">layout</a>. Some |
| appenders wrap other appenders so that they can modify the LogEvent, handle a failure in an Appender, |
| route the event to a subordinate Appender based on advanced Filter criteria or provide similar functionality |
| that does not directly format the event for viewing. |
| </p> |
| |
| <p> |
| Appenders always have a name so that they can be referenced from Loggers. |
| </p> |
| |
| <p> |
| In the tables below, the "Type" column corresponds to the Java type expected. For non-JDK classes, these |
| should usually be in <a href="../log4j-core/apidocs/index.html">Log4j Core</a> unless otherwise noted. |
| </p> |
| <a name="AsyncAppender"></a> |
| <section> |
| <h3><a name="AsyncAppender"></a>AsyncAppender</h3> |
| |
| <p>The AsyncAppender accepts references to other Appenders and causes LogEvents to be written to them |
| on a separate Thread. Note that exceptions while writing to those Appenders will be hidden from |
| the application. The AsyncAppender should be configured after the appenders it references to allow it |
| to shut down properly.</p> |
| |
| <p> |
| By default, AsyncAppender uses |
| <a class="javadoc" href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html">java.util.concurrent.ArrayBlockingQueue</a> |
| which does not require any external libraries. Note that multi-threaded applications should exercise care |
| when using this appender as such: the blocking queue is susceptible to lock contention and our |
| <a href="../performance.html#asyncLogging">tests showed</a> |
| performance may become worse when more threads are logging concurrently. |
| Consider using <a href="async.html">lock-free Async Loggers</a> for optimal performance. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">AsyncAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>AppenderRef</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appenders to invoke asynchronously. Multiple AppenderRef |
| elements can be configured.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>blocking</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, the appender will wait until there are free slots in the queue. If false, the event |
| will be written to the error appender if the queue is full. The default is true.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>shutdownTimeout</td> |
| |
| <td>integer</td> |
| |
| <td>How many milliseconds the Appender should wait to flush outstanding log events in the queue |
| on shutdown. The default is zero which means to wait forever.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>integer</td> |
| |
| <td>Specifies the maximum number of events that can be queued. The default is 1024. Note that when using a |
| disruptor-style BlockingQueue, this buffer size must be a power of 2. |
| |
| <p> |
| When the application is logging faster than the underlying appender can keep up with |
| for a long enough time to fill up the queue, the behaviour is determined by the |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html">AsyncQueueFullPolicy</a>. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>errorRef</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender to invoke if none of the appenders can be called, either due to errors |
| in the appenders or because the queue is full. If not specified then errors will be ignored.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>includeLocation</td> |
| |
| <td>boolean</td> |
| |
| <td>Extracting location is an expensive operation (it can make |
| logging 5 - 20 times slower). To improve performance, location is |
| not included by default when adding a log event to the queue. |
| You can change this by setting includeLocation="true".</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>BlockingQueueFactory</td> |
| |
| <td>BlockingQueueFactory</td> |
| |
| <td>This element overrides what type of BlockingQueue to use. See |
| <a href="#BlockingQueueFactory">below documentation</a> for more details.</td> |
| </tr> |
| </table> |
| |
| <p> |
| There are also a few system properties that can be used to maintain application throughput even when |
| the underlying appender cannot keep up with the logging rate and the queue is filling up. |
| See the details for system properties |
| <a href="configuration.html#log4j2.AsyncQueueFullPolicy">log4j2.AsyncQueueFullPolicy and |
| log4j2.DiscardThreshold</a>. |
| </p> |
| |
| <p> |
| A typical AsyncAppender configuration might look like: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <File name="MyFile" fileName="logs/app.log"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| </File> |
| <Async name="Async"> |
| <AppenderRef ref="MyFile"/> |
| </Async> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Async"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| <a name="BlockingQueueFactory"></a> |
| Starting in Log4j 2.7, a custom implementation of BlockingQueue or TransferQueue can be |
| specified using a |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/BlockingQueueFactory.html" class="javadoc">BlockingQueueFactory</a> |
| plugin. To override the default BlockingQueueFactory, specify the plugin inside an |
| <Async/> element like so: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Configuration name="LinkedTransferQueueExample"> |
| <Appenders> |
| <List name="List"/> |
| <Async name="Async" bufferSize="262144"> |
| <AppenderRef ref="List"/> |
| <LinkedTransferQueue/> |
| </Async> |
| </Appenders> |
| <Loggers> |
| <Root> |
| <AppenderRef ref="Async"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| Log4j ships with the following implementations: |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">BlockingQueueFactory Implementations</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Plugin Name</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ArrayBlockingQueue</td> |
| |
| <td> |
| This is the default implementation that uses |
| <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>DisruptorBlockingQueue</td> |
| |
| <td> |
| This uses the <a class="externalLink" href="https://github.com/conversant/disruptor">Conversant Disruptor</a> implementation |
| of BlockingQueue. This plugin takes a single optional attribute, spinPolicy, which |
| corresponds to |
| |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>JCToolsBlockingQueue</td> |
| |
| <td> |
| This uses <a class="externalLink" href="https://jctools.github.io/JCTools/">JCTools</a>, specifically the |
| <abbr title="multiple producer single consumer">MPSC</abbr> bounded lock-free queue. |
| |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>LinkedTransferQueue</td> |
| |
| <td> |
| This uses the new in Java 7 implementation |
| <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/LinkedTransferQueue.html">LinkedTransferQueue</a>. |
| Note that this queue does not use the bufferSize configuration attribute from AsyncAppender as |
| LinkedTransferQueue does not support a maximum capacity. |
| |
| </td> |
| </tr> |
| </table> |
| </section> |
| <a name="CassandraAppender"></a> |
| <section> |
| <h3><a name="CassandraAppender"></a>CassandraAppender</h3> |
| |
| <p> |
| The CassandraAppender writes its output to an <a class="externalLink" href="https://cassandra.apache.org/">Apache Cassandra</a> |
| database. A keyspace and table must be configured ahead of time, and the columns of that table are mapped |
| in a configuration file. Each column can specify either a <a href="layouts.html">StringLayout</a> (e.g., a |
| <a href="layouts.html#PatternLayout">PatternLayout</a>) along with an optional conversion type, or only |
| a conversion type for org.apache.logging.log4j.spi.ThreadContextMap or |
| org.apache.logging.log4j.spi.ThreadContextStack to store the <a href="thread-context.html">MDC or NDC</a> |
| in a map or list column respectively. A conversion type compatible with java.util.Date will |
| use the log event timestamp converted to that type (e.g., use java.util.Date to fill a |
| timestamp column type in Cassandra). |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">CassandraAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>batched</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether or not to use batch statements to write log messages to Cassandra. By default, this is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>batchType</td> |
| |
| <td><a class="externalLink" href="http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/BatchStatement.Type.html">BatchStatement.Type</a></td> |
| |
| <td>The batch type to use when using batched writes. By default, this is LOGGED.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>The number of log messages to buffer or batch before writing. By default, no buffering is done.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>clusterName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Cassandra cluster to connect to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>columns</td> |
| |
| <td>ColumnMapping[]</td> |
| |
| <td>A list of column mapping configurations. Each column must specify a column name. Each column can |
| have a conversion type specified by its fully qualified class name. By default, the conversion type is |
| String. If the configured type is assignment-compatible with |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/util/ReadOnlyStringMap.html" class="javadoc">ReadOnlyStringMap</a> |
| / |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextMap.html" class="javadoc">ThreadContextMap</a> |
| or |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextStack.html" class="javadoc">ThreadContextStack</a>, |
| then that column will be populated with the MDC or NDC respectively. If the configured type is |
| assignment-compatible with java.util.Date, then the log timestamp will be converted to |
| that configured date type. If a literal attribute is given, then its value will be used as |
| is in the INSERT query without any escaping. Otherwise, the layout or pattern specified |
| will be converted into the configured type and stored in that column. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>contactPoints</td> |
| |
| <td>SocketAddress[]</td> |
| |
| <td>A list of hosts and ports of Cassandra nodes to connect to. These must be valid hostnames or IP |
| addresses. By default, if a port is not specified for a host or it is set to 0, then the default |
| Cassandra port of 9042 will be used. By default, localhost:9042 will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter may be used |
| by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>keyspace</td> |
| |
| <td>String</td> |
| |
| <td>The name of the keyspace containing the table that log messages will be written to.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>The password to use (along with the username) to connect to Cassandra.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>table</td> |
| |
| <td>String</td> |
| |
| <td>The name of the table to write log messages to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>useClockForTimestampGenerator</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether or not to use the configured org.apache.logging.log4j.core.util.Clock as a |
| <a class="javadoc" href="http://docs.datastax.com/en/drivers/java/3.0/com/datastax/driver/core/TimestampGenerator.html">TimestampGenerator</a>. |
| By default, this is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>username</td> |
| |
| <td>String</td> |
| |
| <td>The username to use to connect to Cassandra. By default, no username or password is used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>useTls</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether or not to use TLS/SSL to connect to Cassandra. This is false by default.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is an example CassandraAppender configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Configuration name="CassandraAppenderTest"> |
| <Appenders> |
| <Cassandra name="Cassandra" clusterName="Test Cluster" keyspace="test" table="logs" bufferSize="10" batched="true"> |
| <SocketAddress host="localhost" port="9042"/> |
| <ColumnMapping name="id" pattern="%uuid{TIME}" type="java.util.UUID"/> |
| <ColumnMapping name="timeid" literal="now()"/> |
| <ColumnMapping name="message" pattern="%message"/> |
| <ColumnMapping name="level" pattern="%level"/> |
| <ColumnMapping name="marker" pattern="%marker"/> |
| <ColumnMapping name="logger" pattern="%logger"/> |
| <ColumnMapping name="timestamp" type="java.util.Date"/> |
| <ColumnMapping name="mdc" type="org.apache.logging.log4j.spi.ThreadContextMap"/> |
| <ColumnMapping name="ndc" type="org.apache.logging.log4j.spi.ThreadContextStack"/> |
| </Cassandra> |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.logging.log4j.cassandra" level="DEBUG"> |
| <AppenderRef ref="Cassandra"/> |
| </Logger> |
| <Root level="ERROR"/> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| |
| <p> |
| This example configuration uses the following table schema: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| CREATE TABLE logs ( |
| id timeuuid PRIMARY KEY, |
| timeid timeuuid, |
| message text, |
| level text, |
| marker text, |
| logger text, |
| timestamp timestamp, |
| mdc map<text,text>, |
| ndc list<text> |
| ); |
| </pre></div> |
| </section> |
| <a name="ConsoleAppender"></a> |
| <section> |
| <h3><a name="ConsoleAppender"></a>ConsoleAppender</h3> |
| |
| <p> |
| 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. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">ConsoleAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>follow</td> |
| |
| <td>boolean</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>direct</td> |
| |
| <td>boolean</td> |
| |
| <td>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 file or other process. |
| Cannot be used with Jansi on Windows. Cannot be used with follow. 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. |
| <i>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.</i></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>target</td> |
| |
| <td>String</td> |
| |
| <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_OUT".</td> |
| </tr> |
| </table> |
| |
| <p> |
| A typical Console configuration might look like: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="FailoverAppender"></a> |
| <section> |
| <h3><a name="FailoverAppender"></a>FailoverAppender</h3> |
| |
| <p>The FailoverAppender wraps a set of appenders. If the primary Appender fails the secondary appenders will be |
| tried in order until one succeeds or there are no more secondaries to try.</p> |
| |
| <table border="0" class="table table-striped"><caption align="top">FailoverAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>primary</td> |
| |
| <td>String</td> |
| |
| <td>The name of the primary Appender to use.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>failovers</td> |
| |
| <td>String[]</td> |
| |
| <td>The names of the secondary Appenders to use.</td> |
| </tr> |
| |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>retryIntervalSeconds</td> |
| |
| <td>integer</td> |
| |
| <td>The number of seconds that should pass before retrying the primary Appender. The default is 60.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>target</td> |
| |
| <td>String</td> |
| |
| <td>Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".</td> |
| </tr> |
| </table> |
| |
| <p> |
| A Failover configuration might look like: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" filePattern="logs/app-%d{MM-dd-yyyy}.log.gz" |
| ignoreExceptions="false"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <TimeBasedTriggeringPolicy /> |
| </RollingFile> |
| <Console name="STDOUT" target="SYSTEM_OUT" ignoreExceptions="false"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Failover name="Failover" primary="RollingFile"> |
| <Failovers> |
| <AppenderRef ref="Console"/> |
| </Failovers> |
| </Failover> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Failover"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="FileAppender"></a> |
| <section> |
| <h3><a name="FileAppender"></a>FileAppender</h3> |
| |
| <p>The FileAppender is an OutputStreamAppender that writes to the File named in the fileName parameter. The |
| FileAppender uses a FileManager (which extends OutputStreamManager) to actually perform the file I/O. While |
| FileAppenders from different Configurations cannot be shared, the FileManagers can be if the Manager is |
| accessible. For example, two web applications in a servlet container can have their own configuration and |
| safely write to the same file if Log4j is in a ClassLoader that is common to both of them.</p> |
| |
| <table border="0" class="table table-striped"><caption align="top">FileAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>append</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be appended to the end of the file. When set to false, |
| the file will be cleared before new records are written.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferedIO</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be written to a buffer and the data will be written to |
| disk when the buffer is full or, if immediateFlush is set, when the record is written. |
| File locking cannot be used with bufferedIO. Performance tests have shown that using buffered I/O |
| significantly improves performance, even if immediateFlush is enabled.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>When bufferedIO is true, this is the buffer size, the default is 8192 bytes.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>createOnDemand</td> |
| |
| <td>boolean</td> |
| |
| <td>The appender creates the file on-demand. The appender only creates the file when a log event |
| passes all filters and is routed to this appender. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the file to write to. If the file, or any of its parent directories, do not exist, |
| they will be created.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| <p>When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance.</p> |
| |
| <p>Flushing after every write is only useful when using this |
| appender with synchronous loggers. Asynchronous loggers and |
| appenders will automatically flush at the end of a batch of events, |
| even if immediateFlush is set to false. This also guarantees |
| the data is written to disk but is more efficient.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>locking</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true, I/O operations will occur only while the file lock is held allowing FileAppenders |
| in multiple JVMs and potentially multiple hosts to write to the same file simultaneously. This |
| will significantly impact performance so should be used carefully. Furthermore, on many systems |
| the file lock is "advisory" meaning that other applications can perform operations on the file |
| without acquiring a lock. The default value is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filePermissions</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File attribute permissions in POSIX format to apply whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| |
| <p>Examples: rw------- or rw-rw-rw- etc...</p></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileOwner</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File owner to define whenever the file is created.</p> |
| |
| <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. |
| Only processes with an effective user ID equal to the user ID |
| of the file or with appropriate privileges may change the ownership of a file |
| if <a class="externalLink" href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html">_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> |
| |
| <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html">owner</a> attribute view.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileGroup</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File group to define whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample File configuration: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <File name="MyFile" fileName="logs/app.log"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| </File> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="MyFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="FlumeAppender"></a> |
| <section> |
| <h3><a name="FlumeAppender"></a>FlumeAppender</h3> |
| |
| <p><i>This is an optional component supplied in a separate jar.</i></p> |
| |
| <p><a class="externalLink" href="http://flume.apache.org/index.html">Apache Flume</a> 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.</p> |
| |
| <p> |
| The Flume Appender supports three modes of operation. |
| </p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>It can act as a remote Flume client which sends Flume events via Avro to a Flume Agent configured |
| with an Avro Source.</li> |
| |
| <li>It can act as an embedded Flume Agent where Flume events pass directly into Flume for processing.</li> |
| |
| <li>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.</li> |
| </ol> |
| |
| <p> |
| 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. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">FlumeAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>agents</td> |
| |
| <td>Agent[]</td> |
| |
| <td>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 Agents host and port. |
| The specification of agents and properties are mutually exclusive. If both are configured an |
| error will result.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>agentRetries</td> |
| |
| <td>integer</td> |
| |
| <td>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).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>batchSize</td> |
| |
| <td>integer</td> |
| |
| <td>Specifies the number of events that should be sent as a batch. The default is 1. <i>This |
| parameter only applies to the Flume Appender.</i></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>compress</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true the message body will be compressed using gzip</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>connectTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The number of milliseconds Flume will wait before timing out the connection.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>dataDir</td> |
| |
| <td>String</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>eventPrefix</td> |
| |
| <td>String</td> |
| |
| <td>The character string to prepend to each event attribute in order to distinguish it from MDC attributes. |
| The default is an empty string.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>flumeEventFactory</td> |
| |
| <td>FlumeEventFactory</td> |
| |
| <td>Factory that generates the Flume events from Log4j events. The default factory is the |
| FlumeAvroAppender itself.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is specified RFC5424Layout will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>lockTimeoutRetries</td> |
| |
| <td>integer</td> |
| |
| <td>The number of times to retry if a LockConflictException occurs while writing to Berkeley DB. The |
| default is 5.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>maxDelayMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The maximum number of milliseconds to wait for batchSize events before publishing the batch.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mdcExcludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of mdc keys that should be excluded from the FlumeEvent. This is mutually |
| exclusive with the mdcIncludes attribute.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mdcIncludes</td> |
| |
| <td>String</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mdcRequired</td> |
| |
| <td>String</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mdcPrefix</td> |
| |
| <td>String</td> |
| |
| <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes. |
| The default string is "mdc:".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>properties</td> |
| |
| <td>Property[]</td> |
| |
| <td> |
| <p>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.</p> |
| |
| <p>When used to configure in Persistent mode the valid properties are:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>"keyProvider" to specify the name of the plugin to provide the secret key for encryption.</li> |
| </ol> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>requestTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The number of milliseconds Flume will wait before timing out the request.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>type</td> |
| |
| <td>enumeration</td> |
| |
| <td>One of "Avro", "Embedded", or "Persistent" to indicate which variation of the Appender is desired.</td> |
| </tr> |
| </table> |
| |
| <p> |
| A sample FlumeAppender configuration that is configured with a primary and a secondary agent, |
| compresses the body, and formats the body using the RFC5424Layout: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <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></pre></div> |
| |
| <p> |
| 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: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <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></pre></div> |
| |
| <p> |
| A sample FlumeAppender configuration that is configured with a primary and a secondary agent, |
| compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume |
| Agent. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <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></pre></div> |
| |
| <p> |
| 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. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error" name="MyApp" packages=""> |
| <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></pre></div> |
| </section> |
| <a name="JDBCAppender"></a> |
| <section> |
| <h3><a name="JDBCAppender"></a>JDBCAppender</h3> |
| |
| <p>The JDBCAppender writes log events to a relational database table using standard JDBC. It can be configured |
| to obtain JDBC connections using a JNDI DataSource or a custom factory method. Whichever |
| approach you take, it <b><i>must</i></b> be backed by a connection pool. Otherwise, logging |
| performance will suffer greatly. If batch statements are supported by the configured JDBC driver and a |
| bufferSize is configured to be a positive number, then log events will be batched. Note that as |
| of Log4j 2.8, there are two ways to configure log event to column mappings: the original ColumnConfig |
| style that only allows strings and timestamps, and the new ColumnMapping plugin that uses Log4j's |
| built-in type conversion to allow for more data types (this is the same plugin as in the |
| <a href="#CassandraAppender">Cassandra Appender</a>).</p> |
| |
| <p> |
| To get off the ground quickly during development, an alternative to using a connection source based on |
| JNDI is to use the non-pooling DriverManager connection source. This connection source uses |
| a JDBC connection string, a user name, and a password. Optionally, you can also use properties. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">JDBCAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter may be |
| used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>If an integer greater than 0, this causes the appender to buffer log events and flush whenever the |
| buffer reaches this size.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>connectionSource</td> |
| |
| <td>ConnectionSource</td> |
| |
| <td><i>Required.</i> The connections source from which database connections should be retrieved.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>tableName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the database table to insert log events into.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>columnConfigs</td> |
| |
| <td>ColumnConfig[]</td> |
| |
| <td><i>Required (and/or columnMappings).</i> Information about the columns that log event data should be inserted into and how |
| to insert that data. This is represented with multiple <Column> elements.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>columnMappings</td> |
| |
| <td>ColumnMapping[]</td> |
| |
| <td><i>Required (and/or columnConfigs).</i> A list of column mapping configurations. Each column must |
| specify a column name. Each column can have a conversion type specified by its fully qualified class |
| name. By default, the conversion type is String. If the configured type is |
| assignment-compatible with |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/util/ReadOnlyStringMap.html" class="javadoc">ReadOnlyStringMap</a> |
| / |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextMap.html" class="javadoc">ThreadContextMap</a> |
| or |
| <a href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextStack.html" class="javadoc">ThreadContextStack</a>, |
| then that column will be populated with the MDC or NDC respectively (this is database-specific how they |
| handle inserting a Map or List value). If the configured type is |
| assignment-compatible with java.util.Date, then the log timestamp will be converted to |
| that configured date type. If the configured type is assignment-compatible with java.sql.Clob |
| or java.sql.NClob, then the formatted event will be set as a Clob or NClob respectively |
| (similar to the traditional ColumnConfig plugin). If a literal attribute is given, then its |
| value will be used as is in the INSERT query without any escaping. Otherwise, the layout or |
| pattern specified will be converted into the configured type and stored in that column. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>immediateFail</td> |
| |
| <td>boolean</td> |
| |
| <td>false</td> |
| |
| <td>When set to true, log events will not wait to try to reconnect and will fail immediately if the |
| JDBC resources are not available. New in 2.11.2</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>reconnectIntervalMillis</td> |
| |
| <td>long</td> |
| |
| <td>5000</td> |
| |
| <td>If set to a value greater than 0, after an error, the JDBCDatabaseManager will attempt to reconnect to |
| the database 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.11.2.</td> |
| </tr> |
| </table> |
| |
| <p>When configuring the JDBCAppender, you must specify a ConnectionSource implementation from |
| which the Appender gets JDBC connections. You must use exactly one of the following nested elements:</p> |
| |
| <ul> |
| |
| <li><a href="#JDBCDataSource"><DataSource></a>: Uses JNDI.</li> |
| |
| <li><a href="#JDBCConnectionFactory"><ConnectionFactory></a>: Points to a class-method pair to provide JDBC connections.</li> |
| |
| <li><a href="#JDBCDriverManager"><DriverManager></a>: A quick and dirty way to get off the ground, no connection pooling.</li> |
| |
| <li><a href="#JDBCPoolingDriver"><PoolingDriver></a>: Uses Apache Commons DBCP to provide connection pooling.</li> |
| </ul> |
| <a name="JDBCDataSource"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">DataSource Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>jndiName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The full, prefixed JNDI name that the javax.sql.DataSource is bound |
| to, such as java:/comp/env/jdbc/LoggingDatabase. The DataSource must be backed |
| by a connection pool; otherwise, logging will be very slow.</td> |
| </tr> |
| </table> |
| <a name="JDBCConnectionFactory"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">ConnectionFactory Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>class</td> |
| |
| <td>Class</td> |
| |
| <td><i>Required.</i> The fully qualified name of a class containing a static factory method for |
| obtaining JDBC connections.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>method</td> |
| |
| <td>Method</td> |
| |
| <td><i>Required.</i> The name of a static factory method for obtaining JDBC connections. This method |
| must have no parameters and its return type must be either java.sql.Connection or |
| DataSource. If the method returns Connections, it must obtain them from a |
| connection pool (and they will be returned to the pool when Log4j is done with them); otherwise, logging |
| will be very slow. If the method returns a DataSource, the DataSource will |
| only be retrieved once, and it must be backed by a connection pool for the same reasons.</td> |
| </tr> |
| </table> |
| <a name="JDBCDriverManager"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">DriverManager Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>connectionString</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The driver-specific JDBC connection string.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>userName</td> |
| |
| <td>String</td> |
| |
| <td>The database user name. You cannot specify both properties and a user name or password.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>The database password. You cannot specify both properties and a user name or password.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>driverClassName</td> |
| |
| <td>String</td> |
| |
| <td>The JDBC driver class name. Some old JDBC Driver can only be discovered by explicitly loading them by class name.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>properties</td> |
| |
| <td>Property[]</td> |
| |
| <td>A list of properties. You cannot specify both properties and a user name or password.</td> |
| </tr> |
| </table> |
| <a name="JDBCPoolingDriver"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">PoolingDriver Parameters (Apache Commons DBCP)</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>DriverManager parameters</td> |
| |
| <td>DriverManager parameters</td> |
| |
| <td>This connection source inherits all parameter from the DriverManager connection source.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>poolName</td> |
| |
| <td>String</td> |
| |
| <td>The pool name used to pool JDBC Connections. Defaults to example. You can use the JDBC |
| connection string prefix jdbc:apache:commons:dbcp: followed by the pool name if you want |
| to use a pooled connection elsewhere. For example: jdbc:apache:commons:dbcp:example.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>PoolableConnectionFactory</td> |
| |
| <td>PoolableConnectionFactory element</td> |
| |
| <td>Defines a PoolableConnectionFactory.</td> |
| </tr> |
| </table> |
| <a name="JDBCPoolableConnectionFactory"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">PoolableConnectionFactory Parameters (Apache Commons DBCP)</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>autoCommitOnReturn</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>cacheState</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ConnectionInitSqls</td> |
| |
| <td>Strings</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>defaultAutoCommit</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>defaultCatalog</td> |
| |
| <td>String</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>defaultQueryTimeoutSeconds</td> |
| |
| <td>integer</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>defaultReadOnly</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>defaultTransactionIsolation</td> |
| |
| <td>integer</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>disconnectionSqlCodes</td> |
| |
| <td>Strings</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fastFailValidation</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>maxConnLifetimeMillis</td> |
| |
| <td>long</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>maxOpenPreparedStatements</td> |
| |
| <td>integer</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>poolStatements</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>rollbackOnReturn</td> |
| |
| <td>boolean</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>validationQuery</td> |
| |
| <td>String</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>validationQueryTimeoutSeconds</td> |
| |
| <td>integer</td> |
| |
| <td>See <a class="externalLink" href="http://commons.apache.org/proper/commons-dbcp/api-2.4.0/org/apache/commons/dbcp2/PoolableConnectionFactory.html">Apache Commons DBCP PoolableConnectionFactory.</a></td> |
| </tr> |
| </table> |
| |
| <p>When configuring the JDBCAppender, use the nested <Column> elements to specify which |
| columns in the table should be written to and how to write to them. The JDBCAppender uses this information |
| to formulate a PreparedStatement to insert records without SQL injection vulnerability.</p> |
| |
| <table border="0" class="table table-striped"><caption align="top">Column Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the database column.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>pattern</td> |
| |
| <td>String</td> |
| |
| <td>Use this attribute to insert a value or values from the log event in this column using a |
| PatternLayout pattern. Simply specify any legal pattern in this attribute. Either this |
| attribute, literal, or isEventTimestamp="true" must be specified, but not more |
| than one of these.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>literal</td> |
| |
| <td>String</td> |
| |
| <td> |
| |
| <p>Use this attribute to insert a literal value in this column. The value will be included directly in |
| the insert SQL, without any quoting (which means that if you want this to be a string, your value should |
| contain single quotes around it like this: literal="'Literal String'"). This is especially |
| useful for databases that don't support identity columns. For example, if you are using Oracle you could |
| specify literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL" to insert a unique ID in an ID column. |
| Either this attribute, pattern, or isEventTimestamp="true" must be specified, |
| but not more than one of these. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>parameter</td> |
| |
| <td>String</td> |
| |
| <td> |
| |
| <p>Use this attribute to insert an expression with a parameter marker '?' in this column. The value will be included directly in |
| the insert SQL, without any quoting (which means that if you want this to be a string, your value should |
| contain single quotes around it like this: |
| </p> |
| |
| <p> |
| <ColumnMapping name="instant" parameter="TIMESTAMPADD('MILLISECOND', ?, TIMESTAMP '1970-01-01')"/> |
| </p> |
| |
| <p> |
| You can only specify one of literal or parameter. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>isEventTimestamp</td> |
| |
| <td>boolean</td> |
| |
| <td>Use this attribute to insert the event timestamp in this column, which should be a SQL datetime. The |
| value will be inserted as a java.sql.Types.TIMESTAMP. Either this attribute (equal to |
| true), pattern, or isEventTimestamp must be specified, but not |
| more than one of these.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>isUnicode</td> |
| |
| <td>boolean</td> |
| |
| <td>This attribute is ignored unless pattern is specified. If true or omitted |
| (default), the value will be inserted as unicode (setNString or setNClob). |
| Otherwise, the value will be inserted non-unicode (setString or setClob).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>isClob</td> |
| |
| <td>boolean</td> |
| |
| <td>This attribute is ignored unless pattern is specified. Use this attribute to indicate |
| that the column stores Character Large Objects (CLOBs). If true, the value will be inserted |
| as a CLOB (setClob or setNClob). If false or omitted (default), |
| the value will be inserted as a VARCHAR or NVARCHAR (setString or setNString). |
| </td> |
| </tr> |
| </table> |
| |
| <table border="0" class="table table-striped"><caption align="top">ColumnMapping Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the database column.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>pattern</td> |
| |
| <td>String</td> |
| |
| <td>Use this attribute to insert a value or values from the log event in this column using a |
| PatternLayout pattern. Simply specify any legal pattern in this attribute. Either this |
| attribute, literal, or isEventTimestamp="true" must be specified, but not more |
| than one of these.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>literal</td> |
| |
| <td>String</td> |
| |
| <td>Use this attribute to insert a literal value in this column. The value will be included directly in |
| the insert SQL, without any quoting (which means that if you want this to be a string, your value should |
| contain single quotes around it like this: literal="'Literal String'"). This is especially |
| useful for databases that don't support identity columns. For example, if you are using Oracle you could |
| specify literal="NAME_OF_YOUR_SEQUENCE.NEXTVAL" to insert a unique ID in an ID column. |
| Either this attribute, pattern, or isEventTimestamp="true" must be specified, |
| but not more than one of these.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to format the LogEvent.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>type</td> |
| |
| <td>String</td> |
| |
| <td>Conversion type name, a fully-qualified class name.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here are a couple sample configurations for the JDBCAppender, as well as a sample factory implementation |
| that uses Commons Pooling and Commons DBCP to pool database connections: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <JDBC name="databaseAppender" tableName="dbo.application_log"> |
| <DataSource jndiName="java:/comp/env/jdbc/LoggingDataSource" /> |
| <Column name="eventDate" isEventTimestamp="true" /> |
| <Column name="level" pattern="%level" /> |
| <Column name="logger" pattern="%logger" /> |
| <Column name="message" pattern="%message" /> |
| <Column name="exception" pattern="%ex{full}" /> |
| </JDBC> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <JDBC name="databaseAppender" tableName="LOGGING.APPLICATION_LOG"> |
| <ConnectionFactory class="net.example.db.ConnectionFactory" method="getDatabaseConnection" /> |
| <Column name="EVENT_ID" literal="LOGGING.APPLICATION_LOG_SEQUENCE.NEXTVAL" /> |
| <Column name="EVENT_DATE" isEventTimestamp="true" /> |
| <Column name="LEVEL" pattern="%level" /> |
| <Column name="LOGGER" pattern="%logger" /> |
| <Column name="MESSAGE" pattern="%message" /> |
| <Column name="THROWABLE" pattern="%ex{full}" /> |
| </JDBC> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <div> |
| <pre class="prettyprint linenums lang-java">package net.example.db; |
| |
| import java.sql.Connection; |
| import java.sql.SQLException; |
| import java.util.Properties; |
| |
| import javax.sql.DataSource; |
| |
| import org.apache.commons.dbcp.DriverManagerConnectionFactory; |
| import org.apache.commons.dbcp.PoolableConnection; |
| import org.apache.commons.dbcp.PoolableConnectionFactory; |
| import org.apache.commons.dbcp.PoolingDataSource; |
| import org.apache.commons.pool.impl.GenericObjectPool; |
| |
| public class ConnectionFactory { |
| private static interface Singleton { |
| final ConnectionFactory INSTANCE = new ConnectionFactory(); |
| } |
| |
| private final DataSource dataSource; |
| |
| private ConnectionFactory() { |
| Properties properties = new Properties(); |
| properties.setProperty("user", "logging"); |
| properties.setProperty("password", "abc123"); // or get properties from some configuration file |
| |
| GenericObjectPool<PoolableConnection> pool = new GenericObjectPool<PoolableConnection>(); |
| DriverManagerConnectionFactory connectionFactory = new DriverManagerConnectionFactory( |
| "jdbc:mysql://example.org:3306/exampleDb", properties |
| ); |
| new PoolableConnectionFactory( |
| connectionFactory, pool, null, "SELECT 1", 3, false, false, Connection.TRANSACTION_READ_COMMITTED |
| ); |
| |
| this.dataSource = new PoolingDataSource(pool); |
| } |
| |
| public static Connection getDatabaseConnection() throws SQLException { |
| return Singleton.INSTANCE.dataSource.getConnection(); |
| } |
| }</pre></div> |
| |
| <p> |
| This appender is <a href="messages.html#MapMessage">MapMessage</a>-aware. |
| </p> |
| |
| <p> |
| The following configuration uses a MessageLayout to indicate that the Appender should match |
| the keys of a MapMessage to the names of ColumnMappings when setting the |
| values of the Appender's SQL INSERT statement. This let you insert rows for custom values in a |
| database table based on a Log4j MapMessage instead of values from LogEvents. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><Configuration status="debug"> |
| |
| <Appenders> |
| <Console name="STDOUT"> |
| <PatternLayout pattern="%C{1.} %m %level MDC%X%n"/> |
| </Console> |
| <Jdbc name="databaseAppender" tableName="dsLogEntry" ignoreExceptions="false"> |
| <DataSource jndiName="java:/comp/env/jdbc/TestDataSourceAppender" /> |
| <ColumnMapping name="Id" /> |
| <ColumnMapping name="ColumnA" /> |
| <ColumnMapping name="ColumnB" /> |
| <MessageLayout /> |
| </Jdbc> |
| </Appenders> |
| |
| <Loggers> |
| <Logger name="org.apache.logging.log4j.core.appender.db" level="debug" additivity="false"> |
| <AppenderRef ref="databaseAppender" /> |
| </Logger> |
| |
| <Root level="fatal"> |
| <AppenderRef ref="STDOUT"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration></pre></div> |
| </section> |
| <a name="JMSAppender"></a> |
| |
| <a name="JMSQueueAppender"></a> |
| <a name="JMSTopicAppender"></a> |
| <section> |
| <h3><a name="JMS_Appender"></a>JMS Appender</h3> |
| |
| <p>The JMS Appender sends the formatted log event to a JMS Destination.</p> |
| |
| <p> |
| 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 which use the <JMSQueue/> or |
| <JMSTopic/> elements will continue to work with the new <JMS/> |
| configuration element. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">JMS Appender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Default</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>factoryBindingName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required</i></td> |
| |
| <td>The name to locate in the Context that provides the |
| <a class="javadoc" href="http://download.oracle.com/javaee/5/api/javax/jms/ConnectionFactory.html">ConnectionFactory</a>. |
| This can be any subinterface of ConnectionFactory as well. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>factoryName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required</i></td> |
| |
| <td>The fully qualified class name that should be used to define the Initial Context Factory as defined in |
| <a class="javadoc" href="http://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#INITIAL_CONTEXT_FACTORY">INITIAL_CONTEXT_FACTORY</a>. |
| If a factoryName is specified without a providerURL a warning message will be logged as this is |
| likely to cause problems. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>null</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td><i>Required</i></td> |
| |
| <td> |
| The Layout to use to format the LogEvent. |
| <i>New since 2.9, in previous versions SerializedLayout was default.</i> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required</i></td> |
| |
| <td>The name of the Appender. </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>null</td> |
| |
| <td>The password to use to create the JMS connection.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>providerURL</td> |
| |
| <td>String</td> |
| |
| <td><i>Required</i></td> |
| |
| <td>The URL of the provider to use as defined by |
| <a class="javadoc" href="http://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#PROVIDER_URL">PROVIDER_URL</a>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>destinationBindingName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required</i></td> |
| |
| <td> |
| The name to use to locate the |
| <a class="javadoc" href="http://download.oracle.com/javaee/5/api/javax/jms/Destination.html">Destination</a>. |
| 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. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>securityPrincipalName</td> |
| |
| <td>String</td> |
| |
| <td>null</td> |
| |
| <td>The name of the identity of the Principal as specified by |
| <a class="javadoc" href="http://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#SECURITY_PRINCIPAL">SECURITY_PRINCIPAL</a>. |
| If a securityPrincipalName is specified without securityCredentials a warning message will be |
| logged as this is likely to cause problems.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>securityCredentials</td> |
| |
| <td>String</td> |
| |
| <td>null</td> |
| |
| <td>The security credentials for the principal as specified by |
| <a class="javadoc" href="http://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#SECURITY_CREDENTIALS">SECURITY_CREDENTIALS</a>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>true</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFail</td> |
| |
| <td>boolean</td> |
| |
| <td>false</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>reconnectIntervalMillis</td> |
| |
| <td>long</td> |
| |
| <td>5000</td> |
| |
| <td>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.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>urlPkgPrefixes</td> |
| |
| <td>String</td> |
| |
| <td>null</td> |
| |
| <td>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 |
| <a class="javadoc" href="http://download.oracle.com/javase/7/docs/api/javax/naming/Context.html#URL_PKG_PREFIXES">URL_PKG_PREFIXES</a>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>userName</td> |
| |
| <td>String</td> |
| |
| <td>null</td> |
| |
| <td>The user id used to create the JMS connection.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample JMS Appender configuration: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?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></pre></div> |
| |
| |
| <p> |
| To map your Log4j MapMessages to JMS javax.jms.MapMessages, set the |
| layout of the appender to MessageLayout with <MessageLayout /> (Since 2.9.): |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?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></pre></div> |
| |
| </section> |
| <a name="JPAAppender"></a> |
| <section> |
| <h3><a name="JPAAppender"></a>JPAAppender</h3> |
| |
| <p> |
| As of Log4j 2.11.0, JPA support has moved from the existing module log4j-core to the new module log4j-jpa. |
| </p> |
| |
| <p>The JPAAppender writes log events to a relational database table using the Java Persistence API 2.1. |
| It requires the API and a provider implementation be on the classpath. It also requires a decorated entity |
| configured to persist to the table desired. The entity should either extend |
| org.apache.logging.log4j.core.appender.db.jpa.BasicLogEventEntity (if you mostly want to |
| use the default mappings) and provide at least an @Id property, or |
| org.apache.logging.log4j.core.appender.db.jpa.AbstractLogEventWrapperEntity (if you want |
| to significantly customize the mappings). See the Javadoc for these two classes for more information. You |
| can also consult the source code of these two classes as an example of how to implement the entity.</p> |
| |
| <table border="0" class="table table-striped"><caption align="top">JPAAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter may be |
| used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>If an integer greater than 0, this causes the appender to buffer log events and flush whenever the |
| buffer reaches this size.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>entityClassName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The fully qualified name of the concrete LogEventWrapperEntity implementation that |
| has JPA annotations mapping it to a database table.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>persistenceUnitName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the JPA persistence unit that should be used for persisting log |
| events.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample configuration for the JPAAppender. The first XML sample is the Log4j configuration file, |
| the second is the persistence.xml file. EclipseLink is assumed here, but any JPA 2.1 or higher |
| provider will do. You should <i>always</i> create a <i>separate</i> persistence unit for logging, for |
| two reasons. First, <shared-cache-mode> <i>must</i> be set to "NONE," which is usually |
| not desired in normal JPA usage. Also, for performance reasons the logging entity should be isolated in its |
| own persistence unit away from all other entities and you should use a non-JTA data source. Note that your |
| persistence unit <i>must</i> also contain <class> elements for all of the |
| org.apache.logging.log4j.core.appender.db.jpa.converter converter classes. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <JPA name="databaseAppender" persistenceUnitName="loggingPersistenceUnit" |
| entityClassName="com.example.logging.JpaLogEntity" /> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence |
| http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd" |
| version="2.1"> |
| |
| <persistence-unit name="loggingPersistenceUnit" transaction-type="RESOURCE_LOCAL"> |
| <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextMapJsonAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.ContextStackJsonAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.MarkerAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.MessageAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.StackTraceElementAttributeConverter</class> |
| <class>org.apache.logging.log4j.core.appender.db.jpa.converter.ThrowableAttributeConverter</class> |
| <class>com.example.logging.JpaLogEntity</class> |
| <non-jta-data-source>jdbc/LoggingDataSource</non-jta-data-source> |
| <shared-cache-mode>NONE</shared-cache-mode> |
| </persistence-unit> |
| |
| </persistence></pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-java">package com.example.logging; |
| ... |
| @Entity |
| @Table(name="application_log", schema="dbo") |
| public class JpaLogEntity extends BasicLogEventEntity { |
| private static final long serialVersionUID = 1L; |
| private long id = 0L; |
| |
| public TestEntity() { |
| super(null); |
| } |
| public TestEntity(LogEvent wrappedEvent) { |
| super(wrappedEvent); |
| } |
| |
| @Id |
| @GeneratedValue(strategy = GenerationType.IDENTITY) |
| @Column(name = "id") |
| public long getId() { |
| return this.id; |
| } |
| |
| public void setId(long id) { |
| this.id = id; |
| } |
| |
| // If you want to override the mapping of any properties mapped in BasicLogEventEntity, |
| // just override the getters and re-specify the annotations. |
| }</pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-java">package com.example.logging; |
| ... |
| @Entity |
| @Table(name="application_log", schema="dbo") |
| public class JpaLogEntity extends AbstractLogEventWrapperEntity { |
| private static final long serialVersionUID = 1L; |
| private long id = 0L; |
| |
| public TestEntity() { |
| super(null); |
| } |
| public TestEntity(LogEvent wrappedEvent) { |
| super(wrappedEvent); |
| } |
| |
| @Id |
| @GeneratedValue(strategy = GenerationType.IDENTITY) |
| @Column(name = "logEventId") |
| public long getId() { |
| return this.id; |
| } |
| |
| public void setId(long id) { |
| this.id = id; |
| } |
| |
| @Override |
| @Enumerated(EnumType.STRING) |
| @Column(name = "level") |
| public Level getLevel() { |
| return this.getWrappedEvent().getLevel(); |
| } |
| |
| @Override |
| @Column(name = "logger") |
| public String getLoggerName() { |
| return this.getWrappedEvent().getLoggerName(); |
| } |
| |
| @Override |
| @Column(name = "message") |
| @Convert(converter = MyMessageConverter.class) |
| public Message getMessage() { |
| return this.getWrappedEvent().getMessage(); |
| } |
| ... |
| }</pre></div> |
| </section> |
| <a name="HttpAppender"></a> |
| <section> |
| <h3><a name="HttpAppender"></a>HttpAppender</h3> |
| |
| <p> |
| The HttpAppender sends log events over HTTP. A Layout must be provided to format the LogEvent. |
| </p> |
| |
| <p> |
| Will set the Content-Type header according to the layout. Additional headers can be specified |
| with embedded Property elements. |
| </p> |
| |
| <p> |
| Will wait for response from server, and throw error if no 2xx response is received. |
| </p> |
| |
| <p> |
| Implemented with |
| <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/net/HttpURLConnection.html">HttpURLConnection</a>. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">HttpAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>Ssl</td> |
| |
| <td>SslConfiguration</td> |
| |
| <td>Contains the configuration for the KeyStore and TrustStore for https. |
| Optional, uses Java runtime defaults if not specified. See <a href="#SSL">SSL</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>verifyHostname</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to verify server hostname against certificate. Only valid for https. |
| Optional, defaults to true</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>url</td> |
| |
| <td>string</td> |
| |
| <td>The URL to use. The URL scheme must be "http" or "https".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>method</td> |
| |
| <td>string</td> |
| |
| <td>The HTTP method to use. Optional, default is "POST".</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>connectTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The connect timeout in milliseconds. Optional, default is 0 (infinite timeout).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>readTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The socket read timeout in milliseconds. Optional, default is 0 (infinite timeout).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>headers</td> |
| |
| <td>Property[]</td> |
| |
| <td>Additional HTTP headers to use. The values support <a href="lookups.html">lookups</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample HttpAppender configuration snippet: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| ... |
| <Appenders> |
| <Http name="Http" url="https://localhost:9200/test/log4j/"> |
| <Property name="X-Java-Runtime" value="$${java:runtime}" /> |
| <JsonLayout properties="true"/> |
| <SSL> |
| <KeyStore location="log4j2-keystore.jks" passwordEnvironmentVariable="KEYSTORE_PASSWORD"/> |
| <TrustStore location="truststore.jks" passwordFile="${sys:user.home}/truststore.pwd"/> |
| </SSL> |
| </Http> |
| </Appenders></pre></div> |
| </section> |
| <a name="KafkaAppender"></a> |
| <section> |
| <h3><a name="KafkaAppender"></a>KafkaAppender</h3> |
| |
| <p> |
| The KafkaAppender logs events to an <a class="externalLink" href="https://kafka.apache.org/">Apache Kafka</a> topic. |
| Each log event is sent as a Kafka record. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">KafkaAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>topic</td> |
| |
| <td>String</td> |
| |
| <td>The Kafka topic to use. Required.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>key</td> |
| |
| <td>String</td> |
| |
| <td>The key that will be sent to Kafka with every message. Optional value defaulting to null. |
| Any of the <a href="./lookups.html">Lookups</a>) can be included. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td> |
| The Layout to use to format the LogEvent. Required, there is no default. |
| <i>New since 2.9, in previous versions <PatternLayout pattern="%m"/> was default.</i> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender. Required.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>syncSend</td> |
| |
| <td>boolean</td> |
| |
| <td>The default is true, causing sends to block until the record has been acknowledged by the |
| Kafka server. When set to false sends return immediately, allowing for lower latency and significantly |
| higher throughput. <i>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 error to StatusLogger and the log event will be dropped |
| (the ignoreExceptions parameter will not be effective). Log events may arrive out of order to the Kafka server.</i> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>properties</td> |
| |
| <td>Property[]</td> |
| |
| <td> |
| You can set properties in <a class="externalLink" href="http://kafka.apache.org/documentation.html#producerconfigs">Kafka producer properties</a>. |
| 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. |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample KafkaAppender configuration snippet: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| ... |
| <Appenders> |
| <Kafka name="Kafka" topic="log-test"> |
| <PatternLayout pattern="%date %message"/> |
| <Property name="bootstrap.servers">localhost:9092</Property> |
| </Kafka> |
| </Appenders></pre></div> |
| |
| <p> |
| 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 |
| <a class="externalLink" href="http://logging.apache.org/log4j/2.x/manual/appenders.html#AsyncAppender">Async appender</a> and/or set syncSend to |
| false to log asynchronously. |
| </p> |
| |
| <p> |
| This appender requires the <a class="externalLink" href="http://kafka.apache.org/">Kafka client library</a>. Note that you need to use a version of |
| the Kafka client library matching the Kafka server used. |
| </p> |
| |
| <p> |
| <i>Note:</i>Make sure to not let org.apache.kafka log to a Kafka appender on DEBUG level, |
| since that will cause recursive logging: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| ... |
| <Loggers> |
| <Root level="DEBUG"> |
| <AppenderRef ref="Kafka"/> |
| </Root> |
| <Logger name="org.apache.kafka" level="INFO" /> <!-- avoid recursive logging --> |
| </Loggers></pre></div> |
| </section> |
| <a name="MemoryMappedFileAppender"></a> |
| <section> |
| <h3><a name="MemoryMappedFileAppender"></a>MemoryMappedFileAppender</h3> |
| |
| <p><i>New since 2.1. Be aware that this is a new addition, and although it has been |
| tested on several platforms, it does not have as much track record as the other file appenders.</i></p> |
| |
| <p> |
| The MemoryMappedFileAppender maps a part of the specified file into memory |
| and writes log events to this memory, relying on the operating system's |
| virtual memory manager to synchronize the changes to the storage device. |
| The main benefit of using memory mapped files is I/O performance. Instead of making system |
| calls to write to disk, this appender can simply change the program's local memory, |
| which is orders of magnitude faster. Also, in most operating systems the memory |
| region mapped actually is the kernel's <a class="externalLink" href="http://en.wikipedia.org/wiki/Page_cache">page |
| cache</a> (file cache), meaning that no copies need to be created in user space. |
| (TODO: performance tests that compare performance of this appender to |
| RandomAccessFileAppender and FileAppender.) |
| </p> |
| |
| <p> |
| There is some overhead with mapping a file region into memory, |
| especially very large regions (half a gigabyte or more). |
| The default region size is 32 MB, which should strike a reasonable balance |
| between the frequency and the duration of remap operations. |
| (TODO: performance test remapping various sizes.) |
| </p> |
| |
| <p> |
| Similar to the FileAppender and the RandomAccessFileAppender, |
| MemoryMappedFileAppender uses a MemoryMappedFileManager to actually perform the |
| file I/O. While MemoryMappedFileAppender from different Configurations |
| cannot be shared, the MemoryMappedFileManagers can be if the Manager is |
| accessible. For example, two web applications in a servlet container can have |
| their own configuration and safely write to the same file if Log4j |
| is in a ClassLoader that is common to both of them. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">MemoryMappedFileAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>append</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be appended to the end |
| of the file. When set to false, the file will be cleared before |
| new records are written. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the file to write to. If the file, or any of its |
| parent directories, do not exist, they will be created. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filters</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this |
| Appender. More than one Filter may be used by using a CompositeFilter. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| |
| <p>When set to true, each write will be followed by a |
| call to <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/api/java/nio/MappedByteBuffer.html#force()">MappedByteBuffer.force()</a>. |
| This will guarantee the data is written to the storage device. |
| </p> |
| |
| <p>The default for this parameter is false. |
| This means that the data is written to the storage device even |
| if the Java process crashes, but there may be data loss if the |
| operating system crashes.</p> |
| |
| <p>Note that manually forcing a sync on every log event loses most |
| of the performance benefits of using a memory mapped file.</p> |
| |
| <p>Flushing after every write is only useful when using this |
| appender with synchronous loggers. Asynchronous loggers and |
| appenders will automatically flush at the end of a batch of events, |
| even if immediateFlush is set to false. This also guarantees |
| the data is written to disk but is more efficient. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>regionLength</td> |
| |
| <td>int</td> |
| |
| <td>The length of the mapped region, defaults to 32 MB |
| (32 * 1024 * 1024 bytes). This parameter must be a value |
| between 256 and 1,073,741,824 (1 GB or 2^30); |
| values outside this range will be adjusted to the closest valid |
| value. |
| Log4j will round the specified value up to the nearest power of two.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample MemoryMappedFile configuration: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <MemoryMappedFile name="MyFile" fileName="logs/app.log"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| </MemoryMappedFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="MyFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="NoSQLAppender"></a> |
| <section> |
| <h3><a name="NoSQLAppender"></a>NoSQLAppender</h3> |
| |
| <p> |
| The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface. |
| Provider implementations currently exist for MongoDB and Apache CouchDB, and writing a custom provider is |
| quite simple. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">NoSQLAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter may be |
| used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>If an integer greater than 0, this causes the appender to buffer log events and flush whenever the |
| buffer reaches this size.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>NoSqlProvider</td> |
| |
| <td>NoSQLProvider<C extends NoSQLConnection<W, T extends NoSQLObject<W>>></td> |
| |
| <td><i>Required.</i> The NoSQL provider that provides connections to the chosen NoSQL database.</td> |
| </tr> |
| </table> |
| |
| <p>You specify which NoSQL provider to use by specifying the appropriate configuration element within the |
| <NoSql> element. The types currently supported are <MongoDb> and |
| <CouchDb>. To create your own custom provider, read the JavaDoc for the |
| NoSQLProvider, NoSQLConnection, and NoSQLObject classes and the |
| documentation about creating Log4j plugins. We recommend you review the source code for the MongoDB and |
| CouchDB providers as a guide for creating your own provider. |
| </p> |
| |
| <p> |
| The following example demonstrates how log events are persisted in NoSQL databases if represented in a JSON |
| format: |
| </p> |
| |
| <div> |
| <pre class="prettyprint lang-javascript">{ |
| "level": "WARN", |
| "loggerName": "com.example.application.MyClass", |
| "message": "Something happened that you might want to know about.", |
| "source": { |
| "className": "com.example.application.MyClass", |
| "methodName": "exampleMethod", |
| "fileName": "MyClass.java", |
| "lineNumber": 81 |
| }, |
| "marker": { |
| "name": "SomeMarker", |
| "parent" { |
| "name": "SomeParentMarker" |
| } |
| }, |
| "threadName": "Thread-1", |
| "millis": 1368844166761, |
| "date": "2013-05-18T02:29:26.761Z", |
| "thrown": { |
| "type": "java.sql.SQLException", |
| "message": "Could not insert record. Connection lost.", |
| "stackTrace": [ |
| { "className": "org.example.sql.driver.PreparedStatement$1", "methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 1049 }, |
| { "className": "org.example.sql.driver.PreparedStatement", "methodName": "executeUpdate", "fileName": "PreparedStatement.java", "lineNumber": 738 }, |
| { "className": "com.example.application.MyClass", "methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 }, |
| { "className": "com.example.application.MainClass", "methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 } |
| ], |
| "cause": { |
| "type": "java.io.IOException", |
| "message": "Connection lost.", |
| "stackTrace": [ |
| { "className": "java.nio.channels.SocketChannel", "methodName": "write", "fileName": null, "lineNumber": -1 }, |
| { "className": "org.example.sql.driver.PreparedStatement$1", "methodName": "responder", "fileName": "PreparedStatement.java", "lineNumber": 1032 }, |
| { "className": "org.example.sql.driver.PreparedStatement", "methodName": "executeUpdate", "fileName": "PreparedStatement.java", "lineNumber": 738 }, |
| { "className": "com.example.application.MyClass", "methodName": "exampleMethod", "fileName": "MyClass.java", "lineNumber": 81 }, |
| { "className": "com.example.application.MainClass", "methodName": "main", "fileName": "MainClass.java", "lineNumber": 52 } |
| ] |
| } |
| }, |
| "contextMap": { |
| "ID": "86c3a497-4e67-4eed-9d6a-2e5797324d7b", |
| "username": "JohnDoe" |
| }, |
| "contextStack": [ |
| "topItem", |
| "anotherItem", |
| "bottomItem" |
| ] |
| }</pre></div> |
| </section> |
| <a name="NoSQLAppenderMongoDB"></a> |
| <section> |
| <h3><a name="NoSQLAppender_for_MongoDB"></a>NoSQLAppender for MongoDB</h3> |
| |
| <p> |
| Starting with Log4 2.11.0, we provide two MongoDB modules: |
| </p> |
| |
| <ul> |
| |
| <li>log4j-mongodb2 defines the configuration element <a href="#NoSQLAppenderMongoDB2">MongoDb2</a> matching the MongoDB Driver version 2.</li> |
| |
| <li>log4j-mongodb3 defines the configuration element <a href="#NoSQLAppenderMongoDB3">MongoDb3</a> matching the MongoDB Driver version 3.</li> |
| </ul> |
| |
| <p> |
| We no longer provide the module log4j-mongodb. |
| </p> |
| |
| <p> |
| The module log4j-mongodb2 aliases the old configuration element MongoDb to <a href="#NoSQLAppenderMongoDB2">MongoDb2</a>. |
| </p> |
| </section> |
| <a name="NoSQLAppenderMongoDB2"></a> |
| <section> |
| <h3><a name="NoSQLAppender_for_MongoDB_2"></a>NoSQLAppender for MongoDB 2</h3> |
| |
| <p> |
| This section details specializations of the <a href="#NoSQLAppender">NoSQLAppender</a> provider for MongoDB using |
| the MongoDB driver version 2. The NoSQLAppender Appender writes log events to a NoSQL database using an |
| internal lightweight provider interface. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">MongoDB2 Provider Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>collectionName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the MongoDB collection to insert the events into.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>writeConcernConstant</td> |
| |
| <td>Field</td> |
| |
| <td>By default, the MongoDB provider inserts records with the instructions |
| com.mongodb.WriteConcern.ACKNOWLEDGED. Use this optional attribute to specify the name of |
| a constant other than ACKNOWLEDGED.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>writeConcernConstantClass</td> |
| |
| <td>Class</td> |
| |
| <td>If you specify writeConcernConstant, you can use this attribute to specify a class other |
| than com.mongodb.WriteConcern to find the constant on (to create your own custom |
| instructions).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>factoryClassName</td> |
| |
| <td>Class</td> |
| |
| <td>To provide a connection to the MongoDB database, you can use this attribute and |
| factoryMethodName to specify a class and static method to get the connection from. The |
| method must return a com.mongodb.DB or a com.mongodb.MongoClient. If the |
| DB is not authenticated, you must also specify a username and |
| password. If you use the factory method for providing a connection, you must not specify |
| the databaseName, server, or port attributes.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>factoryMethodName</td> |
| |
| <td>Method</td> |
| |
| <td>See the documentation for attribute factoryClassName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>databaseName</td> |
| |
| <td>String</td> |
| |
| <td>If you do not specify a factoryClassName and factoryMethodName for providing |
| a MongoDB connection, you must specify a MongoDB database name using this attribute. You must also |
| specify a username and password. You can optionally also specify a |
| server (defaults to localhost), and a port (defaults to the default MongoDB |
| port).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>server</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>port</td> |
| |
| <td>int</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>username</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName and factoryClassName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName and factoryClassName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>capped</td> |
| |
| <td>boolean</td> |
| |
| <td>Enable support for <a class="externalLink" href="https://docs.mongodb.com/manual/core/capped-collections/">capped collections</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>collectionSize</td> |
| |
| <td>int</td> |
| |
| <td>Specify the size in bytes of the capped collection to use if enabled. The minimum size is 4096 bytes, |
| and larger sizes will be increased to the nearest integer multiple of 256. See the capped collection documentation |
| linked above for more information.</td> |
| </tr> |
| </table> |
| |
| <p> |
| This appender is <a href="messages.html#MapMessage">MapMessage</a>-aware. |
| </p> |
| |
| <p> |
| Here are a few sample configurations for the NoSQLAppender and MongoDB2 provider: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <NoSql name="databaseAppender"> |
| <MongoDb2 databaseName="applicationDb" collectionName="applicationLog" server="mongo.example.org" |
| username="loggingUser" password="abc123" /> |
| </NoSql> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <NoSql name="databaseAppender"> |
| <MongoDb2 collectionName="applicationLog" factoryClassName="org.example.db.ConnectionFactory" |
| factoryMethodName="getNewMongoClient" /> |
| </NoSql> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| Starting in Log4j version 2.11.0, the provider element name is MongoDb2. |
| The name MongoDb is now a deprecated alias for MongoDb2. |
| </p> |
| </section> |
| <a name="NoSQLAppenderMongoDB3"></a> |
| <section> |
| <h3><a name="NoSQLAppender_for_MongoDB_3"></a>NoSQLAppender for MongoDB 3</h3> |
| |
| <p> |
| This section details specializations of the <a href="#NoSQLAppender">NoSQLAppender</a> provider for MongoDB using |
| the MongoDB driver version 3. The NoSQLAppender Appender writes log events to a NoSQL database using an |
| internal lightweight provider interface. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">MongoDB3 Provider Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>collectionName</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> The name of the MongoDB collection to insert the events into.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>writeConcernConstant</td> |
| |
| <td>Field</td> |
| |
| <td>By default, the MongoDB provider inserts records with the instructions |
| com.mongodb.WriteConcern.ACKNOWLEDGED. Use this optional attribute to specify the name of |
| a constant other than ACKNOWLEDGED.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>writeConcernConstantClass</td> |
| |
| <td>Class</td> |
| |
| <td>If you specify writeConcernConstant, you can use this attribute to specify a class other |
| than com.mongodb.WriteConcern to find the constant on (to create your own custom |
| instructions).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>factoryClassName</td> |
| |
| <td>Class</td> |
| |
| <td>To provide a connection to the MongoDB database, you can use this attribute and |
| factoryMethodName to specify a class and static method to get the connection from. The |
| method must return a com.mongodb.client.MongoDatabase or a com.mongodb.MongoClient. If the |
| com.mongodb.client.MongoDatabase is not authenticated, you must also specify a username and |
| password. If you use the factory method for providing a connection, you must not specify |
| the databaseName, server, or port attributes.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>factoryMethodName</td> |
| |
| <td>Method</td> |
| |
| <td>See the documentation for attribute factoryClassName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>databaseName</td> |
| |
| <td>String</td> |
| |
| <td>If you do not specify a factoryClassName and factoryMethodName for providing |
| a MongoDB connection, you must specify a MongoDB database name using this attribute. You must also |
| specify a username and password. You can optionally also specify a |
| server (defaults to localhost), and a port (defaults to the default MongoDB |
| port).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>server</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>port</td> |
| |
| <td>int</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>username</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName and factoryClassName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName and factoryClassName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>capped</td> |
| |
| <td>boolean</td> |
| |
| <td>Enable support for <a class="externalLink" href="https://docs.mongodb.com/manual/core/capped-collections/">capped collections</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>collectionSize</td> |
| |
| <td>int</td> |
| |
| <td>Specify the size in bytes of the capped collection to use if enabled. The minimum size is 4096 bytes, |
| and larger sizes will be increased to the nearest integer multiple of 256. See the capped collection documentation |
| linked above for more information.</td> |
| </tr> |
| </table> |
| |
| <p> |
| This appender is <a href="messages.html#MapMessage">MapMessage</a>-aware. |
| </p> |
| |
| <p> |
| Here are a few sample configurations for the NoSQLAppender and MongoDB3 provider: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <NoSql name="databaseAppender"> |
| <MongoDb3 databaseName="applicationDb" collectionName="applicationLog" server="mongo.example.org" |
| username="loggingUser" password="abc123" /> |
| </NoSql> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <NoSql name="databaseAppender"> |
| <MongoDb3 collectionName="applicationLog" factoryClassName="org.example.db.ConnectionFactory" |
| factoryMethodName="getNewMongoClient" /> |
| </NoSql> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="NoSQLAppenderApacheCouchDB"></a> |
| <section> |
| <h3><a name="NoSQLAppender_for_Apache_CouchDB"></a>NoSQLAppender for Apache CouchDB</h3> |
| |
| <p> |
| This section details specializations of the <a href="#NoSQLAppender">NoSQLAppender</a> provider for CouchDB. |
| The NoSQLAppender writes log events to a NoSQL database using an internal lightweight provider interface. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">CouchDB Provider Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>factoryClassName</td> |
| |
| <td>Class</td> |
| |
| <td>To provide a connection to the CouchDB database, you can use this attribute and |
| factoryMethodName to specify a class and static method to get the connection from. The |
| method must return a org.lightcouch.CouchDbClient or a |
| org.lightcouch.CouchDbProperties. If you use the factory method for providing a connection, |
| you must not specify the databaseName, protocol, server, |
| port, username, or password attributes.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>factoryMethodName</td> |
| |
| <td>Method</td> |
| |
| <td>See the documentation for attribute factoryClassName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>databaseName</td> |
| |
| <td>String</td> |
| |
| <td>If you do not specify a factoryClassName and factoryMethodName for providing |
| a CouchDB connection, you must specify a CouchDB database name using this attribute. You must also |
| specify a username and password. You can optionally also specify a |
| protocol (defaults to http), server (defaults to localhost), and a |
| port (defaults to 80 for http and 443 for https).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>protocol</td> |
| |
| <td>String</td> |
| |
| <td>Must either be "http" or "https." See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>server</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>port</td> |
| |
| <td>int</td> |
| |
| <td>See the documentation for attribute databaseName.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>username</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>String</td> |
| |
| <td>See the documentation for attributes databaseName.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here are a few sample configurations for the NoSQLAppender and CouchDB provider: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums lang-xml"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <NoSql name="databaseAppender"> |
| <CouchDb databaseName="applicationDb" protocol="https" server="couch.example.org" |
| username="loggingUser" password="abc123" /> |
| </NoSql> |
| </Appenders> |
| <Loggers> |
| <Root level="warn"> |
| <AppenderRef ref="databaseAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="OutputStreamAppender"></a> |
| <section> |
| <h3><a name="OutputStreamAppender"></a>OutputStreamAppender</h3> |
| |
| <p> |
| The OutputStreamAppender provides the base for many of the other Appenders such as the File and Socket |
| appenders that write the event to an Output Stream. It cannot be directly configured. Support for |
| immediateFlush and buffering is provided by the OutputStreamAppender. The OutputStreamAppender uses an |
| OutputStreamManager to handle the actual I/O, allowing the stream to be shared by Appenders in multiple |
| configurations. |
| </p> |
| </section> |
| <a name="RandomAccessFileAppender"></a> |
| <section> |
| <h3><a name="RandomAccessFileAppender"></a>RandomAccessFileAppender</h3> |
| |
| <p> |
| The RandomAccessFileAppender is similar to the standard |
| <a href="#FileAppender">FileAppender</a> |
| except it is always buffered (this cannot be switched off) |
| and internally it uses a |
| ByteBuffer + RandomAccessFile |
| instead of a |
| BufferedOutputStream. |
| We saw a 20-200% performance improvement compared to |
| FileAppender with "bufferedIO=true" in our |
| <a href="../performance.html#whichAppender">measurements</a>. |
| Similar to the FileAppender, |
| RandomAccessFileAppender uses a RandomAccessFileManager to actually perform the |
| file I/O. While RandomAccessFileAppender |
| from different Configurations |
| cannot be shared, the RandomAccessFileManagers can be if the Manager is |
| accessible. For example, two web applications in a |
| servlet container can have |
| their own configuration and safely |
| write to the same file if Log4j |
| is in a ClassLoader that is common to |
| both of them. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RandomAccessFileAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>append</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be appended to the end |
| of the file. When set to false, |
| the file will be cleared before |
| new records are written. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the file to write to. If the file, or any of its |
| parent directories, do not exist, |
| they will be created. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filters</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this |
| Appender. More than one Filter |
| may be used by using a CompositeFilter. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| |
| <p> |
| When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance. |
| </p> |
| |
| <p> |
| Flushing after every write is only useful when using this |
| appender with synchronous loggers. Asynchronous loggers and |
| appenders will automatically flush at the end of a batch of events, |
| even if immediateFlush is set to false. This also guarantees |
| the data is written to disk but is more efficient. |
| </p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>The buffer size, defaults to 262,144 bytes (256 * 1024).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Here is a sample RandomAccessFile configuration: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RandomAccessFile name="MyFile" fileName="logs/app.log"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| </RandomAccessFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="MyFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="RewriteAppender"></a> |
| <section> |
| <h3><a name="RewriteAppender"></a>RewriteAppender</h3> |
| |
| <p> |
| The RewriteAppender allows the LogEvent to manipulated before it is processed by another Appender. This |
| can be used to mask sensitive information such as passwords or to inject information into each event. |
| The RewriteAppender must be configured with a <a href="RewritePolicy">RewritePolicy</a>. The |
| RewriteAppender should be configured after any Appenders it references to allow it to shut down properly. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RewriteAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>AppenderRef</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appenders to call after the LogEvent has been manipulated. Multiple AppenderRef |
| elements can be configured.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>rewritePolicy</td> |
| |
| <td>RewritePolicy</td> |
| |
| <td>The RewritePolicy that will manipulate the LogEvent.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| <section> |
| <h4><a name="RewritePolicy"></a>RewritePolicy</h4> |
| |
| <p> |
| RewritePolicy is an interface that allows implementations to inspect and possibly modify LogEvents |
| before they are passed to Appender. RewritePolicy declares a single method named rewrite that must |
| be implemented. The method is passed the LogEvent and can return the same event or create a new one. |
| </p> |
| <section> |
| <h5><a name="MapRewritePolicy"></a>MapRewritePolicy</h5> |
| |
| <p> |
| MapRewritePolicy will evaluate LogEvents that contain a MapMessage and will add or update |
| elements of the Map. |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mode</td> |
| |
| <td>String</td> |
| |
| <td>"Add" or "Update"</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>keyValuePair</td> |
| |
| <td>KeyValuePair[]</td> |
| |
| <td>An array of keys and their values.</td> |
| </tr> |
| </table> |
| |
| <p> |
| The following configuration shows a RewriteAppender configured to add a product key and its value |
| to the MapMessage.: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Rewrite name="rewrite"> |
| <AppenderRef ref="STDOUT"/> |
| <MapRewritePolicy mode="Add"> |
| <KeyValuePair key="product" value="TestProduct"/> |
| </MapRewritePolicy> |
| </Rewrite> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Rewrite"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section><section> |
| <h5><a name="PropertiesRewritePolicy"></a>PropertiesRewritePolicy</h5> |
| |
| <p> |
| PropertiesRewritePolicy will add properties configured on the policy to the ThreadContext Map |
| being logged. The properties will not be added to the actual ThreadContext Map. The property |
| values may contain variables that will be evaluated when the configuration is processed as |
| well as when the event is logged. |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>properties</td> |
| |
| <td>Property[]</td> |
| |
| <td>One of more Property elements to define the keys and values to be added to the ThreadContext Map.</td> |
| </tr> |
| </table> |
| |
| <p> |
| The following configuration shows a RewriteAppender configured to add a product key and its value |
| to the MapMessage: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Rewrite name="rewrite"> |
| <AppenderRef ref="STDOUT"/> |
| <PropertiesRewritePolicy> |
| <Property name="user">${sys:user.name}</Property> |
| <Property name="env">${sys:environment}</Property> |
| </PropertiesRewritePolicy> |
| </Rewrite> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Rewrite"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section><section> |
| <h5><a name="LoggerNameLevelRewritePolicy"></a>LoggerNameLevelRewritePolicy</h5> |
| |
| <p> |
| You can use this policy to make loggers in third party code less chatty by changing event levels. |
| The LoggerNameLevelRewritePolicy will rewrite log event levels for a given logger name prefix. |
| You configure a LoggerNameLevelRewritePolicy with a logger name prefix and a pairs of levels, |
| where a pair defines a source level and a target level. |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>logger</td> |
| |
| <td>String</td> |
| |
| <td>A logger name used as a prefix to test each event's logger name.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>LevelPair</td> |
| |
| <td>KeyValuePair[]</td> |
| |
| <td>An array of keys and their values, each key is a source level, each value a target level.</td> |
| </tr> |
| </table> |
| |
| <p> |
| The following configuration shows a RewriteAppender configured to map level INFO to DEBUG and level |
| WARN to INFO for all loggers that start with com.foo.bar. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp"> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <Rewrite name="rewrite"> |
| <AppenderRef ref="STDOUT"/> |
| <LoggerNameLevelRewritePolicy logger="com.foo.bar"> |
| <KeyValuePair key="INFO" value="DEBUG"/> |
| <KeyValuePair key="WARN" value="INFO"/> |
| </LoggerNameLevelRewritePolicy> |
| </Rewrite> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Rewrite"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section></section></section> |
| <a name="RollingFileAppender"></a> |
| <section> |
| <h3><a name="RollingFileAppender"></a>RollingFileAppender</h3> |
| |
| <p>The RollingFileAppender is an OutputStreamAppender that writes to the File named in the fileName parameter |
| and rolls the file over according the TriggeringPolicy and the RolloverPolicy. The |
| RollingFileAppender uses a RollingFileManager (which extends OutputStreamManager) to actually perform the |
| file I/O and perform the rollover. While RolloverFileAppenders from different Configurations cannot be |
| shared, the RollingFileManagers can be if the Manager is accessible. For example, two web applications in a |
| servlet container can have their own configuration and safely |
| write to the same file if Log4j is in a ClassLoader that is common to both of them.</p> |
| |
| <p> |
| A RollingFileAppender requires a <a href="#TriggeringPolicies">TriggeringPolicy</a> and a |
| <a href="#RolloverStrategies">RolloverStrategy</a>. The triggering policy determines if a rollover should |
| be performed while the RolloverStrategy defines how the rollover should be done. If no RolloverStrategy |
| is configured, RollingFileAppender will use the <a href="#DefaultRolloverStrategy">DefaultRolloverStrategy</a>. |
| Since log4j-2.5, a <a href="#CustomDeleteOnRollover">custom delete action</a> can be configured in the |
| DefaultRolloverStrategy to run at rollover. Since 2.8 if no file name is configured then |
| <a href="#DirectWriteRolloverStrategy">DirectWriteRolloverStrategy</a> will be used instead of |
| DefaultRolloverStrategy. |
| Since log4j-2.9, a <a href="#CustomPosixViewAttributeOnRollover">custom POSIX file attribute view action</a> can be configured in the |
| DefaultRolloverStrategy to run at rollover, if not defined, inherited POSIX file attribute view from the RollingFileAppender will be applied. |
| </p> |
| |
| <p> |
| File locking is not supported by the RollingFileAppender. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RollingFileAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>append</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be appended to the end of the file. When set to false, |
| the file will be cleared before new records are written.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferedIO</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be written to a buffer and the data will be written to |
| disk when the buffer is full or, if immediateFlush is set, when the record is written. |
| File locking cannot be used with bufferedIO. Performance tests have shown that using buffered I/O |
| significantly improves performance, even if immediateFlush is enabled.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>When bufferedIO is true, this is the buffer size, the default is 8192 bytes.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>createOnDemand</td> |
| |
| <td>boolean</td> |
| |
| <td>The appender creates the file on-demand. The appender only creates the file when a log event |
| passes all filters and is routed to this appender. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the file to write to. If the file, or any of its parent directories, do not exist, |
| they will be created.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filePattern</td> |
| |
| <td>String</td> |
| |
| <td>The pattern of the file name of the archived log file. The format of the pattern is |
| dependent on the RolloverPolicy that is used. The DefaultRolloverPolicy will accept both |
| a date/time pattern compatible with |
| <a class="externalLink" href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a> |
| and/or a %i which represents an integer counter. The pattern also supports interpolation at |
| runtime so any of the Lookups (such as the <a href="./lookups.html#DateLookup">DateLookup</a>) can |
| be included in the pattern.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| <p>When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance.</p> |
| |
| <p>Flushing after every write is only useful when using this |
| appender with synchronous loggers. Asynchronous loggers and |
| appenders will automatically flush at the end of a batch of events, |
| even if immediateFlush is set to false. This also guarantees |
| the data is written to disk but is more efficient.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>policy</td> |
| |
| <td>TriggeringPolicy</td> |
| |
| <td>The policy to use to determine if a rollover should occur.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>strategy</td> |
| |
| <td>RolloverStrategy</td> |
| |
| <td>The strategy to use to determine the name and location of the archive file.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filePermissions</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File attribute permissions in POSIX format to apply whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| |
| <p>Examples: rw------- or rw-rw-rw- etc...</p></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileOwner</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File owner to define whenever the file is created.</p> |
| |
| <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. |
| Only processes with an effective user ID equal to the user ID |
| of the file or with appropriate privileges may change the ownership of a file |
| if <a class="externalLink" href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html">_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> |
| |
| <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html">owner</a> attribute view.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileGroup</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File group to define whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| </td> |
| </tr> |
| </table> |
| <a name="TriggeringPolicies"></a> |
| <section> |
| <h4><a name="Triggering_Policies"></a>Triggering Policies</h4> |
| <section> |
| <h5><a name="Composite_Triggering_Policy"></a>Composite Triggering Policy</h5> |
| |
| <p> |
| The CompositeTriggeringPolicy combines multiple triggering policies and returns true if |
| any of the configured policies return true. The CompositeTriggeringPolicy is configured |
| simply by wrapping other policies in a Policies element. |
| </p> |
| |
| <p> |
| For example, the following XML fragment defines policies that rollover the log when the JVM starts, |
| when the log size reaches twenty megabytes, and when the current date no longer matches the log’s |
| start date. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><Policies> |
| <OnStartupTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="20 MB" /> |
| <TimeBasedTriggeringPolicy /> |
| </Policies></pre></div> |
| </section><section> |
| <h5><a name="Cron_Triggering_Policy"></a>Cron Triggering Policy</h5> |
| |
| <p>The CronTriggeringPolicy triggers rollover based on a cron expression. This policy |
| is controlled by a timer and is asynchronous to processing log events, so it is possible that log events |
| from the previous or next time period may appear at the beginning or end of the log file. The |
| filePattern attribute of the Appender should contain a timestamp otherwise the target file will be |
| overwritten on each rollover. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">CronTriggeringPolicy Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>schedule</td> |
| |
| <td>String</td> |
| |
| <td>The cron expression. The expression is the same as what is allowed in the Quartz scheduler. See |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/CronExpression.html">CronExpression</a> |
| for a full description of the expression. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>evaluateOnStartup</td> |
| |
| <td>boolean</td> |
| |
| <td>On startup the cron expression will be evaluated against the file's last modification timestamp. |
| If the cron expression indicates a rollover should have occurred between that time and the current |
| time the file will be immediately rolled over.</td> |
| </tr> |
| </table> |
| </section><section> |
| <h5><a name="OnStartup_Triggering_Policy"></a>OnStartup Triggering Policy</h5> |
| |
| <p> |
| The OnStartupTriggeringPolicy policy causes a rollover if the log file is older than the |
| current JVM's start time and the minimum file size is met or exceeded. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">OnStartupTriggeringPolicy Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>minSize</td> |
| |
| <td>long</td> |
| |
| <td> |
| The minimum size the file must have to roll over. A size of zero will cause a roll over no matter |
| what the file size is. The default value is 1, which will prevent rolling over an empty file. |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| <i>Google App Engine note:</i><br /> |
| When running in Google App Engine, the OnStartup policy causes a rollover if the log file is older |
| than <i>the time when Log4J initialized</i>. |
| (Google App Engine restricts access to certain classes so Log4J cannot determine JVM start time with |
| java.lang.management.ManagementFactory.getRuntimeMXBean().getStartTime() |
| and falls back to Log4J initialization time instead.) |
| </p> |
| </section><section> |
| <h5><a name="SizeBased_Triggering_Policy"></a>SizeBased Triggering Policy</h5> |
| |
| <p> |
| The SizeBasedTriggeringPolicy causes a rollover once the file has reached the specified |
| size. The size can be specified in bytes, with the suffix KB, MB or GB, for example 20MB. |
| When combined with a time based triggering policy the file pattern must contain a %i |
| otherwise the target file will be overwritten on every rollover as the SizeBased Triggering Policy |
| will not cause the timestamp value in the file name to change. When used without a time based |
| triggering policy the SizeBased Triggering Policy will cause the timestamp value to change. |
| </p> |
| </section><section> |
| <h5><a name="TimeBased_Triggering_Policy"></a>TimeBased Triggering Policy</h5> |
| |
| <p> |
| The TimeBasedTriggeringPolicy causes a rollover once the date/time pattern no longer |
| applies to the active file. This policy accepts an interval attribute which indicates how |
| frequently the rollover should occur based on the time pattern and a modulate boolean |
| attribute. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">TimeBasedTriggeringPolicy Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>interval</td> |
| |
| <td>integer</td> |
| |
| <td>How often a rollover should occur based on the most specific time unit in the date pattern. |
| For example, with a date pattern with hours as the most specific item and and increment of 4 rollovers |
| would occur every 4 hours. |
| The default value is 1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>modulate</td> |
| |
| <td>boolean</td> |
| |
| <td>Indicates whether the interval should be adjusted to cause the next rollover to occur on |
| the interval boundary. For example, if the item is hours, the current hour is 3 am and the |
| interval is 4 then the first rollover will occur at 4 am and then next ones will occur at |
| 8 am, noon, 4pm, etc.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>maxRandomDelay</td> |
| |
| <td>integer</td> |
| |
| <td>Indicates the maximum number of seconds to randomly delay a rollover. By default, |
| this is 0 which indicates no delay. This setting is useful on servers where multiple |
| applications are configured to rollover log files at the same time and can spread |
| the load of doing so across time.</td> |
| </tr> |
| </table> |
| <a name="RolloverStrategies"></a> |
| </section></section><section> |
| <h4><a name="Rollover_Strategies"></a>Rollover Strategies</h4> |
| <a name="DefaultRolloverStrategy"></a> |
| <section> |
| <h5><a name="Default_Rollover_Strategy"></a>Default Rollover Strategy</h5> |
| |
| <p> |
| The default rollover strategy accepts both a date/time pattern and an integer from the filePattern |
| attribute specified on the RollingFileAppender itself. If the date/time pattern |
| is present it will be replaced with the current date and time values. If the pattern contains an integer |
| it will be incremented on each rollover. If the pattern contains both a date/time and integer |
| in the pattern the integer will be incremented until the result of the date/time pattern changes. If |
| the file pattern ends with ".gz", ".zip", ".bz2", ".deflate", ".pack200", or ".xz" the resulting archive |
| will be compressed using the compression scheme that matches the suffix. The formats bzip2, Deflate, |
| Pack200 and XZ require <a class="externalLink" href="http://commons.apache.org/proper/commons-compress/">Apache Commons Compress</a>. |
| In addition, XZ requires <a class="externalLink" href="http://tukaani.org/xz/java.html">XZ for Java</a>. |
| The pattern may also contain lookup references that can be resolved at runtime such as is shown in the example |
| below. |
| </p> |
| |
| <p>The default rollover strategy supports three variations for incrementing |
| the counter. To illustrate how it works, suppose that the min attribute |
| is set to 1, the max attribute is set to 3, the file name is "foo.log", |
| and the file name pattern is "foo-%i.log". |
| </p> |
| |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Number of rollovers</th> |
| |
| <th>Active output target</th> |
| |
| <th>Archived log files</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>0</td> |
| |
| <td>foo.log</td> |
| |
| <td>-</td> |
| |
| <td>All logging is going to the initial file.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>1</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-1.log</td> |
| |
| <td>During the first rollover foo.log is renamed to foo-1.log. A new foo.log file is created and |
| starts being written to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>2</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-2.log, foo-1.log</td> |
| |
| <td>During the second rollover foo.log is renamed to foo-2.log. A new foo.log file is created and |
| starts being written to.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>3</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-3.log, foo-2.log, foo-1.log</td> |
| |
| <td>During the third rollover foo.log is renamed to foo-3.log. A new foo.log file is created and |
| starts being written to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>4</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-3.log, foo-2.log, foo-1.log</td> |
| |
| <td>In the fourth and subsequent rollovers, foo-1.log is deleted, foo-2.log is renamed to |
| foo-1.log, foo-3.log is renamed to foo-2.log and foo.log is renamed to |
| foo-3.log. A new foo.log file is created and starts being written to.</td> |
| </tr> |
| </table> |
| |
| <p>By way of contrast, when the fileIndex attribute is set to "min" but all the other settings are the |
| same the "fixed window" strategy will be performed. |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Number of rollovers</th> |
| |
| <th>Active output target</th> |
| |
| <th>Archived log files</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>0</td> |
| |
| <td>foo.log</td> |
| |
| <td>-</td> |
| |
| <td>All logging is going to the initial file.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>1</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-1.log</td> |
| |
| <td>During the first rollover foo.log is renamed to foo-1.log. A new foo.log file is created and |
| starts being written to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>2</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-1.log, foo-2.log</td> |
| |
| <td>During the second rollover foo-1.log is renamed to foo-2.log and foo.log is renamed to |
| foo-1.log. A new foo.log file is created and starts being written to.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>3</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-1.log, foo-2.log, foo-3.log</td> |
| |
| <td>During the third rollover foo-2.log is renamed to foo-3.log, foo-1.log is renamed to foo-2.log and |
| foo.log is renamed to foo-1.log. A new foo.log file is created and starts being written to.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>4</td> |
| |
| <td>foo.log</td> |
| |
| <td>foo-1.log, foo-2.log, foo-3.log</td> |
| |
| <td>In the fourth and subsequent rollovers, foo-3.log is deleted, foo-2.log is renamed to |
| foo-3.log, foo-1.log is renamed to foo-2.log and foo.log is renamed to |
| foo-1.log. A new foo.log file is created and starts being written to.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Finally, as of release 2.8, if the fileIndex attribute is set to "nomax" then the min and max values |
| will be ignored and file numbering will increment by 1 and each rollover will have an incrementally |
| higher value with no maximum number of files. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">DefaultRolloverStrategy Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileIndex</td> |
| |
| <td>String</td> |
| |
| <td>If set to "max" (the default), files with a higher index will be newer than files with a |
| smaller index. If set to "min", file renaming and the counter will follow the Fixed Window strategy |
| described above.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>min</td> |
| |
| <td>integer</td> |
| |
| <td>The minimum value of the counter. The default value is 1.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>max</td> |
| |
| <td>integer</td> |
| |
| <td>The maximum value of the counter. Once this values is reached older archives will be |
| deleted on subsequent rollovers. The default value is 7.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>compressionLevel</td> |
| |
| <td>integer</td> |
| |
| <td> |
| Sets the compression level, 0-9, where 0 = none, 1 = best speed, through 9 = best compression. |
| Only implemented for ZIP files. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>tempCompressedFilePattern</td> |
| |
| <td>String</td> |
| |
| <td>The pattern of the file name of the archived log file during compression.</td> |
| </tr> |
| </table> |
| <a name="DirectWriteRolloverStrategy"></a> |
| </section><section> |
| <h5><a name="DirectWrite_Rollover_Strategy"></a>DirectWrite Rollover Strategy</h5> |
| |
| <p> |
| The DirectWriteRolloverStrategy causes log events to be written directly to files represented by the |
| file pattern. With this strategy file renames are not performed. If the size-based triggering policy |
| causes multiple files to be written during the specified time period they will be numbered starting |
| at one and continually incremented until a time-based rollover occurs. |
| </p> |
| |
| <p> |
| Warning: If the file pattern has a |
| suffix indicating compression should take place the current file will not be compressed when the |
| application is shut down. Furthermore, if the time changes such that the file pattern no longer |
| matches the current file it will not be compressed at startup either. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">DirectWriteRolloverStrategy Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>maxFiles</td> |
| |
| <td>String</td> |
| |
| <td>The maximum number of files to allow in the time period matching the file pattern. If the |
| number of files is exceeded the oldest file will be deleted. If specified, the value must |
| be greater than 1. If the value is less than zero or omitted then the number of files will |
| not be limited.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>compressionLevel</td> |
| |
| <td>integer</td> |
| |
| <td> |
| Sets the compression level, 0-9, where 0 = none, 1 = best speed, through 9 = best compression. |
| Only implemented for ZIP files. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>tempCompressedFilePattern</td> |
| |
| <td>String</td> |
| |
| <td>The pattern of the file name of the archived log file during compression.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with both the time and size based |
| triggering policies, will create up to 7 archives on the same day (1-7) that are stored in a directory |
| based on the current year and month, and will compress each |
| archive using gzip: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| This second example shows a rollover strategy that will keep up to 20 files before removing them. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| <DefaultRolloverStrategy max="20"/> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with both the time and size based |
| triggering policies, will create up to 7 archives on the same day (1-7) that are stored in a directory |
| based on the current year and month, and will compress each |
| archive using gzip and will roll every 6 hours when the hour is divisible by 6: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy interval="6" modulate="true"/> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| This sample configuration uses a RollingFileAppender with both the cron and size based |
| triggering policies, and writes directly to an unlimited number of archive files. The cron |
| trigger causes a rollover every hour while the file size is limited to 250MB: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" filePattern="logs/app-%d{yyyy-MM-dd-HH}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <CronTriggeringPolicy schedule="0 0 * * * ?"/> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| This sample configuration is the same as the previous but limits the number of files saved each hour to 10: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingFile name="RollingFile" filePattern="logs/app-%d{yyyy-MM-dd-HH}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <CronTriggeringPolicy schedule="0 0 * * * ?"/> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| <DirectWriteRolloverStrategy maxFiles="10"/> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| <a name="CustomDeleteOnRollover"></a> |
| </section><section> |
| <h5><a name="Log_Archive_Retention_Policy:_Delete_on_Rollover"></a>Log Archive Retention Policy: Delete on Rollover</h5> |
| |
| <p> |
| Log4j-2.5 introduces a Delete action that gives users more control |
| over what files are deleted at rollover time than what was possible with the DefaultRolloverStrategy |
| max attribute. |
| The Delete action lets users configure one or more conditions that select the files to delete |
| relative to a base directory. |
| </p> |
| |
| <p> |
| Note that it is possible to delete any file, not just rolled over log files, so use this action with care! |
| With the testMode parameter you can test your configuration without accidentally deleting the wrong files. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">Delete Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>basePath</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> Base path from where to start scanning for files to delete.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>maxDepth</td> |
| |
| <td>int</td> |
| |
| <td>The maximum number of levels of directories to visit. A value of 0 |
| means that only the starting file (the base path itself) is visited, |
| unless denied by the security manager. A value of |
| Integer.MAX_VALUE indicates that all levels should be visited. The default is 1, |
| meaning only the files in the specified base directory.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>followLinks</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to follow symbolic links. Default is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>testMode</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, files are not deleted but instead a message is printed to the <a href="configuration.html#StatusMessages">status logger</a> at INFO level. |
| Use this to do a dry run to test if the configuration works as expected. Default is false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>pathSorter</td> |
| |
| <td>PathSorter</td> |
| |
| <td>A plugin implementing the |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/PathSorter.html">PathSorter</a> |
| interface to sort the files before selecting the files to delete. The default is to sort most recently |
| modified files first.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>pathConditions <a name="DeletePathCondition"></a></td> |
| |
| <td>PathCondition[]</td> |
| |
| <td> |
| <p><i>Required if no ScriptCondition is specified.</i> One or more PathCondition elements.</p> |
| |
| <p> |
| If more than one condition is specified, |
| they all need to accept a path before it is deleted. Conditions can be nested, in which case the |
| inner condition(s) are evaluated only if the outer condition accepts the path. |
| If conditions are not nested they may be evaluated in any order. |
| </p> |
| |
| <p> |
| Conditions can also be combined with the logical operators AND, OR and NOT by using the |
| IfAll, IfAny and IfNot composite conditions. |
| </p> |
| |
| <p>Users can create custom conditions or use the built-in conditions:</p> |
| |
| <ul> |
| |
| <li><a href="#DeleteIfFileName">IfFileName</a> - accepts files whose path (relative to the base path) matches a |
| <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular expression</a> or a |
| <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)">glob</a>.</li> |
| |
| <li><a href="#DeleteIfLastModified">IfLastModified</a> - accepts files that are as old as or older than the specified |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/Duration.html#parseCharSequence">duration</a>. |
| </li> |
| |
| <li><a href="#DeleteIfAccumulatedFileCount">IfAccumulatedFileCount</a> - accepts paths after some count threshold is exceeded during the file tree walk.</li> |
| |
| <li><a href="#DeleteIfAccumulatedFileSize">IfAccumulatedFileSize</a> - accepts paths after the accumulated file size threshold is exceeded during the file tree walk.</li> |
| |
| <li>IfAll - accepts a path if all nested conditions accept it (logical AND). |
| Nested conditions may be evaluated in any order.</li> |
| |
| <li>IfAny - accepts a path if one of the nested conditions accept it (logical OR). |
| Nested conditions may be evaluated in any order.</li> |
| |
| <li>IfNot - accepts a path if the nested condition does not accept it (logical NOT).</li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>scriptCondition <a name="DeleteScriptCondition"></a></td> |
| |
| <td>ScriptCondition</td> |
| |
| <td> |
| <p><i>Required if no PathConditions are specified.</i> A ScriptCondition element specifying a script.</p> |
| |
| <p> |
| The ScriptCondition should contain a <a href="#ScriptCondition">Script, |
| ScriptRef or ScriptFile</a> element that specifies the logic to be executed. |
| (See also the <a href="filters.html#Script">ScriptFilter</a> documentation for more examples of |
| configuring ScriptFiles and ScriptRefs.) |
| </p> |
| |
| <p>The script is passed a number of <a href="#ScriptParameters">parameters</a>, |
| including a list of paths found under the base path (up to maxDepth) |
| and must return a list with the paths to delete.</p> |
| </td> |
| </tr> |
| </table> |
| <a name="DeleteIfFileName"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">IfFileName Condition Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>glob</td> |
| |
| <td>String</td> |
| |
| <td><i>Required if regex not specified.</i> |
| Matches the relative path (relative to the base path) using a limited pattern language that resembles regular expressions but with a |
| <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)">simpler syntax</a>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>regex</td> |
| |
| <td>String</td> |
| |
| <td><i>Required if glob not specified.</i> |
| Matches the relative path (relative to the base path) using a regular expression as defined by the |
| <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a> class. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>nestedConditions</td> |
| |
| <td>PathCondition[]</td> |
| |
| <td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions |
| exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the |
| outer condition accepts a file (if the path name matches). |
| </td> |
| </tr> |
| </table> |
| <a name="DeleteIfLastModified"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">IfLastModified Condition Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>age</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> |
| Specifies a <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/Duration.html#parseCharSequence">duration</a>. |
| The condition accepts files that are as old or older than the specified duration. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>nestedConditions</td> |
| |
| <td>PathCondition[]</td> |
| |
| <td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions |
| exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the |
| outer condition accepts a file (if the file is old enough). |
| </td> |
| </tr> |
| </table> |
| <a name="DeleteIfAccumulatedFileCount"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">IfAccumulatedFileCount Condition Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>exceeds</td> |
| |
| <td>int</td> |
| |
| <td><i>Required.</i> |
| The threshold count from which files will be deleted. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>nestedConditions</td> |
| |
| <td>PathCondition[]</td> |
| |
| <td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions |
| exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the |
| outer condition accepts a file (if the threshold count has been exceeded). |
| </td> |
| </tr> |
| </table> |
| <a name="DeleteIfAccumulatedFileSize"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">IfAccumulatedFileSize Condition Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>exceeds</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> |
| The threshold accumulated file size from which files will be deleted. |
| The size can be specified in bytes, with the suffix KB, MB or GB, for example 20MB. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>nestedConditions</td> |
| |
| <td>PathCondition[]</td> |
| |
| <td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions |
| exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the |
| outer condition accepts a file (if the threshold accumulated file size has been exceeded). |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with the cron |
| triggering policy configured to trigger every day at midnight. |
| Archives are stored in a directory based on the current year and month. |
| All files under the base directory that match the "*/app-*.log.gz" glob and are 60 days old |
| or older are deleted at rollover time. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Properties> |
| <Property name="baseDir">logs</Property> |
| </Properties> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="${baseDir}/app.log" |
| filePattern="${baseDir}/$${date:yyyy-MM}/app-%d{yyyy-MM-dd}.log.gz"> |
| <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" /> |
| <CronTriggeringPolicy schedule="0 0 0 * * ?"/> |
| <DefaultRolloverStrategy> |
| <Delete basePath="${baseDir}" maxDepth="2"> |
| <IfFileName glob="*/app-*.log.gz" /> |
| <IfLastModified age="60d" /> |
| </Delete> |
| </DefaultRolloverStrategy> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with both the time and size based |
| triggering policies, will create up to 100 archives on the same day (1-100) that are stored in a directory |
| based on the current year and month, and will compress each |
| archive using gzip and will roll every hour. |
| |
| During every rollover, this configuration will delete files that match "*/app-*.log.gz" |
| and are 30 days old or older, |
| but keep the most recent 100 GB or the most recent 10 files, whichever comes first. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Properties> |
| <Property name="baseDir">logs</Property> |
| </Properties> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="${baseDir}/app.log" |
| filePattern="${baseDir}/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz"> |
| <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" /> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| <DefaultRolloverStrategy max="100"> |
| <!-- |
| Nested conditions: the inner condition is only evaluated on files |
| for which the outer conditions are true. |
| --> |
| <Delete basePath="${baseDir}" maxDepth="2"> |
| <IfFileName glob="*/app-*.log.gz"> |
| <IfLastModified age="30d"> |
| <IfAny> |
| <IfAccumulatedFileSize exceeds="100 GB" /> |
| <IfAccumulatedFileCount exceeds="10" /> |
| </IfAny> |
| </IfLastModified> |
| </IfFileName> |
| </Delete> |
| </DefaultRolloverStrategy> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| <a name="ScriptCondition"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">ScriptCondition Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>script</td> |
| |
| <td>Script, ScriptFile or ScriptRef</td> |
| |
| <td>The Script element that specifies the logic to be executed. The script is passed |
| a list of paths found under the base path and must return the paths to delete as a |
| java.util.List<<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/PathWithAttributes.html">PathWithAttributes</a>>. |
| See also the <a href="filters.html#Script">ScriptFilter</a> documentation for an example of |
| how ScriptFiles and ScriptRefs can be configured. |
| </td> |
| </tr> |
| </table> |
| <a name="ScriptParameters"></a> |
| |
| <table border="0" class="table table-striped"><caption align="top">Script Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>basePath</td> |
| |
| <td>java.nio.file.Path</td> |
| |
| <td>The directory from where the Delete action started scanning for |
| files to delete. Can be used to relativize the paths in the pathList.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>pathList</td> |
| |
| <td>java.util.List<<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/PathWithAttributes.html">PathWithAttributes</a>></td> |
| |
| <td>The list of paths found under the base path up to the specified max depth, |
| sorted most recently modified files first. |
| The script is free to modify and return this list.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>statusLogger</td> |
| |
| <td>StatusLogger</td> |
| |
| <td>The StatusLogger that can be used to log internal events during script execution.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>configuration</td> |
| |
| <td>Configuration</td> |
| |
| <td>The Configuration that owns this ScriptCondition.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>substitutor</td> |
| |
| <td>StrSubstitutor</td> |
| |
| <td>The StrSubstitutor used to replace lookup variables.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>?</td> |
| |
| <td>String</td> |
| |
| <td>Any properties declared in the configuration.</td> |
| </tr> |
| </table> |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender with the cron |
| triggering policy configured to trigger every day at midnight. |
| Archives are stored in a directory based on the current year and month. |
| The script returns a list of rolled over files under the base directory dated Friday the 13th. |
| The Delete action will delete all files returned by the script. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="trace" name="MyApp" packages=""> |
| <Properties> |
| <Property name="baseDir">logs</Property> |
| </Properties> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="${baseDir}/app.log" |
| filePattern="${baseDir}/$${date:yyyy-MM}/app-%d{yyyyMMdd}.log.gz"> |
| <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" /> |
| <CronTriggeringPolicy schedule="0 0 0 * * ?"/> |
| <DefaultRolloverStrategy> |
| <Delete basePath="${baseDir}" maxDepth="2"> |
| <ScriptCondition> |
| <Script name="superstitious" language="groovy"><![CDATA[ |
| import java.nio.file.*; |
| |
| def result = []; |
| def pattern = ~/\d*\/app-(\d*)\.log\.gz/; |
| |
| pathList.each { pathWithAttributes -> |
| def relative = basePath.relativize pathWithAttributes.path |
| statusLogger.trace 'SCRIPT: relative path=' + relative + " (base=$basePath)"; |
| |
| // remove files dated Friday the 13th |
| |
| def matcher = pattern.matcher(relative.toString()); |
| if (matcher.find()) { |
| def dateString = matcher.group(1); |
| def calendar = Date.parse("yyyyMMdd", dateString).toCalendar(); |
| def friday13th = calendar.get(Calendar.DAY_OF_MONTH) == 13 \ |
| && calendar.get(Calendar.DAY_OF_WEEK) == Calendar.FRIDAY; |
| if (friday13th) { |
| result.add pathWithAttributes; |
| statusLogger.trace 'SCRIPT: deleting path ' + pathWithAttributes; |
| } |
| } |
| } |
| statusLogger.trace 'SCRIPT: returning ' + result; |
| result; |
| ]] > |
| </Script> |
| </ScriptCondition> |
| </Delete> |
| </DefaultRolloverStrategy> |
| </RollingFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <a name="CustomPosixViewAttributeOnRollover"></a> |
| </section><section> |
| <h5><a name="Log_Archive_File_Attribute_View_Policy:_Custom_file_attribute_on_Rollover"></a>Log Archive File Attribute View Policy: Custom file attribute on Rollover</h5> |
| |
| <p> |
| Log4j-2.9 introduces a PosixViewAttribute action that gives users more control |
| over which file attribute permissions, owner and group should be applied. |
| The PosixViewAttribute action lets users configure one or more conditions that select the eligible files |
| relative to a base directory. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">PosixViewAttribute Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>basePath</td> |
| |
| <td>String</td> |
| |
| <td><i>Required.</i> Base path from where to start scanning for files to apply attributes.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>maxDepth</td> |
| |
| <td>int</td> |
| |
| <td>The maximum number of levels of directories to visit. A value of 0 |
| means that only the starting file (the base path itself) is visited, |
| unless denied by the security manager. A value of |
| Integer.MAX_VALUE indicates that all levels should be visited. The default is 1, |
| meaning only the files in the specified base directory.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>followLinks</td> |
| |
| <td>boolean</td> |
| |
| <td>Whether to follow symbolic links. Default is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>pathConditions</td> |
| |
| <td>PathCondition[]</td> |
| |
| <td>see <a href="#DeletePathCondition">DeletePathCondition</a></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>filePermissions</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File attribute permissions in POSIX format to apply when action is executed.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| |
| <p>Examples: rw------- or rw-rw-rw- etc...</p></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileOwner</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File owner to define when action is executed.</p> |
| |
| <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. |
| Only processes with an effective user ID equal to the user ID |
| of the file or with appropriate privileges may change the ownership of a file |
| if <a class="externalLink" href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html">_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> |
| |
| <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html">owner</a> attribute view.</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileGroup</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File group to define when action is executed.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| </td> |
| </tr> |
| </table> |
| |
| |
| <p> |
| Below is a sample configuration that uses a RollingFileAppender and defines different POSIX file attribute view for current and rolled log files. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="trace" name="MyApp" packages=""> |
| <Properties> |
| <Property name="baseDir">logs</Property> |
| </Properties> |
| <Appenders> |
| <RollingFile name="RollingFile" fileName="${baseDir}/app.log" |
| filePattern="${baseDir}/$${date:yyyy-MM}/app-%d{yyyyMMdd}.log.gz" |
| filePermissions="rw-------"> |
| <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" /> |
| <CronTriggeringPolicy schedule="0 0 0 * * ?"/> |
| <DefaultRolloverStrategy stopCustomActionsOnError="true"> |
| <PosixViewAttribute basePath="${baseDir}/$${date:yyyy-MM}" filePermissions="r--r--r--"> |
| <IfFileName glob="*.gz" /> |
| </PosixViewAttribute> |
| </DefaultRolloverStrategy> |
| </RollingFile> |
| </Appenders> |
| |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingFile"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration></pre></div> |
| </section></section></section> |
| |
| <a name="RollingRandomAccessFileAppender"></a> |
| <section> |
| <h3><a name="RollingRandomAccessFileAppender"></a>RollingRandomAccessFileAppender</h3> |
| |
| <p> |
| The RollingRandomAccessFileAppender is similar to the standard |
| <a href="#RollingFileAppender">RollingFileAppender</a> |
| except it is always buffered (this cannot be switched off) and |
| internally it uses a ByteBuffer + RandomAccessFile |
| instead of a BufferedOutputStream. |
| We saw a 20-200% performance improvement compared to |
| RollingFileAppender with "bufferedIO=true" |
| in our <a href="../performance.html#whichAppender">measurements</a>. |
| |
| The RollingRandomAccessFileAppender writes to the File named in the |
| fileName parameter and rolls the file over according the |
| TriggeringPolicy and the RolloverPolicy. |
| |
| Similar to the RollingFileAppender, RollingRandomAccessFileAppender uses a RollingRandomAccessFileManager |
| to actually perform the file I/O and perform the rollover. While RollingRandomAccessFileAppender |
| from different Configurations cannot be shared, the RollingRandomAccessFileManagers can be |
| if the Manager is accessible. For example, two web applications in a servlet |
| container can have their own configuration and safely write to the |
| same file if Log4j is in a ClassLoader that is common to both of them. |
| </p> |
| |
| <p> |
| A RollingRandomAccessFileAppender requires a |
| <a href="#TriggeringPolicies">TriggeringPolicy</a> and a |
| <a href="#RolloverStrategies">RolloverStrategy</a>. |
| The triggering policy determines if a rollover should be performed |
| while the RolloverStrategy defines how the rollover should be done. |
| If no RolloverStrategy is configured, RollingRandomAccessFileAppender will use the |
| <a href="#DefaultRolloverStrategy">DefaultRolloverStrategy</a>. |
| Since log4j-2.5, a <a href="#CustomDeleteOnRollover">custom delete action</a> can be configured in the |
| DefaultRolloverStrategy to run at rollover. |
| </p> |
| |
| <p> |
| File locking is not supported by the RollingRandomAccessFileAppender. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RollingRandomAccessFileAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>append</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, records will be appended to the end |
| of the file. When set to false, |
| the file will be cleared before |
| new records are written. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this |
| Appender. More than one Filter |
| may be used by using a |
| CompositeFilter. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileName</td> |
| |
| <td>String</td> |
| |
| <td>The name of the file to write to. If the file, or any of its |
| parent directories, do not exist, |
| they will be created. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filePattern</td> |
| |
| <td>String</td> |
| |
| <td> |
| The pattern of the file name of the archived log file. The format |
| of the pattern should is dependent on the RolloverStrategu that is used. The DefaultRolloverStrategy |
| will accept both a date/time pattern compatible with |
| <a class="externalLink" href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html"> |
| SimpleDateFormat</a> |
| and/or a %i which represents an integer counter. The integer counter |
| allows specifying a padding, like %3i for space-padding the counter to |
| 3 digits or (usually more useful) %03i for zero-padding the counter to |
| 3 digits. The pattern also supports interpolation at runtime so any of the Lookups (such as the |
| <a href="./lookups.html#DateLookup">DateLookup</a> |
| can be included in the pattern. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td> |
| <p>When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance.</p> |
| |
| <p>Flushing after every write is only useful when using this |
| appender with synchronous loggers. Asynchronous loggers and |
| appenders will automatically flush at the end of a batch of events, |
| even if immediateFlush is set to false. This also guarantees |
| the data is written to disk but is more efficient.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>The buffer size, defaults to 262,144 bytes (256 * 1024).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>policy</td> |
| |
| <td>TriggeringPolicy</td> |
| |
| <td>The policy to use to determine if a rollover should occur. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>strategy</td> |
| |
| <td>RolloverStrategy</td> |
| |
| <td>The strategy to use to determine the name and location of the |
| archive file. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filePermissions</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File attribute permissions in POSIX format to apply whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| |
| <p>Examples: rw------- or rw-rw-rw- etc...</p></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>fileOwner</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File owner to define whenever the file is created.</p> |
| |
| <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. |
| Only processes with an effective user ID equal to the user ID |
| of the file or with appropriate privileges may change the ownership of a file |
| if <a class="externalLink" href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html">_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> |
| |
| <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html">owner</a> attribute view.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>fileGroup</td> |
| |
| <td>String</td> |
| |
| <td> |
| <p>File group to define whenever the file is created.</p> |
| |
| <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html">POSIX</a> file attribute view.</p> |
| </td> |
| </tr> |
| </table> |
| <a name="FRFA_TriggeringPolicies"></a> |
| <section> |
| <h4><a name="Triggering_Policies"></a>Triggering Policies</h4> |
| |
| <p> |
| See |
| <a href="#TriggeringPolicies">RollingFileAppender Triggering Policies</a>. |
| </p> |
| <a name="FRFA_RolloverStrategies"></a> |
| </section><section> |
| <h4><a name="Rollover_Strategies"></a>Rollover Strategies</h4> |
| |
| <p> |
| See |
| <a href="#RolloverStrategies">RollingFileAppender Rollover Strategies</a>. |
| </p> |
| |
| |
| <p> |
| Below is a sample configuration that uses a RollingRandomAccessFileAppender |
| with both the time and size based |
| triggering policies, will create |
| up to 7 archives on the same day (1-7) that |
| are stored in a |
| directory |
| based on the current year and month, and will compress |
| each |
| archive using gzip: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingRandomAccessFile name="RollingRandomAccessFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingRandomAccessFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingRandomAccessFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| This second example shows a rollover strategy that will keep up to |
| 20 files before removing them. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingRandomAccessFile name="RollingRandomAccessFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy /> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| <DefaultRolloverStrategy max="20"/> |
| </RollingRandomAccessFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingRandomAccessFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| Below is a sample configuration that uses a RollingRandomAccessFileAppender |
| with both the time and size based |
| triggering policies, will create |
| up to 7 archives on the same day (1-7) that |
| are stored in a |
| directory |
| based on the current year and month, and will compress |
| each |
| archive using gzip and will roll every 6 hours when the hour is |
| divisible |
| by 6: |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <RollingRandomAccessFile name="RollingRandomAccessFile" fileName="logs/app.log" |
| filePattern="logs/$${date:yyyy-MM}/app-%d{yyyy-MM-dd-HH}-%i.log.gz"> |
| <PatternLayout> |
| <Pattern>%d %p %c{1.} [%t] %m%n</Pattern> |
| </PatternLayout> |
| <Policies> |
| <TimeBasedTriggeringPolicy interval="6" modulate="true"/> |
| <SizeBasedTriggeringPolicy size="250 MB"/> |
| </Policies> |
| </RollingRandomAccessFile> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="RollingRandomAccessFile"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section></section> |
| <a name="RoutingAppender"></a> |
| <section> |
| <h3><a name="RoutingAppender"></a>RoutingAppender</h3> |
| |
| <p> |
| The RoutingAppender evaluates LogEvents and then routes them to a subordinate Appender. The target |
| Appender may be an appender previously configured and may be referenced by its name or the |
| Appender can be dynamically created as needed. The RoutingAppender should be configured after any |
| Appenders it references to allow it to shut down properly. |
| </p> |
| |
| <p> |
| You can also configure a RoutingAppender with scripts: you can run a script when the appender starts |
| and when a route is chosen for an log event. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RoutingAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>Filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>RewritePolicy</td> |
| |
| <td>RewritePolicy</td> |
| |
| <td>The RewritePolicy that will manipulate the LogEvent.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>Routes</td> |
| |
| <td>Routes</td> |
| |
| <td>Contains one or more Route declarations to identify the criteria for choosing Appenders.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>Script</td> |
| |
| <td>Script</td> |
| |
| <td> |
| |
| <p> |
| This Script runs when Log4j starts the RoutingAppender and returns a String Route key to |
| determine the default Route. |
| </p> |
| |
| <p> |
| This script is passed the following variables: |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RoutingAppender Script Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>configuration</td> |
| |
| <td>Configuration</td> |
| |
| <td>The active Configuration.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>staticVariables</td> |
| |
| <td>Map</td> |
| |
| <td> |
| A Map shared between all script invocations for this appender instance. This is |
| the same map passed to the Routes Script. |
| </td> |
| </tr> |
| </table> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| <p> |
| In this example, the script causes the "ServiceWindows" route to be the default route on Windows and |
| "ServiceOther" on all other operating systems. Note that the List Appender is one of our test appenders, |
| any appender can be used, it is only used as a shorthand. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="WARN" name="RoutingTest"> |
| <Appenders> |
| <Routing name="Routing"> |
| <Script name="RoutingInit" language="JavaScript"><![CDATA[ |
| importPackage(java.lang); |
| System.getProperty("os.name").search("Windows") > -1 ? "ServiceWindows" : "ServiceOther";]]> |
| </Script> |
| <Routes> |
| <Route key="ServiceOther"> |
| <List name="List1" /> |
| </Route> |
| <Route key="ServiceWindows"> |
| <List name="List2" /> |
| </Route> |
| </Routes> |
| </Routing> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Routing" /> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| <section> |
| <h4><a name="Routes"></a>Routes</h4> |
| |
| <p> |
| The Routes element accepts a single attribute named "pattern". The pattern is evaluated |
| against all the registered Lookups and the result is used to select a Route. Each Route may be |
| configured with a key. If the key matches the result of evaluating the pattern then that Route |
| will be selected. If no key is specified on a Route then that Route is the default. Only one Route |
| can be configured as the default. |
| </p> |
| |
| <p> |
| The Routes element may contain a Script child element. If specified, the Script is run for each |
| log event and returns the String Route key to use. |
| </p> |
| |
| <p> |
| You must specify either the pattern attribute or the Script element, but not both. |
| </p> |
| |
| <p> |
| Each Route must reference an Appender. If the Route contains a ref attribute then the |
| Route will reference an Appender that was defined in the configuration. If the Route contains an |
| Appender definition then an Appender will be created within the context of the RoutingAppender and |
| will be reused each time a matching Appender name is referenced through a Route. |
| </p> |
| |
| <p> |
| This script is passed the following variables: |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">RoutingAppender Routes Script Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>configuration</td> |
| |
| <td>Configuration</td> |
| |
| <td>The active Configuration.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>staticVariables</td> |
| |
| <td>Map</td> |
| |
| <td> |
| A Map shared between all script invocations for this appender instance. This is |
| the same map passed to the Routes Script. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>logEvent</td> |
| |
| <td>LogEvent</td> |
| |
| <td>The log event.</td> |
| </tr> |
| </table> |
| |
| <p> |
| In this example, the script runs for each log event and picks a route based on the presence of a |
| Marker named "AUDIT". |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="WARN" name="RoutingTest"> |
| <Appenders> |
| <Console name="STDOUT" target="SYSTEM_OUT" /> |
| <Flume name="AuditLogger" 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> |
| <Routing name="Routing"> |
| <Routes> |
| <Script name="RoutingInit" language="JavaScript"><![CDATA[ |
| if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("AUDIT")) { |
| return "AUDIT"; |
| } else if (logEvent.getContextMap().containsKey("UserId")) { |
| return logEvent.getContextMap().get("UserId"); |
| } |
| return "STDOUT";]]> |
| </Script> |
| <Route> |
| <RollingFile |
| name="Rolling-${mdc:UserId}" |
| fileName="${mdc:UserId}.log" |
| filePattern="${mdc:UserId}.%i.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <SizeBasedTriggeringPolicy size="500" /> |
| </RollingFile> |
| </Route> |
| <Route ref="AuditLogger" key="AUDIT"/> |
| <Route ref="STDOUT" key="STDOUT"/> |
| </Routes> |
| <IdlePurgePolicy timeToLive="15" timeUnit="minutes"/> |
| </Routing> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Routing" /> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| </section><section> |
| <h4><a name="Purge_Policy"></a>Purge Policy</h4> |
| |
| <p>The RoutingAppender can be configured with a PurgePolicy whose purpose is to stop and remove dormant |
| Appenders that have been dynamically created by the RoutingAppender. Log4j currently provides the |
| IdlePurgePolicy as the only PurgePolicy available for cleaning up the Appenders. The IdlePurgePolicy |
| accepts 2 attributes; timeToLive, which is the number of timeUnits the Appender should survive without |
| having any events sent to it, and timeUnit, the String representation of java.util.concurrent.TimeUnit |
| which is used with the timeToLive attribute.</p> |
| |
| <p> |
| Below is a sample configuration that uses a RoutingAppender to route all Audit events to |
| a FlumeAppender and all other events will be routed to a RollingFileAppender that captures only |
| the specific event type. Note that the AuditAppender was predefined while the RollingFileAppenders |
| are created as needed. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Flume name="AuditLogger" 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> |
| <Routing name="Routing"> |
| <Routes pattern="$${sd:type}"> |
| <Route> |
| <RollingFile name="Rolling-${sd:type}" fileName="${sd:type}.log" |
| filePattern="${sd:type}.%i.log.gz"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| <SizeBasedTriggeringPolicy size="500" /> |
| </RollingFile> |
| </Route> |
| <Route ref="AuditLogger" key="Audit"/> |
| </Routes> |
| <IdlePurgePolicy timeToLive="15" timeUnit="minutes"/> |
| </Routing> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Routing"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section></section> |
| <a name="SMTPAppender"></a> |
| <section> |
| <h3><a name="SMTPAppender"></a>SMTPAppender</h3> |
| |
| <p> |
| Sends an e-mail when a specific logging event occurs, typically on errors or fatal errors. |
| </p> |
| |
| <p> |
| The number of logging events delivered in this e-mail depend on the value of |
| <b>BufferSize</b> option. The SMTPAppender keeps only the last |
| BufferSize logging events in its cyclic buffer. This keeps |
| memory requirements at a reasonable level while still delivering useful |
| application context. All events in the buffer are included in the email. |
| The buffer will contain the most recent events of level TRACE to WARN |
| preceding the event that triggered the email. |
| </p> |
| |
| <p> |
| The default behavior is to trigger sending an email whenever an ERROR or higher |
| severity event is logged and to format it as HTML. The circumstances on when the |
| email is sent can be controlled by setting one or more filters on the Appender. |
| As with other Appenders, the formatting can be controlled by specifying a Layout |
| for the Appender. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">SMTPAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>from</td> |
| |
| <td>String</td> |
| |
| <td>The email address of the sender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>replyTo</td> |
| |
| <td>String</td> |
| |
| <td>The comma-separated list of reply-to email addresses.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>to</td> |
| |
| <td>String</td> |
| |
| <td>The comma-separated list of recipient email addresses.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>cc</td> |
| |
| <td>String</td> |
| |
| <td>The comma-separated list of CC email addresses.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bcc</td> |
| |
| <td>String</td> |
| |
| <td>The comma-separated list of BCC email addresses.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>subject</td> |
| |
| <td>String</td> |
| |
| <td>The subject of the email message.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>integer</td> |
| |
| <td>The maximum number of log events to be buffered for inclusion in the message. Defaults to 512.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied <a href="layouts.html#HTMLLayout">HTML layout</a> will be used.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>smtpDebug</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true enables session debugging on STDOUT. Defaults to false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>smtpHost</td> |
| |
| <td>String</td> |
| |
| <td>The SMTP hostname to send to. This parameter is required.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>smtpPassword</td> |
| |
| <td>String</td> |
| |
| <td>The password required to authenticate against the SMTP server.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>smtpPort</td> |
| |
| <td>integer</td> |
| |
| <td>The SMTP port to send to. </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>smtpProtocol</td> |
| |
| <td>String</td> |
| |
| <td>The SMTP transport protocol (such as "smtps", defaults to "smtp").</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>smtpUsername</td> |
| |
| <td>String</td> |
| |
| <td>The username required to authenticate against the SMTP server.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <SMTP name="Mail" subject="Error Log" to="errors@logging.apache.org" from="test@logging.apache.org" |
| smtpHost="localhost" smtpPort="25" bufferSize="50"> |
| </SMTP> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="Mail"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="ScriptAppenderSelector"></a> |
| <section> |
| <h3><a name="ScriptAppenderSelector"></a>ScriptAppenderSelector</h3> |
| |
| <p> |
| When the configuration is built, the ScriptAppenderSelector appender calls a Script |
| to compute an appender name. Log4j then creates one of the appender named listed under |
| AppenderSet using the name of the ScriptAppenderSelector. After configuration, Log4j |
| ignores the ScriptAppenderSelector. Log4j only builds the one selected appender from the |
| configuration tree, and ignores other AppenderSet child nodes. |
| </p> |
| |
| <p> |
| In the following example, the script returns the name "List2". The appender name is recorded under |
| the name of the ScriptAppenderSelector, not the name of the selected appender, in this example, |
| "SelectIt". |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><Configuration status="WARN" name="ScriptAppenderSelectorExample"> |
| <Appenders> |
| <ScriptAppenderSelector name="SelectIt"> |
| <Script language="JavaScript"><![CDATA[ |
| importPackage(java.lang); |
| System.getProperty("os.name").search("Windows") > -1 ? "MyCustomWindowsAppender" : "MySyslogAppender";]]> |
| </Script> |
| <AppenderSet> |
| <MyCustomWindowsAppender name="MyAppender" ... /> |
| <SyslogAppender name="MySyslog" ... /> |
| </AppenderSet> |
| </ScriptAppenderSelector> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="SelectIt" /> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| <a name="SocketAppender"></a> |
| <section> |
| <h3><a name="SocketAppender"></a>SocketAppender</h3> |
| |
| <p> |
| The SocketAppender is an OutputStreamAppender that writes its output to a remote destination |
| specified by a host and port. The data can be sent over either TCP or UDP and can be sent in any format. |
| You can optionally secure communication with <a href="#SSL">SSL</a>. Note that the TCP and SSL variants |
| write to the socket as a stream and do not expect response from the target destination. Due to limitations |
| in the TCP protocol that means that when the target server closes its connection some log events may |
| continue to appear to succeed until a closed connection exception is raised, causing those events to be |
| lost. If guaranteed delivery is required a protocol that requires acknowledgements must be used. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">SocketAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>host</td> |
| |
| <td>String</td> |
| |
| <td>The name or address of the system that is listening for log events. This parameter is required. If |
| the host name resolves to multiple IP addresses the TCP and SSL variations will fail over to |
| the next IP address when a connection is lost. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>port</td> |
| |
| <td>integer</td> |
| |
| <td>The port on the host that is listening for log events. This parameter must be specified.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>protocol</td> |
| |
| <td>String</td> |
| |
| <td>"TCP" (default), "SSL" or "UDP".</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>SSL</td> |
| |
| <td>SslConfiguration</td> |
| |
| <td>Contains the configuration for the KeyStore and TrustStore. See <a href="#SSL">SSL</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>immediateFail</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true, log events will not wait to try to reconnect and will fail immediately if the |
| socket is not available.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>bufferedIO</td> |
| |
| <td>boolean</td> |
| |
| <td>When true - the default, events are written to a buffer and the data will be written to |
| the socket when the buffer is full or, if immediateFlush is set, when the record is written.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bufferSize</td> |
| |
| <td>int</td> |
| |
| <td>When bufferedIO is true, this is the buffer size, the default is 8192 bytes.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>layout</td> |
| |
| <td>Layout</td> |
| |
| <td>The Layout to use to format the LogEvent. Required, there is no default. |
| <i>New since 2.9, in previous versions SerializedLayout was default.</i></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>reconnectionDelayMillis</td> |
| |
| <td>integer</td> |
| |
| <td>If set to a value greater than 0, after an error the SocketManager will attempt to reconnect to |
| the server 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).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>connectTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The connect timeout in milliseconds. The default is 0 (infinite timeout, like Socket.connect() |
| methods).</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| </table> |
| |
| |
| <p> |
| This is an unsecured TCP configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Socket name="socket" host="localhost" port="9500"> |
| <JsonLayout properties="true"/> |
| </Socket> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="socket"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <p> |
| This is a secured <a href="#SSL">SSL</a> configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Socket name="socket" host="localhost" port="9500"> |
| <JsonLayout properties="true"/> |
| <SSL> |
| <KeyStore location="log4j2-keystore.jks" passwordEnvironmentVariable="KEYSTORE_PASSWORD"/> |
| <TrustStore location="truststore.jks" passwordFile="${sys:user.home}/truststore.pwd"/> |
| </SSL> |
| </Socket> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="socket"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| </section> |
| <a name="SSL"></a> |
| <section> |
| <h3><a name="SSL_Configuration"></a>SSL Configuration</h3> |
| |
| <p> |
| Several appenders can be configured to use either a plain network connection or a Secure Socket Layer (SSL) |
| connection. This section documents the parameters available for SSL configuration. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">SSL Configuration Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>protocol</td> |
| |
| <td>String</td> |
| |
| <td>SSL if omitted. |
| See also <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#SSLContext">Standard names</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>KeyStore</td> |
| |
| <td>KeyStore</td> |
| |
| <td>Contains your private keys and certificates, |
| and determines which authentication credentials to send to the remote host.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>TrustStore</td> |
| |
| <td>TrustStore</td> |
| |
| <td>Contains the CA certificates of the remote counterparty. |
| Determines whether the remote authentication credentials |
| (and thus the connection) should be trusted.</td> |
| </tr> |
| </table> |
| |
| <section> |
| <h4><a name="KeyStore"></a>KeyStore</h4> |
| |
| <p> |
| The keystore is meant to contain your private keys and certificates, |
| and determines which authentication credentials to send to the remote host. |
| </p> |
| |
| |
| <table border="0" class="table table-striped"><caption align="top">KeyStore Configuration Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>location</td> |
| |
| <td>String</td> |
| |
| <td>Path to the keystore file.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>char[]</td> |
| |
| <td>Plain text password to access the keystore. Cannot be combined with either |
| passwordEnvironmentVariable or passwordFile.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>passwordEnvironmentVariable</td> |
| |
| <td>String</td> |
| |
| <td>Name of an environment variable that holds the password. Cannot be combined with either |
| password or passwordFile.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>passwordFile</td> |
| |
| <td>String</td> |
| |
| <td>Path to a file that holds the password. Cannot be combined with either |
| password or passwordEnvironmentVariable.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>type</td> |
| |
| <td>String</td> |
| |
| <td>Optional KeyStore type, e.g. JKS, PKCS12, PKCS11, |
| BKS, Windows-MY/Windows-ROOT, KeychainStore, etc. |
| The default is JKS. See also <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#KeyStore">Standard types</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>keyManagerFactoryAlgorithm</td> |
| |
| <td>String</td> |
| |
| <td>Optional KeyManagerFactory algorithm. The default is SunX509. |
| See also <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory">Standard algorithms</a>.</td> |
| </tr> |
| </table> |
| |
| </section><section> |
| <h4><a name="TrustStore"></a>TrustStore</h4> |
| |
| <p> |
| The trust store is meant to contain the CA certificates you are willing to trust |
| when a remote party presents its certificate. Determines whether the remote authentication credentials |
| (and thus the connection) should be trusted. |
| </p> |
| <p> |
| In some cases, they can be one and the same store, |
| although it is often better practice to use distinct stores (especially when they are file-based). |
| </p> |
| |
| |
| <table border="0" class="table table-striped"><caption align="top">TrustStore Configuration Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>location</td> |
| |
| <td>String</td> |
| |
| <td>Path to the keystore file.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>password</td> |
| |
| <td>char[]</td> |
| |
| <td>Plain text password to access the keystore. Cannot be combined with either |
| passwordEnvironmentVariable or passwordFile.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>passwordEnvironmentVariable</td> |
| |
| <td>String</td> |
| |
| <td>Name of an environment variable that holds the password. Cannot be combined with either |
| password or passwordFile.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>passwordFile</td> |
| |
| <td>String</td> |
| |
| <td>Path to a file that holds the password. Cannot be combined with either |
| password or passwordEnvironmentVariable.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>type</td> |
| |
| <td>String</td> |
| |
| <td>Optional KeyStore type, e.g. JKS, PKCS12, PKCS11, |
| BKS, Windows-MY/Windows-ROOT, KeychainStore, etc. |
| The default is JKS. See also <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#KeyStore">Standard types</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>trustManagerFactoryAlgorithm</td> |
| |
| <td>String</td> |
| |
| <td>Optional TrustManagerFactory algorithm. The default is SunX509. |
| See also <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#TrustManagerFactory">Standard algorithms</a>.</td> |
| </tr> |
| </table> |
| |
| </section><section> |
| <h4><a name="Example"></a>Example</h4> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| ... |
| <SSL> |
| <KeyStore location="log4j2-keystore.jks" passwordEnvironmentVariable="KEYSTORE_PASSWORD"/> |
| <TrustStore location="truststore.jks" passwordFile="${sys:user.home}/truststore.pwd"/> |
| </SSL> |
| ...</pre></div> |
| |
| </section></section> |
| <a name="SyslogAppender"></a> |
| <section> |
| <h3><a name="SyslogAppender"></a>SyslogAppender</h3> |
| |
| <p> |
| The SyslogAppender is a SocketAppender that writes its output to a remote destination |
| specified by a host and port in a format that conforms with either the BSD Syslog format or the RFC 5424 |
| format. The data can be sent over either TCP or UDP. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">SyslogAppender Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>advertise</td> |
| |
| <td>boolean</td> |
| |
| <td>Indicates whether the appender should be advertised.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>appName</td> |
| |
| <td>String</td> |
| |
| <td>The value to use as the APP-NAME in the RFC 5424 syslog record.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>charset</td> |
| |
| <td>String</td> |
| |
| <td>The character set to use when converting the syslog String to a byte array. The String must be |
| a valid <a class="externalLink" href="http://download.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html">Charset</a>. |
| If not specified, the default system Charset will be used.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>connectTimeoutMillis</td> |
| |
| <td>integer</td> |
| |
| <td>The connect timeout in milliseconds. The default is 0 (infinite timeout, like Socket.connect() |
| methods).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>enterpriseNumber</td> |
| |
| <td>integer</td> |
| |
| <td>The IANA enterprise number as described in |
| <a class="externalLink" href="http://tools.ietf.org/html/rfc5424#section-7.2.2">RFC 5424</a></td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>filter</td> |
| |
| <td>Filter</td> |
| |
| <td>A Filter to determine if the event should be handled by this Appender. More than one Filter |
| may be used by using a CompositeFilter.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>facility</td> |
| |
| <td>String</td> |
| |
| <td>The facility is used to try to classify the message. The facility option must be set to one of |
| "KERN", "USER", "MAIL", "DAEMON", "AUTH", "SYSLOG", "LPR", "NEWS", "UUCP", "CRON", "AUTHPRIV", |
| "FTP", "NTP", "AUDIT", "ALERT", "CLOCK", "LOCAL0", "LOCAL1", "LOCAL2", "LOCAL3", "LOCAL4", "LOCAL5", |
| "LOCAL6", or "LOCAL7". These values may be specified as upper or lower case characters.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>format</td> |
| |
| <td>String</td> |
| |
| <td>If set to "RFC5424" the data will be formatted in accordance with RFC 5424. Otherwise, it will |
| be formatted as a BSD Syslog record. Note that although BSD Syslog records are required to be |
| 1024 bytes or shorter the SyslogLayout does not truncate them. The RFC5424Layout also does not |
| truncate records since the receiver must accept records of up to 2048 bytes and may accept records |
| that are longer.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>host</td> |
| |
| <td>String</td> |
| |
| <td>The name or address of the system that is listening for log events. This parameter is required.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>id</td> |
| |
| <td>String</td> |
| |
| <td>The default structured data id to use when formatting according to RFC 5424. If the LogEvent contains |
| a StructuredDataMessage the id from the Message will be used instead of this value.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>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 |
| <a href="#FailoverAppender">FailoverAppender</a>.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>immediateFail</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true, log events will not wait to try to reconnect and will fail immediately if the |
| socket is not available.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>immediateFlush</td> |
| |
| <td>boolean</td> |
| |
| <td>When set to true - the default, each write will be followed by a flush. |
| This will guarantee the data is written |
| to disk but could impact performance.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>includeMDC</td> |
| |
| <td>boolean</td> |
| |
| <td>Indicates whether data from the ThreadContextMap will be included in the RFC 5424 Syslog record. |
| Defaults to true.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>Layout</td> |
| |
| <td>Layout</td> |
| |
| <td>A custom layout which overrides the format setting.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>loggerFields</td> |
| |
| <td>List of KeyValuePairs</td> |
| |
| <td>Allows arbitrary PatternLayout patterns to be included as specified ThreadContext fields; no default |
| specified. To use, include a >LoggerFields< nested element, containing one or more |
| >KeyValuePair< elements. Each >KeyValuePair< must have a key attribute, which |
| specifies the key name which will be used to identify the field within the MDC Structured Data element, |
| and a value attribute, which specifies the PatternLayout pattern to use as the value.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mdcExcludes</td> |
| |
| <td>String</td> |
| |
| <td>A comma separated list of mdc keys that should be excluded from the LogEvent. This is mutually |
| exclusive with the mdcIncludes attribute. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mdcIncludes</td> |
| |
| <td>String</td> |
| |
| <td>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. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mdcRequired</td> |
| |
| <td>String</td> |
| |
| <td>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. This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>mdcPrefix</td> |
| |
| <td>String</td> |
| |
| <td>A string that should be prepended to each MDC key in order to distinguish it from event attributes. |
| The default string is "mdc:". This attribute only applies to RFC 5424 syslog records.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>messageId</td> |
| |
| <td>String</td> |
| |
| <td>The default value to be used in the MSGID field of RFC 5424 syslog records. </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>newLine</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, a newline will be appended to the end of the syslog record. The default is false.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>port</td> |
| |
| <td>integer</td> |
| |
| <td>The port on the host that is listening for log events. This parameter must be specified.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>protocol</td> |
| |
| <td>String</td> |
| |
| <td>"TCP" or "UDP". This parameter is required.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>SSL</td> |
| |
| <td>SslConfiguration</td> |
| |
| <td>Contains the configuration for the KeyStore and TrustStore. See <a href="#SSL">SSL</a>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>reconnectionDelayMillis</td> |
| |
| <td>integer</td> |
| |
| <td>If set to a value greater than 0, after an error the SocketManager will attempt to reconnect to |
| the server 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).</td> |
| </tr> |
| </table> |
| |
| <p> |
| A sample syslogAppender configuration that is configured with two SyslogAppenders, one using the BSD |
| format and one using RFC 5424. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <Syslog name="bsd" host="localhost" port="514" protocol="TCP"/> |
| <Syslog name="RFC5424" format="RFC5424" host="localhost" port="8514" |
| protocol="TCP" appName="MyApp" includeMDC="true" |
| facility="LOCAL0" enterpriseNumber="18060" newLine="true" |
| messageId="Audit" id="App"/> |
| </Appenders> |
| <Loggers> |
| <Logger name="com.mycorp" level="error"> |
| <AppenderRef ref="RFC5424"/> |
| </Logger> |
| <Root level="error"> |
| <AppenderRef ref="bsd"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <p> |
| For <a href="#SSL">SSL</a> this appender writes its output to a remote destination specified by a host and port over SSL in |
| a format that conforms with either the BSD Syslog format or the RFC 5424 format. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="warn" name="MyApp" packages=""> |
| <Appenders> |
| <TLSSyslog name="bsd" host="localhost" port="6514"> |
| <SSL> |
| <KeyStore location="log4j2-keystore.jks" passwordEnvironmentVariable="KEYSTORE_PASSWORD"/> |
| <TrustStore location="truststore.jks" passwordFile="${sys:user.home}/truststore.pwd"/> |
| </SSL> |
| </TLSSyslog> |
| </Appenders> |
| <Loggers> |
| <Root level="error"> |
| <AppenderRef ref="bsd"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| </section> |
| |
| <a name="JeroMQAppender"></a> |
| <section> |
| <h3><a name="ZeroMQ.2FJeroMQ_Appender"></a>ZeroMQ/JeroMQ Appender</h3> |
| |
| <p> |
| The ZeroMQ appender uses the <a class="externalLink" href="https://github.com/zeromq/jeromq">JeroMQ</a> library to send log |
| events to one or more ZeroMQ endpoints. |
| </p> |
| |
| <p> |
| This is a simple JeroMQ configuration: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration name="JeroMQAppenderTest" status="TRACE"> |
| <Appenders> |
| <JeroMQ name="JeroMQAppender"> |
| <Property name="endpoint">tcp://*:5556</Property> |
| <Property name="endpoint">ipc://info-topic</Property> |
| </JeroMQ> |
| </Appenders> |
| <Loggers> |
| <Root level="info"> |
| <AppenderRef ref="JeroMQAppender"/> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| <p> |
| The table below describes all options. Please consult the JeroMQ and ZeroMQ documentation for details. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">JeroMQ Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>name</td> |
| |
| <td>String</td> |
| |
| <td>The name of the Appender. Required.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>Layout</td> |
| |
| <td>layout</td> |
| |
| <td>The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout |
| of "%m%n" will be used.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>Filters</td> |
| |
| <td>Filter</td> |
| |
| <td>The Filter(s) of the Appender.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>Properties</td> |
| |
| <td>Property[]</td> |
| |
| <td>One or more Property elements, named endpoint.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ignoreExceptions</td> |
| |
| <td>boolean</td> |
| |
| <td>If true, exceptions will be logged and suppressed. If false errors will be logged and then passed to the application.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>affinity</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_AFFINITY option. Defaults to 0.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>backlog</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_BACKLOG option. Defaults to 100.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>delayAttachOnConnect</td> |
| |
| <td>boolean</td> |
| |
| <td>The ZMQ_DELAY_ATTACH_ON_CONNECT option. Defaults to false.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>identity</td> |
| |
| <td>byte[]</td> |
| |
| <td>The ZMQ_IDENTITY option. Defaults to none.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>ipv4Only</td> |
| |
| <td>boolean</td> |
| |
| <td>The ZMQ_IPV4ONLY option. Defaults to true.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>linger</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_LINGER option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>maxMsgSize</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_MAXMSGSIZE option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>rcvHwm</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_RCVHWM option. Defaults to 1000.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>receiveBufferSize</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_RCVBUF option. Defaults to 0.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>receiveTimeOut</td> |
| |
| <td>int</td> |
| |
| <td>The ZMQ_RCVTIMEO option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>reconnectIVL</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_RECONNECT_IVL option. Defaults to 100.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>reconnectIVLMax</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_RECONNECT_IVL_MAX option. Defaults to 0.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>sendBufferSize</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_SNDBUF option. Defaults to 0.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>sendTimeOut</td> |
| |
| <td>int</td> |
| |
| <td>The ZMQ_SNDTIMEO option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>sndHwm</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_SNDHWM option. Defaults to 1000.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>tcpKeepAlive</td> |
| |
| <td>int</td> |
| |
| <td>The ZMQ_TCP_KEEPALIVE option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>tcpKeepAliveCount</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_TCP_KEEPALIVE_CNT option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>tcpKeepAliveIdle</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_TCP_KEEPALIVE_IDLE option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>tcpKeepAliveInterval</td> |
| |
| <td>long</td> |
| |
| <td>The ZMQ_TCP_KEEPALIVE_INTVL option. Defaults to -1.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>xpubVerbose</td> |
| |
| <td>boolean</td> |
| |
| <td>The ZMQ_XPUB_VERBOSE option. Defaults to false.</td> |
| </tr> |
| </table> |
| </section> |
| |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2020 <a class="external" href="http://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
