RedisAppender plugin provides a Log4j 2.x appender for Redis in-memory data structure store. The plugin uses Jedis as a client for Redis.

Usage

Add the log4j2-redis-appender dependency to your POM file

<dependency>
    <groupId>com.vlkan.log4j2</groupId>
    <artifactId>log4j2-redis-appender</artifactId>
    <version>${log4j2-redis-appender.version}</version>
</dependency>

together with a valid log4j-core dependency:

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>${log4j2.version}</version>
</dependency>

Below you can find a sample log4j2.xml snippet employing RedisAppender.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <RedisAppender name="REDIS"
                       key="log4j2-messages"
                       host="localhost"
                       port="6379">
            <PatternLayout pattern="%level %msg"/>
            <RedisConnectionPoolConfig testWhileIdle="true"
                                       minEvictableIdleTimeMillis="60000"
                                       timeBetweenEvictionRunsMillis="30000"
                                       numTestsPerEvictionRun="-1"/>
            <RedisThrottlerConfig bufferSize="500"
                                  batchSize="100"
                                  flushPeriodMillis="1000"
                                  maxEventCountPerSecond="100"
                                  maxByteCountPerSecond="4194304"
                                  maxErrorCountPerSecond="0.003"/>
        </RedisAppender>
    </Appenders>
    <Loggers>
        <Root level="all">
            <AppenderRef ref="REDIS"/>
        </Root>
    </Loggers>
</Configuration>

One can make RedisAppender work against a sentinel setup using sentinelNodes and sentinelMaster parameters:

<RedisAppender name="REDIS"
               key="log4j2-messages"
               sentinelNodes="localhost:63791,localhost:63792"
               sentinelMaster="mymaster">
...
</RedisAppender>

Note that sentinelNodes and sentinelMaster have priority over host and port parameters.

RedisAppender is configured with the following parameters:

Parameter Name	Type	Default	Description
`charset`	String	`UTF-8`	output charset
`database`	int	0	Redis logical database
`key`	String		Redis queue key
`host`	String	`localhost`	Redis host
`port`	int	6379	Redis port
`sentinelNodes`	String	`null`	Redis sentinel nodes as comma-separated list, e.g., `host1:port1,host2:port2`. If specified, `host` and `port` parameters are ignored.
`sentinelMaster`	String	`null`	Redis sentinel master name
`username`	String	`default`	Redis username
`password`	String	`null`	Redis password
`command`	String	`rpush`	Redis command for writing to the queue. Accepts `rpush` (default) and `publish`.
`connectionTimeoutSeconds`	int	2	initial connection timeout in seconds
`socketTimeoutSeconds`	int	2	socket timeout in seconds
`ignoreExceptions`	boolean	`true`	Enabling causes exceptions encountered while appending events to be internally logged and then ignored. When set to false, exceptions will be propagated to the caller, instead. You must set this to false when wrapping this appender in a `FailoverAppender`.
`Layout`	Layout	`PatternLayout`	used to format the `LogEvent`s
`RedisConnectionPoolConfig`	RedisConnectionPoolConfig		Redis connection pool configuration
`RedisThrottlerConfig`	RedisThrottlerConfig		Redis throttler configuration

Redis Connection Pool

RedisConnectionPoolConfig is a wrapper for JedisPoolConfig which extends GenericObjectPoolConfig of Apache Commons Pool. Below is a complete list of available RedisConnectionPoolConfig attributes.

Parameter Name	Type	Default
`maxTotal`	int	8
`maxIdle`	int	8
`minIdle`	int	0
`lifo`	boolean	`true`
`fairness`	boolean	`false`
`maxWaitMillis`	long	-1
`minEvictableIdleTimeMillis`	long	1000 * 60
`softMinEvictableIdleTimeMillis`	long	-1
`numTestsPerEvictionRun`	int	-1
`testOnCreate`	boolean	`false`
`testOnBorrow`	boolean	`false`
`testOnReturn`	boolean	`false`
`testWhileIdle`	boolean	`true`
`timeBetweenEvictionRunsMillis`	long	1000 * 30
`evictionPolicyClassName`	String	`org.apache.commons.pool2.impl.DefaultEvictionPolicy`
`blockWhenExhausted`	boolean	`true`
`jmxEnabled`	boolean	`true`
`jmxNameBase`	String	`null`
`jmxNamePrefix`	String	`com.vlkan.log4j2.redis.appender.JedisConnectionPool`

Redis Throttler

