Mutators

• Built-in mutators
• Specification
• Examples

How do mutators work?

A handler can specify a mutator to transform event data. Mutators are executed prior to the execution of a handler. If the mutator executes successfully, the modified event data is returned to the handler, and the handler is then executed. If the mutator fails to execute, an error will be logged, and the handler will not be executed.

• When Sensu server processes an event, it will check the handler for the presence of a mutator, and execute that mutator before executing the handler.
• If the mutator executes successfully (it returns an exit status code of 0), modified event data is provided to the handler, and the handler is executed.
• If the mutator fails to execute (it returns a non-zero exit status code, or fails to complete within its configured timeout), an error will be logged and the handler will not execute.

Mutator specification

• Accepts input/data via STDIN
• Able to parse JSON event data
• Outputs JSON data (modified event data) to STDOUT or STDERR
• Produces an exit status code to indicate state:
  • 0 indicates OK status
  • exit codes other than 0 indicate failure

Commands

Each Sensu mutator definition defines a command to be executed. Mutator commands are executable commands which will be executed on a Sensu server, 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.

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 (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 (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 it can be accepted by Graphite.

To use the only check output mutator, 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"
  }
}

Mutators specification

Top-level attributes

"type": "Mutator"

"api_version": "core/v2"

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

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

Spec attributes

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

"env_vars": ["RUBY_VERSION=2.5.0"]

"timeout": 30

"runtime_assets": ["ruby-2.5.0"]

Metadata attributes

"name": "example-mutator"

"namespace": "production"

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

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

Examples

The following Sensu mutator definition uses an imaginary Sensu plugin called example_mutator.go to modify event data prior to handling the event.

Mutator definition

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