What is a Sensu event handler?

Sensu event handlers are actions executed by the Sensu server on
events, such as sending an email alert, creating or resolving an incident
(e.g. in PagerDuty, ServiceNow, etc), or storing metrics in a time-series
database (e.g. Graphite).

Handler types

There are several types of handlers. The most common handler type is the pipe
handler, which works very similarly to how checks work, enabling Sensu to
interact with almost any computer program via standard streams.

Handler sets. Handler sets (also called “set handlers”) are used to group
event handlers, making it easy to manage groups of actions that should be
executed for certain types of events.

The default handler

Sensu expects all events to have a corresponding handler. Event handler(s)
may be configured in check definitions, however if no handler or
handlers have been configured, Sensu will attempt to handle the event using a
handler nameddefault. The default handler is only a reference
(i.e. Sensu does not provide a built-in default handler), so if no handler
definition exists for a handler named default, Sensu will log an error
indicating that the event was not handled because a default handler definition
does not exist. To use one or more existing handlers as the default, you can
create a Set handler called default and include the existing handler(s)
in the set.

Example pipe handler definition

Pipe handler commands

What is a pipe handler command?

Pipe handler definitions include a command attribute which are literally
executable commands which will be executed on a Sensu server as the sensu
user.

Pipe handler command arguments

Pipe handler command attributes may include command line arguments for
controlling the behavior of the command executable. Most Sensu handler
plugins provide support for command line arguments for reusability.

How and where are pipe handler commands executed?

As mentioned above, all pipe handlers are executed by a Sensu server as the
sensu user. Commands must be executable files that are discoverable on the
Sensu server system (i.e. installed in a system $PATH directory).

NOTE: By default, the Sensu installer packages will modify the system $PATH
for the Sensu processes to include /etc/sensu/plugins. As a result, executable
scripts (e.g. plugins) located in /etc/sensu/plugins will be valid commands.
This allows command attributes to use “relative paths” for Sensu plugin
commands;

Transport handlers

Transport handlers enable Sensu to publish event data to named queues on the
Sensu transport for external services to consume.

Example transport handler definition

The following example transport handler definition will publish event data
to the Sensu transport on a pipe (e.g. a “queue” or “channel”, etc) named
example_handler_queue. One or more instances of an external process or
third-party application would need to subscribe to the named pipe to process the
events.

Handler configuration

Example handler definition

The following is an example Sensu handler definition, a JSON configuration file
located at /etc/sensu/conf.d/mail_handler.json. This handler definition uses
the mailx unix command, to email the event data to example@address.com, with
the email subject sensu event. The handler is named mail.

The Sensu event filter (name) to use when filtering events for the handler.

required

false

type

String

example

"filter": "recurrence"

filters

description

An array of Sensu event filters (names) to use when filtering events for the
handler. Each array item must be a string.

required

false

type

Array

example

"filters": ["recurrence", "production"]

severities

description

An array of check result severities the handler will handle.
NOTE: event resolution bypasses this filtering.

required

false

type

Array

allowed values

warning, critical, unknown

example

"severities": ["critical", "unknown"]

mutator

description

The Sensu event mutator (name) to use to mutate event data for the handler.

required

false

type

String

example

"mutator": "only_check_output"

timeout

description

The handler execution duration timeout in seconds (hard stop). Only used by
pipe and tcp handler types.

required

false

type

Integer

default

10

example

"timeout": 30

handle_silenced

description

If events matching one or more silence entries should be handled.

required

false

type

Boolean

default

false

example

"handle_silenced": true

handle_flapping

description

If events in the flapping state should be handled.

required

false

type

Boolean

default

false

example

"handle_flapping": true

command

description

The handler command to be executed. The event data is passed to the process
via STDIN.
NOTE: the command attribute is only supported for Pipe handlers (i.e.
handlers configured with "type": "pipe").

required

true (if type == pipe)

type

String

example

"command": "/etc/sensu/plugins/pagerduty.rb"

socket

description

The socket definition scope, used to configure the TCP/UDP handler
socket.
NOTE: the socket attribute is only supported for TCP/UDP handlers (i.e.
handlers configured with "type": "tcp" or "type": "udp").

required

true (if type == tcp or udp)

type

Hash

example

"socket": {}

pipe

description

The pipe definition scope, used to configure the Sensu transport
pipe.
NOTE: the pipe attribute is only supported for Transport handlers (i.e.
handlers configured with "type": "transport").

required

true (if type == transport)

type

Hash

example

"pipe": {}

handlers

description

An array of Sensu event handlers (names) to use for events using the handler
set. Each array item must be a string.
NOTE: the handlers attribute is only supported for handler sets (i.e.
handlers configured with "type": "set").

Newsletter

Subscribe to the newsletter to get product updates about Sensu, including notifications when new releases are available. No more than one email per week, no less than one email per month. #monitoringlove.