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

• Configuration Options

• Testing

• Download

• Notes

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.

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 …

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:

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

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

• You can download the Clickatell AlarmCallback Plugin source from our GitHub account

• You can also download the binary from our drone.io account

• The plugin is LICENSED under Apache 2.0 so you can freely use and modify it

Notes

• Password protected field of AlarmCallback plugin is displayed as clear text in web interface
  Currently there is a bug in the Graylog web interface (or in the Graylog Server portion) as the API key is displayed in clear text, tough it is supposed to be a password protected field.

• Displayed field order of plugin does not match added order in ConfigurationRequest object
  The order of configuration fields cannot be controlled and is displayed somehow randomly on the UI making it harder for a user to fill out the fields.

• Alarm callback search results payload broken
  Curently there is no direct way to retrieve the Message object from within an AlarmCallback plugin, but only via a workaround.

• When programming a Plugin that targets the v1 branch of Graylog be careful to work with the correct Maven Archetype and explicitly specify the version as recommended by Jochen Schalanda:

  mvn archetype:generate -DarchetypeGroupId=org.graylog -DarchetypeArtifactId=graylog-plugin-archetype -DarchetypeVersion=1.0.0