Sensu Go OpsGenie Handler

Table of Contents

• Overview
• Usage examples
  • Help output
  • Templates
  • To use Opsgenie Priority
  • To use alert actions
• Configuration
  • Asset registration
  • Handler definition
  • Environment variables
  • Argument annotations
  • Proxy support
• Installation from source
• Contributing

Overview

The Sensu Go OpsGenie Handler is a Sensu Event Handler which manages OpsGenie incidents, for alerting operators. With this handler, Sensu can trigger OpsGenie incidents.

To configure OpsGenie Sensu Integration follow these first part in OpsGenie Docs.

This handler was inspired by pagerduty plugin.

Usage examples

Help output

Help:

The Sensu Go OpsGenie handler for incident management

Usage:
  sensu-opsgenie-handler [flags]
  sensu-opsgenie-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -a, --auth string                  The OpsGenie V2 API authentication token, use default from OPSGENIE_AUTHTOKEN env var
  -t, --team string                  The OpsGenie V2 API Team, use default from OPSGENIE_TEAM env var
  -r, --region string                The OpsGenie API Region (us or eu), use default from OPSGENIE_REGION env var (default "us")
  -p, --priority string              The OpsGenie Alert Priority, use default from OPSGENIE_PRIORITY env var (default "P3")
  -A, --actions strings              The OpsGenie custom actions to assign to the event
  -d, --descriptionTemplate string   The template for the description to be sent (default "{{.Check.Output}}")
  -L, --descriptionLimit int         The maximum length of the description field (default 15000)
  -m, --messageTemplate string       The template for the message to be sent (default "{{.Entity.Name}}/{{.Check.Name}}")
  -l, --messageLimit int             The maximum length of the message field (default 130)
  -i, --includeEventInNote           Include the event JSON in the payload sent to OpsGenie
  -F, --fullDetails                  Include the more details to send to OpsGenie like proxy_entity_name, occurrences and agent details arch and os
  -w, --withAnnotations              Include the event.metadata.Annotations in details to send to OpsGenie
  -W, --withLabels                   Include the event.metadata.Labels in details to send to OpsGenie
  -T, --tagTemplate strings          The template to assign for the incident in OpsGenie (default [{{.Entity.Name}},{{.Check.Name}},{{.Entity.Namespace}},{{.Entity.EntityClass}}])
  -s, --sensuDashboard string        The OpsGenie Handler will use it to create a source Sensu Dashboard URL. Use OPSGENIE_SENSU_DASHBOARD. Example: http://sensu-dashboard.example.local/c/~/n
  -h, --help                         help for sensu-opsgenie-handler

Use "sensu-opsgenie-handler [command] --help" for more information about a command.

Templates

This handler provides options for using templates to populate various fields in the OpsGenie alert with values provided in the Sensu event. More information on template syntax and format can be found in the documentation

To use Opsgenie Priority

Use the --priority command-line option to specify a default priority and then use check and/or entity annotations to override the default on a per-check or per-entity basis. See Argument Annotations for more information.

To use alert actions

Use the --actions command-line option to specify alert actions to be triggered by an event. The argument for this option is a comma separated list of actions. Use check and/or entity annotations to set this option on a per-check or per-entity basis. See Argument Annotations for more information.

Configuration

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not using an asset, please consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the following command to add the asset:

sensuctl asset add nixwiz/sensu-opsgenie-handler

If you're using an earlier version of sensuctl, you can find the asset on the Bonsai Asset Index.

Handler definition

type: Handler
api_version: core/v2
metadata:
  name: opsgenie
  namespace: default
spec:
  type: pipe
  command: sensu-opsgenie-handler
  env_vars:
  - OPSGENIE_TEAM=TEAM_NAME
  - OPSGENIE_APIURL=https://api.opsgenie.com
  timeout: 10
  runtime_assets:
  - nixwiz/sensu-opsgenie-handler
  filters:
  - is_incident
  secrets:
  - name: OPSGENIE_AUTHTOKEN
    secret: opgsgenie_authtoken

Environment variables

Most arguments for this handler are available to be set via environment variables. However, any arguments specified directly on the command line override the corresponding environment variable.

Security Note: Care should be taken to not expose the auth token for this handler by specifying it on the command line or by directly setting the environment variable in the handler definition. It is suggested to make use of secrets management to surface it as an environment variable. The handler definition above references it as a secret. Below is an example secrets definition that make use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: opsgenie_authtoken
spec:
  provider: env
  id: OPSGENIE_AUTHTOKEN

Argument annotations

All arguments for this handler are tunable on a per entity or check basis based on annotations. The annotations keyspace for this handler is sensu.io/plugins/sensu-opsgenie-handler/config.

Examples

To change the team argument for a particular check, for that checks's metadata add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/sensu-opsgenie-handler/config/team: WebOps
[...]

Proxy support

This handler supports the use of the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes precedence over HTTP_PROXY for https requests. The environment values may be either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.

Installation from source

Download the latest version of the sensu-opsgenie-handler from releases, or create an executable script from this source.

From the local path of the sensu-opsgenie-handler repository:

go build -o /usr/local/bin/sensu-opsgenie-handler main.go

Contributing

See https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md