When to use a mutator

Many Sensu event handlers will modify event data in the course of
processing an event, and in many cases this is recommended because
modifying the event data and performing some action in memory (in the same
process) will result in better performance than executing a mutatorand a
handler (two separate processes). However, when multiple handlers require
similar event data modifications, mutators provide the ability to avoid code
duplication (DRY), and simplify
event handler logic.

How do Sensu mutators work?

Sensu mutators are applied when event handlers are configured to use a
mutator. Prior to executing a Handler, the Sensu server will execute the
configured mutator. If the mutator is successfully executed, the modified
event data is then provided to the handler and the handler will be executed. If
the mutator fails to execute for any reason, an error will be logged and the
handler will not be executed. The complete process may be described as follows:

When the Sensu server is processing an event, it will check for the definition
of a mutator. Prior to executing each handler, the Sensu server will first
execute the configured mutator (if any) for the handler

If the mutator is successfully executed (i.e. if it returns an exit status
code of 0), the modified event data is provided to the handler and the
handler will be executed.

If the mutator fails to execute (i.e. returns a non-zero exit status code, or
does not complete execution within the configured timeout), an error will be
logged and the handler will not be executed

Mutator command arguments

Sensu mutator command attributes may include command line arguments for
controlling the behavior of the command executable. Many Sensu mutator
plugins provide support for command line arguments for reusability.

How and where are mutator commands executed?

As mentioned above, all mutator commands 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;

e.g.: "command": "check-http.rb -u https://sensuapp.org"

Mutator configuration

Example mutator definition

The following is an example Sensu mutator definition, a JSON configuration file
located at /etc/sensu/conf.d/example_mutator.json. This mutator definition
uses an imaginary Sensu plugin called example_mutator.rb to modify event
data prior to handling the event.

{"mutators":{"example_mutator":{"command":"example_mutator.rb"}}}

Mutator definition specification

Mutator name(s)

Each mutator definition has a unique mutator name, used for the definition key.
Every mutator definition is within the "mutators": {} definition scope.

Mutator attributes

The mutator command to be executed. The event data is passed to the process via STDIN.

required

true

type

String

example

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

timeout

description

The mutator execution duration timeout in seconds (hard stop).

required

false

type

Integer

example

"timeout": 30

About Sensu

The Sensu monitoring event pipeline empowers businesses to automate their monitoring workflows and gain deep visibility into their multi-cloud infrastructure, from Kubernetes to bare metal. Companies like Sony, Box.com, and Activision rely on Sensu to help deliver value faster, at scale.