Splunk® Enterprise

Developing Views and Apps for Splunk Web

Download manual as PDF

Download topic as PDF

HipChat example for custom alert actions

The HipChat example implements an alert action that does the following:

  • Posts a message to a HipChat room.
  • Writes log messages to a Splunk Enterprise log file.

When a user selects the HipChat alert actions, the user can select from various actions that are available.

Python file for the HipChat Example

$SPLUNK_HOME$/etc/apps/hipchat_app/bin/hipchat.py

import sys, json, urllib2

def send_message(settings):
    print >> sys.stderr, "DEBUG Sending message with settings %s" % settings
    room = settings.get('room')
    auth_token = settings.get('auth_token')
    base_url = settings.get('base_url').rstrip('/')
    fmt = settings.get('format', 'text')
    print >> sys.stderr, "INFO Sending message to hipchat room=%s with format=%s" % (room, fmt)
    url = "%s/room/%s/notification?auth_token=%s" % (
        base_url, urllib2.quote(room), urllib2.quote(auth_token)
    )
    body = json.dumps(dict(
        message=settings.get('message'),
        message_format=fmt,
        color=settings.get('color', "green")
    ))
    print >> sys.stderr, 'DEBUG Calling url="%s" with body=%s' % (url, body)
    req = urllib2.Request(url, body, {"Content-Type": "application/json"})
    try:
        res = urllib2.urlopen(req)
        body = res.read()
        print >> sys.stderr, "INFO HipChat server responded with HTTP status=%d" % res.code
        print >> sys.stderr, "DEBUG HipChat server response: %s" % json.dumps(body)
        return 200 <= res.code < 300
    except urllib2.HTTPError, e:
        print >> sys.stderr, "ERROR Error sending message: %s" % e
        return False

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--execute":
        payload = json.loads(sys.stdin.read())
        if not send_message(payload.get('configuration')):
            print >> sys.stderr, "FATAL Failed trying to send room notification"
            sys.exit(2)
        else:
            print >> sys.stderr, "INFO Room notification successfully sent"
    else:
        print >> sys.stderr, "FATAL Unsupported execution mode (expected --execute flag)"
        sys.exit(1)

Configuration files for the HipChat example

The HipChat example for custom alert actions contains the following configuration files.

File Description
alert_actions.conf Define the properties of the custom alert action.
app.conf Package and UI information about the add-on.

Required to display information about logger alert actions on the Alert Actions Manager page.

hipchat_alert_icon.png Icon file for the alert action in the Splunk Enterprise UI.
alert_actions.conf.spec
savedsearches.conf.spec
Configuration spec files describing settings in alert_actions.conf and seavedsearches.conf.

alert_actions.conf

alert_action.conf defines the properties of the custom alert action. It also defines parameters to the hipchat.py script.

$SPLUNK_HOME$/etc/apps/hipchat_app/default/alert_actions.conf

[hipchat]
is_custom = 1
label = HipChat
description = Send HipChat room notifications
icon_path = hipchat_alert_icon.png
payload_format = json

# base URL and Auth token available from your HipChat installation
param.base_url = http://hipchat.splunk.com/v2/
param.auth_token = Hr9marGO3ywwCyZqsE9r91MAMExtFpJKsxCnptbx

app.conf

Defines properties that appear in the Alert Actions Manager page.

[ui]
is_visible = 1
label = Mod Alert Tests

[launcher]
author = Splunk
description = Quick examples for testing mod alerts
version = 1.0

[install]
state = enabled
is_configured = 1

PNG file for the custom alert action icon

The height and width dimensions of the PNG file should be equal. A PNG files with dimensions of 48x48 pixels works best.

$SPLUNK_HOME$/etc/apps/hipchat_app/appserver/static/hipchat_alert_icon.png

Spec files for the custom alert action

The README directory contains the spec files for custom alert actions.

alert_actions.conf.spec

alert_action.conf.spec describes custom settings for the custom alert action. These settings are used across all instances.

$SPLUNK_HOME$/etc/apps/hipchat_app/README/alert_actions.conf.spec

[hipchat]

param.base_url = <string>
* HipChat API base URL - adjust if you're using you own server on premise

param.auth_token = <string>
* HipChat OAuth2 token 
* see https://www.hipchat.com/docs/apiv2/auth

savedsearches.conf.spec

savedsearches.conf.spec describes additional savedsearches.conf settings introduced by the custom alert actions. These are per-instance settings.

Reference the parameters listed here with controls in the form that implements the UI for custom actions. See Configure the UI for custom actions.

$SPLUNK_HOME$/etc/apps/hipchat_app/README/savedsearches.conf.spec

# HipChat alert settings

action.hipchat = [0|1]
* Enable hipchat notification

action.hipchat.param.room = <string>
* Name of the room to send the notification to
* (required)

action.hipchat.param.message = <string>
* The message to send to the hipchat room. 
* (required)

action.hipchat.param.message_format = [html|text]
* The format of the room notification (optional)
* Default is "html"
* (optional)

action.hipchat.param.color = [red|green|blue|yellow|grey]
* Background color of the room notification (optional)
* (optional)

action.hipchat.param.notify = [1|0]
* Notify users in the room
* Defaults to 0 (not notifying users in the room)
* (optional)

action.hipchat.param.auth_token = <string>
* Override Hipchat API auth token from global alert_actions config
* (optional)

HTML file for the custom alert action form

The HTML file defines the form elements for the custom alert action in the Splunk Enterprise UI.

Highlights of the HTML code:

  • Defines a set of controls to display in the form for the custom action.
  • Uses pre-defined CSS styles to define the controls in the form.
  • Uses {{SPLUNKWEB_URL_PREFIX}} to define paths to local resources. [TBD]

$SPLUNK_HOME$/etc/apps/hipchat_app/default/data/ui/alerts/hipchat.html

<form class="form-horizontal form-complex">
    <div class="control-group">
        <label class="control-label" for="hipchat_room">Room</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.room" id="hipchat_room" />
            <span class="help-block">
              The name of a HipChat room.
            </span>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_message">Message</label>

        <div class="controls">
            <textarea name="action.hipchat.param.message" id="hipchat_message" />
            <span class="help-block">
                The chat message for the HipChat room.
                Include tokens to insert text based on search results.
                <a href="{{SPLUNKWEB_URL_PREFIX}}/help?location=learnmore.alert.action.tokens" target="_blank"
                   title="Splunk help">Learn More <i class="icon-external"></i></a>
            </span>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label">Message Format</label>

        <div class="controls">
            <label class="radio" for="hipchat_message_format_plain">
                <input id="hipchat_message_format_plain" type="radio" name="action.hipchat.param.message_format" value="plain" />
                Plain Text
            </label>
            <label class="radio" for="hipchat_message_format_html">
                <input id="hipchat_message_format_html" type="radio" name="action.hipchat.param.message_format" value="html" />
                HTML
            </label>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_color">Background Color</label>

        <div class="controls">
            <select id="hipchat_color" name="action.hipchat.param.color">
                <option value="">None</option>
                <option value="red">Red</option>
                <option value="green">Green</option>
                <option value="blue">Blue</option>
                <option value="grey">Grey</option>
            </select>
            <span class="help-block">Change the background of the hipchat message.</span>
        </div>
    </div>
    <div class="control-group">
        <div class="controls">
            <label class="checkbox" for="hipchat_notify">
                <input type="checkbox" name="action.hipchat.param.notify" id="hipchat_notify" value="1"/>
                Notify users in the room
            </label>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_auth_token">Auth Token</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.auth_token" id="hipchat_auth_token" placeholder="Optional"/>
            <span class="help-block">Override the globally configured HipChat Auth Token for this alert.</span>
        </div>
    </div>
</form>
PREVIOUS
Logger example for custom alert actions
  NEXT
Advanced options for working with custom alert actions

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.6.0, 6.6.1, 6.6.2


Comments

Hi Garethatiag,
Thanks for your comment and for noticing the typo. I've updated the text to fix this issue.
All best!

Frobinson splunk, Splunker
February 26, 2016

Just below "alert_action.conf.spec describes custom settings for the custom alert action. These settings are used across all instances."

$SPLUNK_HOME$/etc/apps/hipchat_app/README/alert_actions.conf

The above should read alert_actions.conf.spec (not alert_actions.conf)

Garethatiag
February 25, 2016

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters