Send Slack alerts with handlers

Sensu event handlers are actions the Sensu backend executes on events. You can use handlers to send an email alert, create or resolve incidents (in PagerDuty, for example), or store metrics in a time-series database like InfluxDB.

This guide will help you send alerts to Slack in the channel monitoring by configuring a handler named slack to a check named check-cpu. If you don’t already have a check in place, Monitor server resources is a great place to start.

Register the asset

Assets are shareable, reusable packages that help you deploy Sensu plugins. In this guide, you’ll use the Sensu Slack Handler asset to power a slack handler.

Use sensuctl asset add to register the Sensu Slack Handler asset:

sensuctl asset add sensu/sensu-slack-handler:1.0.3 -r sensu-slack-handler
fetching bonsai asset: sensu/sensu-slack-handler:1.0.3
added asset: sensu/sensu-slack-handler:1.0.3

You have successfully added the Sensu asset resource, but the asset will not get downloaded until
it's invoked by another Sensu resource (ex. check). To add this runtime asset to the appropriate
resource, populate the "runtime_assets" field with ["sensu-slack-handler"].

This example uses the -r (rename) flag to specify a shorter name for the asset: sensu-slack-handler.

You can also download the latest asset definition for your platform from Bonsai and register the asset with sensuctl create --file filename.yml.

You should see a confirmation message from sensuctl:

Created

NOTE: Sensu does not download and install asset builds onto the system until they are needed for command execution. Read the asset reference for more information about asset builds.

Get a Slack webhook

If you’re already the admin of a Slack, visit https://YOUR WORKSPACE NAME HERE.slack.com/services/new/incoming-webhook and follow the steps to add the Incoming WebHooks integration, choose a channel, and save the settings. If you’re not yet a Slack admin, create a new workspace. After saving, you’ll see your webhook URL under Integration Settings.

Create a handler

Use sensuctl to create a handler called slack that pipes event data to Slack using the sensu-slack-handler asset. Edit the command below to include your Slack channel and webhook URL. For more information about customizing your Sensu slack alerts, see the asset page in Bonsai.

sensuctl handler create slack \
--type pipe \
--env-vars "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T0000/B000/XXXXXXXX" \
--command "sensu-slack-handler --channel '#monitoring'" \
--runtime-assets sensu-slack-handler

You should see a confirmation message from sensuctl:

Created

Assign the handler to a check

With the slack handler created, you can assign it to a check. In this case, you’re using the check-cpu check: you want to receive Slack alerts whenever the CPU usage of your systems reach some specific thresholds. Assign your handler to the check check-cpu:

sensuctl check set-handlers check-cpu slack

Validate the handler

It might take a few moments after you assign the handler to the check for the check to be scheduled on the entities and the result sent back to Sensu backend. After an event is handled, you should see the following message in Slack:

Example Slack message

Verify the proper behavior of this handler with sensu-backend logs. See Troubleshooting for log locations by platform.

Whenever an event is being handled, a log entry is added with the message "handler":"slack","level":"debug","msg":"sending event to handler", followed by a second log entry with the message "msg":"pipelined executed event pipe handler","output":"","status":0.

Next steps

Now that you know how to apply a handler to a check and take action on events, read the handlers reference for in-depth handler documentation and check out the Reduce alert fatigue guide.

You can also try our interactive tutorial and learn how to send Sensu Go alerts to your PagerDuty account.