Mutators reference
Sensu executes mutators during the transform stage of the observability pipeline.
Handlers can specify a mutator to execute and transform observability event data before any handlers are applied. When the Sensu backend processes an event, it checks the handler for the presence of a mutator and executes that mutator before executing the handler.
Mutators produce an exit status code to indicate state.
A code of 0
indicates OK status.
If the mutator executes successfully (returns an exit status code of 0
), the modified event data return to the handler and the handler is executed.
Exit codes other than 0
indicate failure.
If the mutator fails to execute (returns a non-zero exit status code or fails to complete within its configured timeout), an error is logged and the handler will not execute.
Mutators accept input/data via STDIN
and can parse JSON event data.
They output JSON data (modified event data) to STDOUT
or STDERR
.
Mutator examples
This example shows a mutator resource definition with the minimum required attributes:
type: Mutator
api_version: core/v2
metadata:
name: mutator_minimum
namespace: default
spec:
command: example_mutator.go
{
"type": "Mutator",
"api_version": "core/v2",
"metadata": {
"name": "mutator_minimum",
"namespace": "default"
},
"spec": {
"command": "example_mutator.go"
}
}
The following mutator definition uses an imaginary Sensu plugin, example_mutator.go
, to modify event data prior to handling the event:
---
type: Mutator
api_version: core/v2
metadata:
annotations: null
labels: null
name: example-mutator
namespace: default
spec:
command: example_mutator.go
env_vars: []
runtime_assets: []
timeout: 0
{
"type": "Mutator",
"api_version": "core/v2",
"metadata": {
"name": "example-mutator",
"namespace": "default",
"labels": null,
"annotations": null
},
"spec": {
"command": "example_mutator.go",
"timeout": 0,
"env_vars": [],
"runtime_assets": []
}
}
Commands
Each Sensu mutator definition defines a command to be executed.
Mutator commands are executable commands that will be executed on a Sensu backend, run as the sensu user
.
Most mutator commands are provided by Sensu plugins.
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.
All mutator commands are executed by a Sensu backend as the sensu
user.
Commands must be executable files that are discoverable on the Sensu backend system (installed in a system $PATH
directory).
NOTE: By default, Sensu installer packages will modify the system $PATH
for the Sensu processes to include /etc/sensu/plugins
.
As a result, executable scripts (like plugins) located in /etc/sensu/plugins
will be valid commands.
This allows command
attributes to use “relative paths” for Sensu plugin commands (for example, "command": "check-http.go -u https://sensuapp.org"
).
Built-in mutators
Sensu includes built-in mutators to help you customize event pipelines for metrics and alerts.
Built-in mutator: only_check_output
To process an event, some handlers require only the check output, not the entire event definition.
For example, when sending metrics to Graphite using a TCP handler, Graphite expects data that follows the Graphite plaintext protocol.
By using the built-in only_check_output
mutator, Sensu reduces the event to only the check output so Graphite can accept it.
To use only check output, include the only_check_output
mutator in the handler configuration mutator
string:
---
type: Handler
api_version: core/v2
metadata:
name: graphite
namespace: default
spec:
mutator: only_check_output
socket:
host: 10.0.1.99
port: 2003
type: tcp
{
"type": "Handler",
"api_version": "core/v2",
"metadata": {
"name": "graphite",
"namespace": "default"
},
"spec": {
"type": "tcp",
"socket": {
"host": "10.0.1.99",
"port": 2003
},
"mutator": "only_check_output"
}
}
Mutator specification
Top-level attributes
type | |
---|---|
description | Top-level attribute that specifies the sensuctl create resource type. Mutators should always be type Mutator . |
required | Required for mutator definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For mutators in this version of Sensu, the api_version should always be core/v2 . |
required | Required for mutator definitions in wrapped-json or yaml format for use with sensuctl create . |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of metadata about the mutator that includes name , namespace , and created_by as well as custom labels and annotations . The metadata map is always at the top level of the mutator definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See the metadata attributes reference for details. |
required | Required for mutator definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the mutator spec attributes. |
required | Required for mutator definitions in wrapped-json or yaml format for use with sensuctl create . |
type | Map of key-value pairs |
example |
|
Metadata attributes
name | |
---|---|
description | Unique string used to identify the mutator. Mutator names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z ). Each mutator must have a unique name within its namespace. |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the mutator belongs to. |
required | false |
type | String |
default | default |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created the mutator or last updated the mutator. Sensu automatically populates the created_by field when the mutator is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with event data that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
annotations | |
---|---|
description | Non-identifying metadata to include with event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
Spec attributes
command | |
---|---|
description | Mutator command to be executed by the Sensu backend. |
required | true |
type | String |
example |
|
timeout | |
---|---|
description | Mutator execution duration timeout (hard stop). In seconds. |
required | false |
type | integer |
example |
|
env_vars | |
---|---|
description | Array of environment variables to use with command execution. |
required | false |
type | Array |
example |
|
runtime_assets | |
---|---|
description | Array of Sensu dynamic runtime assets (by their names) required at runtime for execution of the command . |
required | false |
type | Array |
example |
|
secrets | |
---|---|
description | Array of the name/secret pairs to use with command execution. |
required | false |
type | Array |
example |
|
secrets
attributes
name | |
---|---|
description | Name of the secret defined in the executable command. Becomes the environment variable presented to the mutator. See Use secrets management in Sensu for more information. |
required | true |
type | String |
example |
|
secret | |
---|---|
description | Name of the Sensu secret resource that defines how to retrieve the secret. |
required | true |
type | String |
example |
|
Mutator that uses secrets management
Learn more about secrets management for your Sensu configuration in the secrets and secrets providers references.
---
type: Mutator
api_version: core/v2
metadata:
name: ansible-tower
namespace: ops
spec:
command: sensu-ansible-mutator -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN
secrets:
- name: ANSIBLE_HOST
secret: sensu-ansible-host
- name: ANSIBLE_TOKEN
secret: sensu-ansible-token
{
"type": "Mutator",
"api_version": "core/v2",
"metadata": {
"name": "ansible-tower",
"namespace": "ops"
},
"spec": {
"command": "sensu-ansible-mutator -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN",
"secrets": [
{
"name": "ANSIBLE_HOST",
"secret": "sensu-ansible-host"
},
{
"name": "ANSIBLE_TOKEN",
"secret": "sensu-ansible-token"
}
]
}
}