Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name


v0.1.3 · public · Published 15 days ago

README
Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset
goreleaser
Go Test
goreleaser

Sensu BigPanda Handler

Table of Contents

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:

Required BigPanda Alert Attributes Description
host sensu event entity name
check sensu event check name
cluster sensu event namespace
timestamp sensu event timestamp
status sensu event check state mapped into BigPanda status ("ok","warning","critical","unknown")
primary_property default to "host" settable via cmdline argument
secondary_property default to "check" settable via cmdline argument
description filled using golang template defaults to event check output, settable via cmdline argument

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:

Extended BigPanda Alert Attributes Sensu Event Attribute
sensu.event.labels. event labels
sensu.event.attributes. event attributes
sensu.event.entity.labels. event entity labels
sensu.event.entity.attributes. event entity attributes
sensu.event.check.labels. event check labels
sensu.event.check.attributes. event check Attributes
sensu.event.check.occurrences event check occurrences count
sensu.event.check.state event check state ("passing", "failing", "flapping"")
sensu.event.check.status event check status (0-254)
sensu.event.check.subscriptions comma separated list of event check subscriptions
sensu.event.entity.system.arch event entity system arch
sensu.event.entity.system.cloud_provider event entity system cloud_provider
sensu.event.entity.system.hostname event entity system hostname
sensu.event.entity.system.os event entity system os
sensu.event.entity.system.platform event entity system platform
sensu.event.entity.system.platform_family event entity system platform_family
sensu.event.entity.system.platform_version event entity system platform version
sensu.event.entity.system.vm_role event entity system vm_role
sensu.event.entity.system.vm_system event entity system vm_version
sensu.event.id event id

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

Argument Environment Variable
--token BIGPANDA_TOKEN
--appkey BIGPANDA_APPKEY
--url BIGPANDA_URL
--status BIGPANDA_STATUS
--description-template BIGPANDA_DESCRIPTION_TEMPLATE
--primary-property BIGPANDA_PRIMARY_PROPERTY
--secondary-property BIGPANDA_SECONDARY_PROPERTY
--custom-tags BIGPANDA_CUSTOM_TAGS

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

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.

×

You must be signed in to report this asset.

Sign In with Github

Download

×

This asset is enterprise only and requires an enterprise license. By clicking download, you agree to the Sensu terms and conditions and license agreement.