HipChat event handler

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.

Configuration

Configuration as well as default option values for the HipChat event handler are set in your kapacitor.conf. Below is an example configuration:

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

enabled

Set to true to enable HipChat event handler.

url

The HipChat API URL. Replace subdomain with your HipChat subdomain.

room

Default room for messages. This serves as the default room ID if the TICKscript does not specify a room ID. Visit the HipChat API documentation for information on obtain your room ID.

token

Default authentication token. This serves as the default token if the TICKscript does not specify an API access token. Visit the HipChat API documentation for information on obtain your authentication token.

global

If true, all alerts are sent to HipChat without explicitly specifying HipChat in the TICKscript.

state-changes-only

If true, alerts will only be sent to HipChat if the alert state changes. This only applies if the global is also set to true.

Options

The following HipChat event handler options can be set in a handler file or when using .hipchat() in a TICKscript.

Example: handler file

topic: topic-name
id: handler-id
kind: hipchat
options:
  room: 'alerts'
  token: 'mysupersecretauthtoken'

Example: TICKscript

|alert()
  // ...
  .hipChat()
    .room('alerts')
    .token('mysupersecretauthtoken')

HipChat Setup

Requirements

To configure Kapacitor with HipChat, the following is needed:

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

Get your HipChat API access token

1. Log into your HipChat account dashboard.
2. Select "API access" in the left menu.
3. Under "Create new token", enter a label for the token. The label is arbitrary and is meant only to help identify the token.
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:

Using the HipChat Event Handler

With the HipChat event handler enabled in your kapacitor.conf, use the .hipchat() attribute in your TICKscripts to send alerts to HipChat or define a HipChat handler that subscribes to a topic and sends published alerts to HipChat.

To avoid posting a message every alert interval, use AlertNode.StateChangesOnly so only events where the alert changed state are sent to Alerta.

The examples below use the following HipChat configuration defined in the kapacitor.conf:

HipChat settings in kapacitor.conf

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

Send alerts to a HipChat room from a TICKscript

The following TICKscript uses the .hipchat() event handler to send the message, "Hey, check your CPU", whenever idle CPU usage drops below 10%. It publishes the messages to the alerts room associated with the HipChat subdomain defined in the kapacitor.conf.

hipchat-cpu-alert.tick

stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .stateChangesOnly()
    .message('Hey, check your CPU')
    .hipchat()
      .room('alerts')

Send alerts to the HipChat room from a defined handler

The following setup sends an alert to the cpu topic with the message, "Hey, check your CPU". A HipChat handler is added that subscribes to the cpu topic and publishes all alert messages to the alerts room associated with the testest HipChat subdomain defined in the kapacitor.conf.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an alert message to the cpu topic any time CPU idle usage drops below 10% (or CPU usage is above 90%).

cpu_alert.tick

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

Add and enable the TICKscript:

kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert

Create a handler file that subscribes to the cpu topic and uses the HipChat event handler to send alerts to the alerts channel in HipChat.

hipchat_cpu_handler.yaml

id: hipchat-cpu-alert
topic: cpu
kind: hipchat
options:
  room: 'alerts'

Add the handler:

kapacitor define-topic-handler hipchat_cpu_handler.yaml