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.
• 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.
• 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.

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).

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

Mutators:

• Accept input/data via STDIN
• Can parse JSON event data
• Output JSON data (modified event data) to STDOUT or STDERR
• Produce an exit status code to indicate state:
  • 0 indicates OK status
  • exit codes other than 0 indicate failure

Top-level attributes

"type": "Mutator"

"api_version": "core/v2"

"metadata": {
  "name": "example-mutator",
  "namespace": "default",
  "created_by": "admin",
  "labels": {
    "region": "us-west-1"
  },
  "annotations": {
    "slack-channel" : "#monitoring"
  }
}

"spec": {
  "command": "example_mutator.go",
  "timeout": 0,
  "env_vars": [],
  "runtime_assets": []
}

Metadata attributes

"name": "example-mutator"

"namespace": "production"

"created_by": "admin"

"labels": {
  "environment": "development",
  "region": "us-west-2"
}

 "annotations": {
  "managed-by": "ops",
  "playbook": "www.example.url"
}

Spec attributes

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

"timeout": 30

"env_vars": ["RUBY_VERSION=2.5.0"]

"runtime_assets": ["ruby-2.5.0"]

"secrets": [
  {
    "name": "ANSIBLE_HOST",
    "secret": "sensu-ansible-host"
  },
  {
    "name": "ANSIBLE_TOKEN",
    "secret": "sensu-ansible-token"
  }
]

secrets attributes

"name": "ANSIBLE_HOST"

"secret": "sensu-ansible-host"

Examples

Example mutator definition

The following Sensu 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": []
  }
}

Minimum required mutator 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"
  }
}

Mutator with secret

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