Home

The log4j-sns project provides an Amazon SNS appender, allowing users of the popular log4j logging framework to deliver logging notifications (usually WARNings) to subscribers through email, HTTP and SQS messages.

---

Why should I use SNS to deliver my logging notifications?

1. The SNS service allows you to decouple yours logging notifications from the subscribers. You don't need to know in advance who will be receiving the notifications. Subscribers can be added/removed through the AWS Console interface.
2. It's a better alternative than using the SMTPAppender to send e-mail messages. You could also implement loose coupling through an e-mail list, but that works properly only if you have a single/few servers running your application. Now imagine when you have a server farm/cluster (which is now very popular due to cloud computing environments like EC2): in some use cases, it will be common to have the same exception (WARNing) being logged in multiple servers at the same time. If using an SMTPAppender, you could have an overwhelming amount of e-mail being fired to your inbox(es). With the SNSAppender you have the option of choosing an HTTP endpoint and filtering these messages.
3. You don't want to receive lots of notifications informing you of the exact same WARNing message. You just want to know that something is wrong, and that you should take a look at it. We've implemented QuietPeriodTriggeringEventEvaluator which is plugged by default in the SNSAppender, setting a 15 minutes quiet period by default. During the quiet period you won't receive the same message from the same application instance again, even if logged multiple times. If you want to change the behavior of the quiet period, you can plug your own TriggeringEventEvaluator with the evaluatorClass property of the SNSAppender.

---

Log4j configuration

A simple log4j.properties configuration:

log4j.rootLogger=WARN, SNS

log4j.appender.SNS=br.com.insula.log4j.sns.SNSAppender
log4j.appender.SNS.AccessKey=YOUR_ACCESS_KEY
log4j.appender.SNS.SecretKey=YOUR_SECRET_KEY
log4j.appender.SNS.Subject=[WARN] SNS Logging
log4j.appender.SNS.Topic=warnings
log4j.appender.SNS.Threshold=WARN
log4j.appender.SNS.layout=org.apache.log4j.PatternLayout
log4j.appender.SNS.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

Customize the AccessKey and SecretKey properties with yours AWS credentials. The Topic property represents the SNS Topic that will be notified. You don't have to create the Topic before using the SNS Appender. It'll be created on first usage. The Subject property will be the e-mail subject if you choose the e-mail subscription on the SNS Topic.

Important: You don't want to receive notifications lower than WARNings in your SNSAppender. It costs money and would be annoying. Think twice before setting the logger level of the SNSAppender lower than WARN.

A more appropriate configuration would be to log all the information in a file and send the notifications with the quiet period through the SNSAppender:

logg4j.rootLogger=WARN, ROLLING, SNS

log4j.appender.ROLLING=org.apache.log4j.RollingFileAppender
log4j.appender.ROLLING.File=my-rolling-file.log
log4j.appender.ROLLING.MaxFileSize=2MB
log4j.appender.ROLLING.MaxBackupIndex=5
log4j.appender.ROLLING.layout=org.apache.log4j.PatternLayout
log4j.appender.ROLLING.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

log4j.appender.SNS=br.com.insula.log4j.sns.SNSAppender
log4j.appender.SNS.AccessKey=YOUR_ACCESS_KEY
log4j.appender.SNS.SecretKey=YOUR_SECRET_KEY
log4j.appender.SNS.Subject=[WARN] SNS Logging
log4j.appender.SNS.Topic=warnings
log4j.appender.SNS.Threshold=WARN
log4j.appender.SNS.layout=org.apache.log4j.PatternLayout
log4j.appender.SNS.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

But of couse it is just a suggestion. Use the right tool for the right job.

---

Maven instructions

Add the following repository into the <repositories> element of your pom.xml:

<repository>
	<id>maven-oss-insula</id>
	<name>Insula Maven OSS Releases Repository</name>
	<url>http://maven-oss.insula.com.br/releases</url>
</repository>

And the following dependency into the <dependencies> element of your pom.xml:

<dependency>
	<groupId>br.com.insula</groupId>
	<artifactId>log4j-sns</artifactId>
	<version>1.1.2</version>
</dependency>