Handlers

Handlers are actions the Sensu backend executes on events. Several types of handlers are available. The most common are pipe handlers, which work similarly to checks and enable Sensu to interact with almost any computer program via standard streams.

  • Pipe handlers send event data into arbitrary commands via STDIN
  • TCP/UDP handlers send event data to a remote socket
  • Handler sets group event handlers and streamline groups of actions to execute for certain types of events (also called “set handlers”)

Discover, download, and share Sensu handlers assets using Bonsai, the Sensu asset index. Read Install plugins with assets to get started.

Pipe handlers

Pipe handlers are external commands that can consume event data via STDIN.

Pipe handler command

Pipe handler definitions include a command attribute, which is a command for the Sensu backend to execute.

Pipe handler command arguments

Pipe handler command attributes may include command line arguments for controlling the behavior of the command executable.

TCP/UDP handlers

TCP and UDP handlers enable Sensu to forward event data to arbitrary TCP or UDP sockets for external services to consume.

Handler sets

Handler set definitions allow you to use a single named handler set to refer to groups of handlers (individual collections of actions to take on event data).

NOTE: Attributes defined on handler sets do not apply to the handlers they include. For example, filters and mutator attributes defined in a handler set will have no effect on handlers.

Keepalive event handlers

Sensu keepalives are the heartbeat mechanism used to ensure that all registered Sensu agents are operational and can reach the Sensu backend. You can connect keepalive events to your monitoring workflows using a keepalive handler. Sensu looks for an event handler named keepalive and automatically uses it to process keepalive events.

Suppose you want to receive Slack notifications for keepalive alerts, and you already have a Slack handler set up to process events. To process keepalive events using the Slack pipeline, create a handler set named keepalive and add the slack handler to the handlers array. The resulting keepalive handler set configuration will look like this example:

type: Handler
api_version: core/v2
metadata:
  name: keepalive
  namespace: default
spec:
  handlers:
  - slack
  type: set
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata" : {
    "name": "keepalive",
    "namespace": "default"
  },
  "spec": {
    "type": "set",
    "handlers": [
      "slack"
    ]
  }
}

You can also use the keepalive-handlers flag to send keepalive events to any handler you have configured. If you do not specify a keepalive handler with the keepalive-handlers flag, the Sensu backend will use the default keepalive handler and create an event in sensuctl and the Sensu web UI.

Handler specification

Top-level attributes

type
description Top-level attribute that specifies the sensuctl create resource type. Handlers should always be type Handler.
required Required for handler definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example
"type": "Handler"
api_version
description Top-level attribute that specifies the Sensu API group and version. For handlers in this version of Sensu, the api_version should always be core/v2.
required Required for handler definitions in wrapped-json or yaml format for use with sensuctl create.
type String
example
"api_version": "core/v2"
metadata
description Top-level collection of metadata about the handler that includes the name and namespace as well as custom labels and annotations. The metadata map is always at the top level of the handler definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope. See metadata attributes for details.
required Required for handler definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example
"metadata": {
  "name": "handler-slack",
  "namespace": "default",
  "labels": {
    "region": "us-west-1"
  },
  "annotations": {
    "slack-channel" : "#monitoring"
  }
}
spec
description Top-level map that includes the handler spec attributes.
required Required for handler definitions in wrapped-json or yaml format for use with sensuctl create.
type Map of key-value pairs
example
"spec": {
  "type": "tcp",
  "socket": {
    "host": "10.0.1.99",
    "port": 4444
  },
  "metadata" : {
    "name": "tcp_handler",
    "namespace": "default"
  }
}

Metadata attributes

name
description Unique string used to identify the handler. Handler names cannot contain special characters or spaces (validated with Go regex \A[\w\.\-]+\z). Each handler must have a unique name within its namespace.
required true
type String
example
"name": "handler-slack"
namespace
description Sensu RBAC namespace that the handler belongs to.
required false
type String
default default
example
"namespace": "production"
labels
description Custom attributes to include with event data that you can use for response and dashboard view filtering.

If you include labels in your event data, you can filter API responses, sensuctl responses, and dashboard 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"
}
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 dashboard 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"
}

Spec attributes

type
description Handler type.
required true
type String
allowed values pipe, tcp, udp & set
example
"type": "pipe"
filters
description Array of Sensu event filters (by names) to use when filtering events for the handler. Each array item must be a string.
required false
type Array
example
"filters": ["occurrences", "production"]
mutator
description Name of the Sensu event mutator to use to mutate event data for the handler.
required false
type String
example
"mutator": "only_check_output"
timeout
description Handler execution duration timeout (hard stop). In seconds. Only used by pipe, tcp, and udp handler types.
required false
type Integer
default 60 (for tcp and udp handlers)
example
"timeout": 30
command
description Handler command to be executed. The event data is passed to the process via STDIN. NOTE: The command attribute is only supported for pipe handlers (i.e. handlers configured with "type": "pipe").
required true (if type equals pipe)
type String
example
"command": "/etc/sensu/plugins/pagerduty.go"
env_vars
description Array of environment variables to use with command execution. NOTE: The env_vars attribute is only supported for pipe handlers (i.e. handlers configured with "type": "pipe").
required false
type Array
example
"env_vars": ["API_KEY=0428d6b8nb51an4d95nbe28nf90865a66af5"]
socket
description Scope for socket definition used to configure the TCP/UDP handler socket. NOTE: The socket attribute is only supported for TCP/UDP handlers (i.e. handlers configured with "type": "tcp" or "type": "udp").
required true (if type equals tcp or udp)
type Hash
example
"socket": {}
handlers
description Array of Sensu event handlers (by their names) to use for events using the handler set. Each array item must be a string. NOTE: The handlers attribute is only supported for handler sets (i.e. handlers configured with "type": "set").
required true (if type equals set)
type Array
example
"handlers": ["pagerduty", "email", "ec2"]
runtime_assets
description Array of Sensu assets (by names) required at runtime to execute the command
required false
type Array
example
"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"
  }
]