While Log4j 2 provides utilities like BurstFilter and AsyncAppender that you can wrap around any appender to facilitate throttling, the appender API falls short of communicating this intent. Hence, RedisAppender provides its own throttling mechanics to exploit batch pushes available in Redis RPUSH. This feature is configured by RedisThrottlerConfig element using the following attributes:

Parameter Name	Type	Description
`bufferSize`	int	`LogEvent` buffer size (defaults to 500)
`batchSize`	int	size of batches fed into Redis `RPUSH` (defaults to 100)
`flushPeriodMillis`	long	buffer flush period (defaults to 1000)
`maxEventCountPerSecond`	double	allowed maximum number of events per second (defaults to 0, that is, unlimited)
`maxByteCountPerSecond`	double	allowed maximum number of bytes per second (defaults to 0, that is, unlimited)
`maxErrorCountPerSecond`	double	allowed maximum number of errors per second propagated (defaults to 0.003, that is, approximately once every 5 minutes)
`jmxBeanName`	String	`RedisThrottlerJmxBean` name (defaults to `org.apache.logging.log4j2:type=<loggerContextName>,component=Appenders,name=<appenderName>,subtype=RedisThrottler`)

The buffer is flushed if either there are more than batchSize events queued in the buffer, or the last flush was older than flushPeriodMillis.

maxErrorCountPerSecond is there to avoid flooding logs if the application is suffering a shortage of memory, or the Redis server is unreachable.

Fat JAR

Project also contains a log4j2-redis-appender-fatjar artifact which includes all its transitive dependencies in a separate shaded package (to avoid the JAR Hell) with the exception of log4j-core, that you need to include separately.

This might come handy if you want to use this plugin along with already compiled applications, e.g., Elasticsearch 5.x, which requires Log4j 2.x.

F.A.Q.

How can I connect to multiple Redis servers for failover? You can define multiple Redis appenders nested under a FailoverAppender. (Don't forget to turn off ignoreExceptions flag.)

How can I avoid getting AccessControlException exceptions? If you are using the plugin in a security manager enabled Java application (for instance, which is the case for Elasticsearch since version 2.3), you might be getting AccessControlException exceptions as follows:

[2017-06-23T11:25:35,644][WARN ][o.e.b.ElasticsearchUncaughtExceptionHandler] [tst-store-001.data] uncaught exception in thread [commons-pool-EvictionTimer]
java.security.AccessControlException: access denied ("java.lang.RuntimePermission" "setContextClassLoader")
        at java.security.AccessControlContext.checkPermission(AccessControlContext.java:472) ~[?:1.8.0_131]
        at java.security.AccessController.checkPermission(AccessController.java:884) ~[?:1.8.0_131]
        at java.lang.SecurityManager.checkPermission(SecurityManager.java:549) ~[?:1.8.0_131]
        at java.lang.Thread.setContextClassLoader(Thread.java:1474) [?:1.8.0_131]
        at org.apache.commons.pool2.impl.BaseGenericObjectPool$Evictor.run(BaseGenericObjectPool.java:1052) ~[log4j2-redis-appender.jar:?]
        at java.util.TimerThread.mainLoop(Timer.java:555) ~[?:1.8.0_131]
        at java.util.TimerThread.run(Timer.java:505) ~[?:1.8.0_131]

To alleviate this, you need to grant necessary permissions using a policy file:

grant {
    permission java.lang.RuntimePermission "setContextClassLoader";
};

Then you can activate this policy for your application via either placing it under one of default policy file locations (e.g., $JAVA_HOME/lib/security/java.policy) or providing it as an argument at runtime, that is, -Djava.security.policy=someURL.

How can I access JMX bean of an appender? Once you have a reference to the relevant LoggerContext, you can access the instance of the appender and its JMX bean by its name as follows:

Appender appender = loggerContext.getConfiguration().getAppender("REDIS");
RedisThrottlerJmxBean jmxBean = ((RedisAppender) appender).getJmxBean();

You can either create your own LoggerContext:

LoggerContextResource loggerContextResource = new LoggerContextResource("/path/to/log4j2.xml");
LoggerContext loggerContext = loggerContextResource.getLoggerContext();

or get a handle to an existing one:

 LoggerContext logContext = (LoggerContext) LogManager.getContext(false);

Here note that you should be using org.apache.logging.log4j.core.LoggerContext, not org.apache.logging.log4j.spi.LoggerContext.

Contributors

Security policy

If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to the volkan@yazi.ci email address.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

vy / log4j2-redis-appender