This Python package provides an alternative Sensu Go handler for communicating with PagerDuty. Originally authored under the auspices of my day job at DigitalOcean and released as open source with their gracious permission.
While there is a handler released by the good folks at Sensu, there was one piece of functionality it did not have that I needed. Specifically, I had the need to be able to customize the data structure that is sent to PagerDuty in the customer details section of an incident.
I want to be clear that this handler is far inferior to the one provided and that unless you have the same specific need that I have, you are almost definitely better off using theirs instead.
usage: sensu_handler_pagerduty_alternative.py [-h] [-k DEDUP_KEY] [-d DETAILS] [-S SUMMARY]
[--source SOURCE] [-s {0,1,2}] -t TOKEN
sensu-go handler for sending data to pagerduty
optional arguments:
-h, --help show this help message and exit
-k DEDUP_KEY, --dedup-key DEDUP_KEY
String to use to identify the alert, for deduplication purposes. Can be
set with PAGERDUTY_DEDUP_KEY env var. Defaults to
"{namespace}_{host}_{check name}".
-d DETAILS, --details DETAILS
String of details to send - will attempt to convert from json. Can be set
with PAGERDUTY_DETAILS env var. Defaults to full event data.
-S SUMMARY, --summary SUMMARY
String for alert summary. Can be set with PAGERDUTY_SUMMARY env var.
Defaults to "{namespace/{entity name}/{check name} : {check output}"
--source SOURCE Define the 'source' field for the alert, to indicate where this alert is
coming from. Can be set with PAGERDUTY_SOURCE env var. Defaults to the
local host's FQDN
-s {0,1,2}, --status {0,1,2}
Status of the check. Can be set with PAGERDUTY_STATUS env var. Defaults to
value of check status. Valid values: 0 (Ok), 1 (Warning), 2 (Critical)
-t TOKEN, --token TOKEN
The authentication token. Can be set with PAGERDUTY_TOKEN env var.
The deduplication key, unlike the official handler, does not accept a template string and no interpolation will be performed on the value. A simple string can be passed in. If none is defined, the environment variable PAGERDUTY_DEDUP_KEY will be looked at for a value. If that is also unavailable/unset, a dedup key will be generated by looking at the event data and combining the values of the {entity namespace}/{entity name}/{check name} fields.
The incident summary (only relevant for incident creation), much like the Deduplication key field, supports only a non-template string value. If none is defined, the environment variable PAGERDUTY_SUMMARY will be sourced for a value. If this is also unavailable, the default value will be generated from the event data, by combining {entity namespace}/{entity name}/{check name} and the {check output}.
The source field defined for the alert is a simple, non-templated string, as with the Deduplication key field. If none is defined, the environment variable PAGERDUTY_SOURCE will be examined for a value. If this is also unavailable, the default value will be generated by looking up the FQDN of the host executing the handler.
This field allows one to explicitly define the status of the check for the handler, overriding the value defined in the event. In the case of a Warning (1) or Critical (2), an incident will be triggered whereas a value of Ok (0) will trigger a resolve of an incident. If this field is not defined, the handler will read the value from the event data in the {check status} field.
The function of this field is largely the driver for the creation of this module. The desire was to be able to provide a customized data structure to PagerDuty. This field supports several options:
- A normal string. Example:
This is some text that matters to me. - A string that is JSON encoded (it will be decoded to be sent to PagerDuty ). Example:
"{\"field\": \"value\", \"something\": \"else\"}" - A very simplified template reference. Example:
"{{ .check.metadata.annotations }}"
Option 1 is as described, a simple string value.
Option 2 is similar except that if the string value that is provided is a JSON encoded data structure, the handler will attempt to decode it and use the resulting data structure.
Option 3 is a VERY simplified version of the templating employed by the original handler. This allows the value to contain a single reference to a field within the event data structure.
At this time, this plugin is NOT yet available as a Sensu asset. It is recommended to be installed using a local virtualenv.
type: Handler
api_version: core/v2
metadata:
name: pagerduty
namespace: default
spec:
type: pipe
command: >-
/path/to/pd-handler.py
--token "<token_value>"
--details "{{ .check.metadata.annotations }}"
filters:
- is_incident
timeout: 10
Much like the original handler, this handler allows most fields to be defined via environment variables rather than commandline arguments. A commandline argument will override these values though.
| Argument | Environment Variable |
|---|---|
| --dedup-key | PAGERDUTY_DEDUP_KEY |
| --details | PAGERDUTY_DETAILS |
| --source | PAGERDUTY_SOURCE |
| --status | PAGERDUTY_STATUS |
| --summary | PAGERDUTY_SUMMARY |
| --token | PAGERDUTY_TOKEN |