socket attributes

host
description Socket host address (IP or hostname) to connect to.
required true
type String
example
"host": "8.8.8.8"
port
description Socket port to connect to.
required true
type Integer
example
"port": 4242

secrets attributes

name
description Name of the secret defined in the executable command. Becomes the environment variable presented to the check. See Use secrets management in Sensu for more information.
required true
type String
example
"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"

Handler examples

Minimum required pipe handler attributes

type: Handler
api_version: core/v2
metadata:
  name: pipe_handler_minimum
  namespace: default
spec:
  command: command-example
  type: pipe
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "pipe_handler_minimum",
    "namespace": "default"
  },
  "spec": {
    "command": "command-example",
    "type": "pipe"
  }
}

Minimum required TCP/UDP handler attributes

This example demonstrates a tcp type handler. Change the type from tcp to udp to create the minimum configuration for a udp type handler.

type: Handler
api_version: core/v2
metadata:
  name: tcp_udp_handler_minimum
  namespace: default
spec:
  socket:
    host: 10.0.1.99
    port: 4444
  type: tcp
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "tcp_udp_handler_minimum",
    "namespace": "default"
  },
  "spec": {
    "type": "tcp",
    "socket": {
      "host": "10.0.1.99",
      "port": 4444
    }
  }
}

Send Slack alerts

This handler will send alerts to a channel named monitoring with the configured webhook URL, using the handler-slack executable command.

type: Handler
api_version: core/v2
metadata:
  name: slack
  namespace: default
spec:
  command: sensu-slack-handler --channel '#monitoring'
  env_vars:
  - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  filters:
  - is_incident
  - not_silenced
  handlers: []
  runtime_assets: []
  timeout: 0
  type: pipe
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "slack",
    "namespace": "default"
  },
  "spec": {
    "command": "sensu-slack-handler --channel '#monitoring'",
    "env_vars": [
      "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    ],
    "filters": [
      "is_incident",
      "not_silenced"
    ],
    "handlers": [],
    "runtime_assets": [],
    "timeout": 0,
    "type": "pipe"
  }
}

Send event data to a TCP socket

This handler will send event data to a TCP socket (10.0.1.99:4444) and timeout if an acknowledgement (ACK) is not received within 30 seconds.

type: Handler
api_version: core/v2
metadata:
  name: tcp_handler
  namespace: default
spec:
  socket:
    host: 10.0.1.99
    port: 4444
  type: tcp
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata" : {
    "name": "tcp_handler",
    "namespace": "default"
  },
  "spec": {
    "type": "tcp",
    "socket": {
      "host": "10.0.1.99",
      "port": 4444
    }
  }
}

Send event data to a UDP socket

This handler will forward event data to a UDP socket (10.0.1.99:4444) and timeout if an acknowledgement (ACK) is not received within 30 seconds.

type: Handler
api_version: core/v2
metadata:
  name: udp_handler
  namespace: default
spec:
  socket:
    host: 10.0.1.99
    port: 4444
  type: udp
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata" : {
    "name": "udp_handler",
    "namespace": "default"
  },
  "spec": {
    "type": "udp",
    "socket": {
      "host": "10.0.1.99",
      "port": 4444
    }
  }
}

Execute multiple handlers

The following example handler will execute three handlers: slack, tcp_handler, and udp_handler.

type: Handler
api_version: core/v2
metadata:
  name: notify_all_the_things
  namespace: default
spec:
  handlers:
  - slack
  - tcp_handler
  - udp_handler
  type: set
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata" : {
    "name": "notify_all_the_things",
    "namespace": "default"
  },
  "spec": {
    "type": "set",
    "handlers": [
      "slack",
      "tcp_handler",
      "udp_handler"
    ]
  }
}

Handler with secret

Learn more about secrets management for your Sensu configuration in the secrets and secrets providers references.

---
type: Handler 
api_version: core/v2 
metadata:
  name: ansible-tower
  namespace: ops
spec: 
  type: pipe
  command: sensu-ansible-handler -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN
  secrets:
  - name: ANSIBLE_HOST
    secret: sensu-ansible-host
  - name: ANSIBLE_TOKEN
    secret: sensu-ansible-token
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "ansible-tower",
    "namespace": "ops"
  },
  "spec": {
    "type": "pipe",
    "command": "sensu-ansible-handler -h $ANSIBLE_HOST -t $ANSIBLE_TOKEN",
    "secrets": [
      {
        "name": "ANSIBLE_HOST",
        "secret": "sensu-ansible-host"
      },
      {
        "name": "ANSIBLE_TOKEN",
        "secret": "sensu-ansible-token"
      }
    ]
  }
}