Clickatell AlarmCallback Plugin for Graylog v1.0.0

Introduction

This Graylog AlarmCallback Plugin can send short messages (SMS) via the Clickatell Messaging Provider based on alert conditions configured in Graylog. It is based on the new version 1 plugin architecture (though for AlarmCallback Plugins not that much has changed).

Here is a brief overview of what is covered:

Installation

You install this plugin by copying the JAR file to the Graylog plugin directory which is /opt/graylog/plugins by default. After a restart of the Graylog server the plugin will be visible under the Details view of the Node under System menu.

Installed Plugin

You can also follow the information in Using drone.io to automatically integrate your Graylog2 Plugins in Docker to integrate the plugin in your docker image.

Configuration Options

There are several options you can use to configure the plugin. Some of them are specific to Clickatell as the messaging provider and some are specific to the message properties from Graylog.

  1. CONFIG_AUTH_TOKEN, Clickatell AuthToken
    This field is mandatory and lets you specify the Clickatell REST API AUTHTOKEN key.

  2. CONFIG_RECIPIENTS, Recipients of short message
    This field is mandatory and lets you specify the recpients where the messages should be sent to. The format of the telephone numbers must be in international format and must consist of only numbers with no leading zero or whatsoever. Example: 27999112345.
    Multiple numbers can be separated by a comma, ie. 27999112345,27999112346.
    Clickatell has defined a test range (starting with 27999) that you can use to test the messaging API without actually sending short messages.

  3. CONFIG_RESULT_DESCRIPTION, Include result description in short message
    When this boolean field is selected the generated short message will contain the alarm description at the beginning of the message. This option is enabeld by default.

  4. CONFIG_FIELDS, Fields to send in short message
    You can specify the fields of the message to be sent when an alert is generated. Fields will appear in th message in the order you specify them in the text field, where each field is separated by a comma. Builtin fields must be enclosed with chevrons (e.g. <timestamp>), whereas additional fields must be specified without (e.g. myExtraMessageField).
    If you do not specify any fields the following fields will be included in the message: timestamp, stream, source, message
    When you specify a field name that does not exist, it will be skipped.

  5. CONFIG_INCLUDE_FIELD_NAMES, Include field names in short message
    If you specify this option, the actual field names along with their values are sent in the short message. This option is enabeld by default.

  6. CONFIG_MAX_LENGTH, MaxLength
    If you want to limit the maximum message size, you can specify a number larger than 0. Leaving this option at the default value of 0 means, there is no message size limit. But keep in mind, that currently clickatell supports only 35 message parts with approximately 4900 characters.
    When you send a message that exceeds this limit the message is truncated to the specified size.

  7. CONFIG_MAX_CREDITS, MaxCredits
    You can also specify the maximum number of credits a message may cost (per recipient). Leaving this option at 0 means there is no credit restriction.

  8. CONFIG_MAX_PARTS, MaxParts
    This option lets you limit the number of parts a short message can consist of. Currently Clickatell supports 35 parts. Please note that this setting has no effect when you specify a maximum inside the Clickatell API configuration on your Developer Central account. Leaving this value at 0 means there is no restriction.

  9. CONFIG_STATIC_TEXT, Static text that prepends the short message
    With this optional field you can specify a static text that will prepend every message that is sent.

The following screenshot shows the previously described options …
Installed Plugin

Testing


To test the plugin you create a stream and add an alert condition such as message count and add the AlarmCallback with the options described in Configuration Options that it will look similar to this:

Installed Plugin

After you inserted some messages into Graylog and an alert is generated you will a receive a message like this:

Sent SMS

As you can see in the screenshot the plugin has been configured with a statics text testmessage2 and the complete alarm result text (Field cpu had a MIN of 34 ...). In addition the fields names and values stream, timestamp, message, cpu, disk, mem are sent with the message. As there is no message size limit defined the whole message is sent.

Download

Notes

Trackbacks

  1. […] It is based on the new version 1 plugin architecture. This plugin does essentially the same as the Clickatell AlarmCallback Plugin for Graylog, but works on streams instead of alert conditions. So with this plugin you can forward all messages […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: