
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
This script has been made cross-compatible with Python 2 and Python 3 using python-future.
$SPLUNK_HOME$/etc/apps/hipchat_app/bin/hipchat.py
from __future__ import print_function from future import standard_library standard_library.install_aliases() import sys, json, urllib.request, urllib.error, urllib.parse def send_message(settings): print("DEBUG Sending message with settings %s" % settings, file=sys.stderr) room = settings.get('room') auth_token = settings.get('auth_token') base_url = settings.get('base_url').rstrip('/') fmt = settings.get('format', 'text') print("INFO Sending message to hipchat room=%s with format=%s" % (room, fmt), file=sys.stderr) url = "%s/room/%s/notification?auth_token=%s" % ( base_url, urllib.parse.quote(room), urllib.parse.quote(auth_token) ) body = json.dumps(dict( message=settings.get('message'), message_format=fmt, color=settings.get('color', "green") )) print('DEBUG Calling url="%s" with body=%s' % (url, body), file=sys.stderr) req = urllib.request.Request(url, body, {"Content-Type": "application/json"}) try: res = urllib.request.urlopen(req) body = res.read() print("INFO HipChat server responded with HTTP status=%d" % res.code, file=sys.stderr) print("DEBUG HipChat server response: %s" % json.dumps(body), file=sys.stderr) return 200 <= res.code < 300 except urllib.error.HTTPError as e: print("ERROR Error sending message: %s" % e, file=sys.stderr) 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("FATAL Failed trying to send room notification", file=sys.stderr) sys.exit(2) else: print("INFO Room notification successfully sent", file=sys.stderr) else: print("FATAL Unsupported execution mode (expected --execute flag)", file=sys.stderr) 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
- Note: The HipChat example does not override the
alert.execute.cmd
command. For more details, see Override a script with alert.execute.cmd.
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.5.7, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.8, 7.1.7, 7.0.0, 7.3.7, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 7.3.9, 8.0.0, 8.0.1
Feedback submitted, thanks!