Sensu BigPanda Handler

Table of Contents

• Overview
• Usage examples
  • Help output
  • Environment variables
  • Templates
  • Annotations
• Configuration
  • Asset registration
  • Handler definition
  • Check definition
• Local testing and troubleshooting
• Installation from source and contributing

Overview

The Sensu BigPanda Handler is a Sensu Event Handler that sends alerts to
the BigPanda service.

Sensu Event to BigPand Alert Attribute translation

The common BigPanda alerts attributes are filled using the following rules:

Extended Sensu Event to BigPanda Alert Attribute Translation

The BigPanda alert allows for custom attributes. This handler uses this feature to extend BigPanda alerts with sensu event contextual information:

Usage examples

Help output

Sensu Handler to send alerts to BigPanda

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

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

Flags:
  -t, --token string                         BigPanda API Authentication Token - Required. Note for security using BIGPANDA_TOKEN environment variable is preferred
  -a, --appkey string                        BigPanda API App Key - Required . Note for security using BIGPANDA_APPKEY environment variable is preferred
  -c, --custom-tags strings                  Comma separated list of tags to add using 'tag_name: tag_value'  format
  -d, --description-template string          The BigPanda alert description template, in Golang text/template format (default "{{ .Check.Output }}")
  -p, --primary-property string              The BigPanda alert primary property (default "host")
  -s, --secondary-property string            The BigPanda alert secondary property (default "check")
  -S, --status string                        The BigPanda alert status, overrides check status
  -u, --url string                           The BigPanda alert API URL (default "https://api.bigpanda.io/data/v2/alerts")
  -v, --verbose                              Enable verbose output
  -n, --dry-run                              Dry run, do not contact BigPanda. For testing only, implies --verbose
  -h, --help                                 help for sensu-bigpanda-handler

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

Note: You must generate both an http authentication token and app key via the Big Panda service by following the steps to enable a new webhook integration for the Alert API.

Environment variables

Security Note: Care should be taken to not expose the token/appkey authentication
credentials for this handler by specifying them 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 these as
an environment variables. The handler definition referenced here uses secrets for the authentication credentials.
Below is an example secrets definition that make use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: bigpanda_token
spec:
  provider: env
  id: BIGPANDA_TOKEN
---
type: Secret
api_version: secrets/v1
metadata:
  name: bigpanda_appkey
spec:
  provider: env
  id: BIGPANDA_APPKEY

Templates

This handler provides options for using GoLang templates to optionally populate several BigPanda alert attributes.
For example, by default the alert description is populated using a template to extract the Sensu checkout output.
Similarly the primary property, secondary property and status attributes can also use templates if required.
More information on template syntax and format can be found in the documentation

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/bigpanda/config.

NOTE: Due to check token substituion, supplying a template value such
as for description-template as a check annotation requires that you place the
desired template as a golang string literal (enlcosed in backticks)
within another template definition. This does not apply to entity annotations.

Examples

To customize the custom tags for a specific entity, you could use the following
sensu-agent configuration snippet:

# /etc/sensu/agent.yml example
annotations:
  sensu.io/plugins/bigpanda/config/custom-tags: 'enviroment: testing, application: infinidash'

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 sensu/sensu-bigpanda-handler

If you're using an earlier version of sensuctl, you can find the asset on the [Bonsai Asset Index][https://bonsai.sensu.io/assets/sensu/sensu-bigpanda-handler].

Handler definition

---
api_version: core/v2
type: Handler
metadata:
  namespace: default
  name: bigpanda
spec:
  type: pipe
  command: sensu-bigpanda-handler 
  filters:
  - is_incident
  runtime_assets:
  - sensu/sensu-bigpanda-handler
  secrets:
  - name: BIGPANDA_TOKEN
    secret: bigpanda_token
  - name: BIGPANDA_APPKEY
    secret: bigpanda_appkey
  timeout: 10

Security Note: The BigPanda authentication credentials token/appkey
should always be treated as a security sensitive configuration options and in this example,
they are loaded into the handler configuration as an environment variable using a secret.
Command arguments are commonly readable from the process table by other unprivaledged
users on a system (ex: ps and top commands), so it's a better practise to read
in sensitive information via environment variables or configuration files on
disk. The cmdline argument flags for credentials are provided as overrides for testing purposes.

Check definition

api_version: core/v2
type: CheckConfig
metadata:
  namespace: default
  name: dummy-app-healthz
spec:
  command: check-http -u http://localhost:8080/healthz
  subscriptions:
  - dummy
  publish: true
  interval: 10
  handlers:
  - bigpanda

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.

Local testing and troubleshooting

Before deploying as a handler in your Sensu environment, you can optionally test for correct functionality using the handler executable locally in your development environemnt.
First download and unpack the appropriate asset tarball for the development host and change into the 'bin/' of the unpacked tarball.

You can test by sending an event into stdin of the executable using sensuctl:

sensuctl event info <ENTITY_NAME> <CHECK_NAME> --format json | ./sensu-bigpanda-handler --token <TOKEN> --appkey <APPKEY> --dry-run

The --dry-run argument will prevent the executable from contacting the bigpanda api and will instead report back intended api communication. Remove the --dry-run option to send the msg to the BigPand api.

Installation from source

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

Compiling

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

go build

Additional notes

Contributing

To contribute to this plugin, see CONTRIBUTING