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 
type: Mutator
{
  "type": "Mutator"
}
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 
api_version: core/v2
{
  "api_version": "core/v2"
}
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 
metadata:
  name: example-mutator
  namespace: default
  created_by: admin
  labels:
    region: us-west-1
  annotations:
    slack-channel: "#monitoring"
{
  "metadata": {
    "name": "example-mutator",
    "namespace": "default",
    "created_by": "admin",
    "labels": {
      "region": "us-west-1"
    },
    "annotations": {
      "slack-channel": "#monitoring"
    }
  }
}
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 
spec:
  command: example_mutator.go
  timeout: 0
  env_vars: []
  runtime_assets: []
{
  "spec": {
    "command": "example_mutator.go",
    "timeout": 0,
    "env_vars": [],
    "runtime_assets": []
  }
}

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 
name: example-mutator
{
  "name": "example-mutator"
}
namespace
description Sensu RBAC namespace that the mutator belongs to.
required false
type String
default default
example 
namespace: production
{
  "namespace": "production"
}
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 
created_by: admin
{
  "created_by": "admin"
}
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 
labels:
  environment: development
  region: us-west-2
{
  "labels": {
    "environment": "development",
    "region": "us-west-2"
  }
}
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 
annotations:
  managed-by: ops
  playbook: www.example.url
{
  "annotations": {
    "managed-by": "ops",
    "playbook": "www.example.url"
  }
}

Spec attributes

command
description Mutator command to be executed by the Sensu backend.
required true
type String
example 
command: /etc/sensu/plugins/mutated.go
{
  "command": "/etc/sensu/plugins/mutated.go"
}
timeout
description Mutator execution duration timeout (hard stop). In seconds.
required false
type integer
example 
timeout: 30
{
  "timeout": 30
}
env_vars
description Array of environment variables to use with command execution.
required false
type Array
example 
env_vars:
- RUBY_VERSION=2.5.0
{
  "env_vars": [
    "RUBY_VERSION=2.5.0"
  ]
}
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 
runtime_assets:
- ruby-2.5.0
{
  "runtime_assets": [
    "ruby-2.5.0"
  ]
}
secrets
description Array of the name/secret pairs to use with command execution.
required false
type Array
example 
secrets:
- name: ANSIBLE_HOST
  secret: sensu-ansible-host
- name: ANSIBLE_TOKEN
  secret: sensu-ansible-token
{
  "secrets": [
    {
      "name": "ANSIBLE_HOST",
      "secret": "sensu-ansible-host"
    },
    {
      "name": "ANSIBLE_TOKEN",
      "secret": "sensu-ansible-token"
    }
  ]
}

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 
name: ANSIBLE_HOST
{
  "name": "ANSIBLE_HOST"
}
secret
description Name of the Sensu secret resource that defines how to retrieve the secret.
required true
type String
example 
secret: sensu-ansible-host
{
  "secret": "sensu-ansible-host"
}

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"
      }
    ]
  }
}