Mutators
Reference documentation
What are Sensu mutators?
Sensu mutators are executable scripts or other programs that modify event data for Sensu event handlers which may expect additional or modified event data (e.g. custom attributes that are not provided by the default event data specification.
The Sensu mutator specification
- Accept input/data via
STDIN
- Able to parse a JSON data payload (i.e. a event data)
- Output JSON data (the modified event data) to
STDOUT
orSTDERR
- Produce an exit status code to indicate state:
0
indicates OK- exit status codes other than
0
indicates a failure
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 mutator and 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 configuredmutator
(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
Please refer to the Sensu event handler definition specification for more
information about applying a mutator to an event handler (see the mutator
attribute).
Mutator commands
What is a mutator command?
Each Sensu mutator definition defines a command to be executed. Mutator
commands are literally executable commands which will be executed on a Sensu
server, run as the sensu
user. Most mutator commands are provided by
Sensu plugins.
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.
- A unique string used to name/identify the mutator
- Cannot contain special characters or spaces
- Validated with Ruby regex
/^[\w\.-]+$/.match("mutator-name")
Mutator attributes
command | |
---|---|
description | The mutator command to be executed. The event data is passed to the process via STDIN . |
required | true |
type | String |
example |
|
timeout | |
---|---|
description | The mutator execution duration timeout in seconds (hard stop). |
required | false |
type | Integer |
example |
|