[LOG4J2-1730]: Add documentation for CassandraAppender
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/536f6a8d Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/536f6a8d Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/536f6a8d Branch: refs/heads/master Commit: 536f6a8d990a1c2b13aa59c64f1c25f49c0fc856 Parents: 33e7ab3 Author: Matt Sicker <[email protected]> Authored: Sat Dec 31 18:48:39 2016 -0600 Committer: Matt Sicker <[email protected]> Committed: Sat Dec 31 18:48:39 2016 -0600 ---------------------------------------------------------------------- src/site/site.xml | 1 + src/site/xdoc/manual/appenders.xml | 157 ++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/536f6a8d/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index b69d3a1..1636574 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -122,6 +122,7 @@ <item name="Appenders" href="/manual/appenders.html" collapse="true"> <item name="Async" href="/manual/appenders.html#AsyncAppender"/> + <item name="Cassandra" href="/manual/appenders.html#CassandraAppender"/> <item name="Console" href="/manual/appenders.html#ConsoleAppender"/> <item name="Failover" href="/manual/appenders.html#FailoverAppender"/> <item name="File" href="/manual/appenders.html#FileAppender"/> http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/536f6a8d/src/site/xdoc/manual/appenders.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/appenders.xml b/src/site/xdoc/manual/appenders.xml index 4cd1092..69fe93b 100644 --- a/src/site/xdoc/manual/appenders.xml +++ b/src/site/xdoc/manual/appenders.xml @@ -24,6 +24,7 @@ <author email="[email protected]">Ralph Goers</author> <author email="[email protected]">Gary Gregory</author> <author email="[email protected]">Nick Williams</author> + <author email="[email protected]">Matt SIcker</author> </properties> <body> @@ -49,6 +50,10 @@ <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"/> <subsection name="AsyncAppender"> <p>The AsyncAppender accepts references to other Appenders and causes LogEvents to be written to them @@ -232,6 +237,158 @@ </tr> </table> </subsection> + <a name="CassandraAppender"/> + <subsection name="CassandraAppender"> + <p> + The CassandraAppender writes its output to an <a 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 <code>org.apache.logging.log4j.spi.ThreadContextMap</code> or + <code>org.apache.logging.log4j.spi.ThreadContextStack</code> to store the <a href="thread-context.html">MDC or NDC</a> + in a map or list column respectively. + </p> + <table> + <caption align="top">CassandraAppender Parameters</caption> + <tr> + <th>Parameter Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td>batched</td> + <td>boolean</td> + <td>Whether or not to use batch statements to write log messages to Cassandra. By default, this is <code>false</code>.</td> + </tr> + <tr> + <td>batchType</td> + <td><a 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 <code>LOGGED</code>.</td> + </tr> + <tr> + <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> + <td>clusterName</td> + <td>String</td> + <td>The name of the Cassandra cluster to connect to.</td> + </tr> + <tr> + <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 + <code>String</code>. If the configured type is assignment-compatible with + <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextMap.html">ThreadContextMap</a> + or + <a class="javadoc" href="../log4j-api/apidocs/org/apache/logging/log4j/spi/ThreadContextStack.html">ThreadContextStack</a>, + then that column will be populated with the MDC or NDC respectively. Otherwise, the layout or pattern + specified will be converted into the configured type and stored in that column. + </td> + </tr> + <tr> + <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, <code>localhost:9042</code> will be used.</td> + </tr> + <tr> + <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> + <td>ignoreExceptions</td> + <td>boolean</td> + <td>The default is <code>true</code>, causing exceptions encountered while appending events to be + internally logged and then ignored. When set to <code>false</code> exceptions will be propagated to the + caller, instead. You must set this to <code>false</code> when wrapping this Appender in a + <a href="#FailoverAppender">FailoverAppender</a>.</td> + </tr> + <tr> + <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> + <td>name</td> + <td>String</td> + <td>The name of the Appender.</td> + </tr> + <tr> + <td>password</td> + <td>String</td> + <td>The password to use (along with the username) to connect to Cassandra.</td> + </tr> + <tr> + <td>table</td> + <td>String</td> + <td>The name of the table to write log messages to.</td> + </tr> + <tr> + <td>useClockForTimestampGenerator</td> + <td>boolean</td> + <td>Whether or not to use the configured <code>org.apache.logging.log4j.core.util.Clock</code> 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 <code>false</code>.</td> + </tr> + <tr> + <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> + <td>useTls</td> + <td>boolean</td> + <td>Whether or not to use TLS/SSL to connect to Cassandra. This is <code>false</code> by default.</td> + </tr> + </table> + <p> + Here is an example CassandraAppender configuration: + </p> + <pre class="prettyprint linenums"><![CDATA[ +<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="message" pattern="%message"/> + <ColumnMapping name="level" pattern="%level"/> + <ColumnMapping name="marker" pattern="%marker"/> + <ColumnMapping name="logger" pattern="%logger"/> + <ColumnMapping name="timestamp" pattern="%date{UNIX_MILLIS}" type="java.lang.Long"/> + <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.nosql.appender.cassandra" level="DEBUG"> + <AppenderRef ref="Cassandra"/> + </Logger> + <Root level="ERROR"/> + </Loggers> +</Configuration> +]]></pre> + <p> + This example configuration uses the following table schema: + </p> + <pre class="prettyprint linenums"><![CDATA[ +CREATE TABLE logs ( + id timeuuid PRIMARY KEY, + message text, + level text, + marker text, + logger text, + timestamp timestamp, + mdc map<text,text>, + ndc list<text> +); +]]></pre> + </subsection> <a name="ConsoleAppender"/> <subsection name="ConsoleAppender"> <p>
