Logstash comes with a number of plugins that interact with AWS, Amazon’s cloud infrastructure. This short guide will look at the configuration options for the Simple Notification Service (or SNS) output that will allow you to convert Logstash events to push messages to various mobile devices, as well as to more traditional messages such as SMS texts and emails.

Keep in mind: This plugin uses the AWS config plugin options.

Quick Info

Links: Documentation | Source
Version: 1.4.2
Requirements:

  • AWS Account
  • AWS Credentials with access to the SNS service OR
  • An instance of Logstash running on EC2 with access to the SNS service.

TL;DR

Logstash needs to know what AWS credentials it should use to access the SNS service. Configure those using the AWS config plugin options. All of these examples assume that access to the service is set up using the environment variables.

The only two required options (other than the credentials) are region and arn:

region – The AWS region for the SNS service.

arn – The SNS topic to which the event should be sent.

# Bare minimum
output {
  sns {
    region => "us-east-1"
    arn => "arn:aws:sns:us-east-1:770975001275:logstash-testing"
  }
}

With this setup you’ll be sending all of your events to the logstash-testing topic in plain text format. You can omit the arn parameter if your event contains an sns field. See below for more detail.

The highlights

You can use the fields present in the Logstash event to further customize the SNS output.

SNS alert content

The subject and the body of the SNS alert will be set to the contents of the sns_subject and sns_message fields respectively if they are present in the event. If the sns_subject field is not present, the event’s source will be used in stead. If the sns_message field isn’t present, the whole event will be converted to plain text (by default) or JSON (if format is set to json).

Keep in mind: The subject will be truncated to 100 characters and the message to 32768 bytes.

# SNS message content
filter {
  mutate {
    rename => [ "message", "sns_message" ] # Use the message property as the content of the SNS alert
    add_field => { "sns_subject" => "Alert: %{type}" } # Use the type property as the subject of the SNS alert
  }
}

ARN

Logstash events can be sent to different SNS topics by populating the sns field of the event.

# Custom ARN
filter {
  mutate {
    add_field => { "sns" => "arn:aws:sns:us-east-1:770975001275:type-%{type}" } # Send events to different topics dependent on the event type
  }
}

All the options

region – String – The AWS region for the SNS service.

arn – String – The SNS topic to which the event should be sent.

format – String – This parameter can be used to specify that the message should be encoded as JSON or plain text. The possible values are json and plain. This option won’t be used if the sns_message property is present in the event.

publish_boot_message_arn – String – Specify an ARN for a SNS topic in this parameter if you’d like to be notified when this plugin boots up. This happens in the registration phase of the plugin.


Did you have any issues setting up SNS? Tell us about it in the comments or buy The Logstash Config Guide to soothe the pain!

Coder. Thinker. Human. I try to write good code for a living and wrangle data as a hobby. Be sure to check out the book I'm writing: The Logstash Config Guide.

Subscribe To Our Newsletter

Subscribe To Our Newsletter

Join our mailing list to receive the latest news and updates from our team.

You have Successfully Subscribed!

Share This