Skip to content

Latest commit

 

History

History
78 lines (55 loc) · 4.04 KB

sns.md

File metadata and controls

78 lines (55 loc) · 4.04 KB
Raw

Simple Notification Service (SNS)

The SNS appender is intended to support real-time error notifications, operating concurrently with other logging outputs. You would configure the appender to only respond to messages with the ERROR level, and then hook the destination SNS topic to feed a messaging application.

The SNS appender provides the following features:

  • Configurable destination topic, with substitution variables to specify topic name
  • Optional message subjects, useful for email reporting.
  • Auto-creation of topics
  • Configurable discard in case of network connectivity issues

Configuration

Your Log4J configuration will look something like this (note the threshold setting; this is a Log4J feature that allows different appenders to receive different levels of output):

log4j.rootLogger=ERROR, sns

log4j.appender.sns=com.kdgregory.log4j.aws.SNSAppender
log4j.appender.sns.threshold=ERROR
log4j.appender.sns.topicArn=arn:aws:sns:us-east-1:123456789012:LoggingExample
log4j.appender.sns.subject=Error from {env:APPNAME}

log4j.appender.sns.layout=org.apache.log4j.PatternLayout
log4j.appender.sns.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n

The appender provides the following properties (also described in the JavaDoc):

Name Description
topicName The name of the SNS topic that will receive messages; no default value. See below for more information.
topicArn The ARN of the SNS topic that will receive messages; no default value. See below for more information.
subject If used, attaches a subject to each message sent; no default value. See below for more information.
discardThreshold The threshold count for discarding unsent messages; default is 1,000. See design doc for more information.
discardAction Which messages will be discarded once the threshold is passed: oldest (the default), newest, or none.
clientFactory Specifies the fully-qualified name of a static method that will be used to create the AWS service client via reflection. See design doc for more information.
clientEndpoint Specifies a non-default endpoint for the client (eg, "sns.us-east-2.amazonaws.com")

The topicName, topicArn, and subject properties may use substitutions.

Permissions

To use this appender you will need to grant the following IAM permissions:

  • sns:CreateTopic (may be omitted if topic already exists)
  • sns:ListTopics
  • sns:Publish

Operation

The SNS appender writes messages as simple text strings, formatted according to the layout manager; it does not support platform-specific payloads. Messages can have an optional subject, and this text may use substitutions. This is useful to identify the source of a message when sending to an email address. Note that substitutions are applied when the appender starts, not on a per-message basis.

You can specify the destination topic either by ARN or name. When specifying topic by ARN, the topic must already exist. If you specify the topic by name, the appender will attempt to find an existing topic with the specified name. If unable to find an existing topic it will create the topic.

The appender assumes that, when listing topics, it will only receive topics for the current region. That constraint is not explicitly stated in the API docs but is the current observed behavior. If this behavior ever changes, the appender may choose an unexpected topic.

You may use substitutions in either the topic name or ARN. When constructing an ARN it's particularly useful to use {env:AWS_REGION} or {ec2:region} along with {aws:accountId}.

While the appender exposes the batch delay configuration parameters, these are ignored. Each message will be sent as soon as possible after it's passed to the appender (SNS does not support message batching).