Using Kapacitor event handlers to send alert messages

Kapacitor can be integrated into a monitoring system by sending alert messages to supported event handlers. Currently, Kapacitor can send alert messages to specific log files and specific URLs, as well as to many third party applications like Slack and HipChat.

This document offers step-by-step instructions for setting up event handlers with Kapacitor, including the relevant configuration options and TICKscript syntax. Currently, this document does not cover every supported event handler, but additional content should be added to this page over time. For a complete list of the supported event handlers and for additional information, please see the event handler presentation in the Alert node documentation.

• HipChat setup
• Telegram setup

HipChat setup

HipChat is Atlassian’s web service for group chat, video chat, and screen sharing. Kapacitor can be configured to send alert messages to a HipChat room.

Requirements

To configure Kapacitor with HipChat the following will be needed:

• A HipChat subdomain name
• A HipChat room name
• A HipChat API access token for sending notifications

HipChat API Access Token

The following steps describe how to create the API access token.

1. From the HipChat home page, access Account settings by clicking on the person icon in the top right corner.

2. Select API access from the items in the left menu sidebar.

3. Under Create new token, enter a label for the token (it can be anything).

4. Under Create new token, select Send Notification as the Scope.

5. Click Create.

Your token appears in the table just above the Create new token section:

Configuration

In the [hipchat] section of the Kapacitor configuration file set:

• enabled to true
• subdomain in the url setting to the HipChat subdomain

The optional configuration settings are:

room   Set to a HipChat room. This serves as the default chat id if the TICKscript does not specify a chat id. token   Set to a HipChat API access token. This serves as the default token if the TICKscript does not specify an API access token. global   Set to true to send all alerts to HipChat without needing to specify HipChat in TICKscripts. state-changes-only   Set to true to send only an alert to HipChat if the alert state changes. This setting only applies if the global setting is also set to true.

Sample configuration

    [hipchat]
      enabled = true
      url = "https://my-subdomain.hipchat.com/v2/room"
      room = "my-room"
      token = "mytokentokentokentoken"
      global = false
      state-changes-only = false

TICKscript syntax

|alert()
    .hipChat()
        .room('<HipChat-room>')
        .token('<HipChat-API-token>')

The .room() and .token() specifications are optional. If they are not set in the TICKscript, they default to the room and token settings in the [hipchat] section of the configuration file. Note that if global is set to true in the configuration file, there is no need to specify .hipChat() in the TICKscript; Kapacitor sends all alerts to HipChat by default.

.room('<HipChat-room>')    Sets the HipChat room. .token('<HipChat-API-token>')    Sets the HipChat API access token.

Examples

Example 1: Send alerts to the HipChat room set in the configuration file

Configuration file:

[hipchat]
  enabled = true
  url = "https://testtest.hipchat.com/v2/room"
  room = "my-alerts"
  token = "tokentokentokentokentoken"
  global = false
  state-changes-only = true

TICKscript:

stream
    |from()
        .measurement('cpu')
    |alert()
        .crit(lambda: "usage_idle" <  97)
        .message('Hey, check your CPU')
        .hipChat()

The setup sends Hey, check your CPU to the my-alerts room associated with the testest subdomain.

Example 2: Send alerts to the HipChat room set in the TICKscript

Configuration file:

[hipchat]
  enabled = true
  url = "https://testtest.hipchat.com/v2/room"
  room = "my-alerts"
  token = "tokentokentokentokentoken"
  global = false
  state-changes-only = true

TICKscript:

stream
    |from()
        .measurement('cpu')
    |alert()
        .crit(lambda: "usage_idle" <  97)
        .message('Hey, check your CPU')
        .hipChat()
        .room('random')

The setup sends Hey, check your CPU to the random room associated with the testest subdomain. Notice that .room() in the TICKscript overrides the room setting in the configuration file.

Telegram setup

Telegram is a messaging app. Configure Kapacitor to send alert messages to a Telegram bot.

Requirements

To configure Kapacitor with Telegram, the following will be needed:

• a Telegram bot
• a Telegram API access token
• a Telegram chat id

Telegram bot

[telegram]
  enabled = true
  url = "https://api.telegram.org/bot"
  token = "abcdefghi:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  chat-id = "123456789"
  parse-mode = Markdown
  disable-web-page-preview = true
  disable-notification = false
  global = true
  state-changes-only = true

|alert()
    .telegram()
        .chatId('<chat_id>')
        .disableNotification()
        .disableWebPagePreview()
        .parseMode(['Markdown' | 'HTML'])

[telegram]
  enabled = true
  url = "https://api.telegram.org/bot"
  token = "abcdefghi:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  chat-id = "123456789"
  parse-mode  = "Markdown"
  disable-web-page-preview = false
  disable-notification = false
  global = false
  state-changes-only = false

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 97)
    .message('Might want to check your CPU')
    .telegram()

[telegram]
  enabled = true
  url = "https://api.telegram.org/bot"
  token = "abcdefghi:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  chat-id = ""
  parse-mode  = "Markdown"
  disable-web-page-preview = false
  disable-notification = false
  global = false
  state-changes-only = false

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 97)
    .message('Might want to check your CPU')
    .telegram()
      .chatId('123456789')