Handlers

• How do Sensu handlers work?
  • Pipe handlers
  • TCP/UDP handlers
  • Handler sets
• Handling keepalive events
• Specification
  • Top-level attributes
  • Spec attributes
  • Metadata attributes
  • socket attributes
• Examples

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

How do Sensu handlers work?

Handlers actions are executed by the Sensu backend on events, and there are several types of handlers available. The most common handler type is the pipe handler, which works very similarly to how checks work, enabling Sensu to interact with almost any computer program via standard streams.

• Pipe handlers. Pipe handlers pipe event data into arbitrary commands via STDIN.
• TCP/UDP handlers. TCP and UDP handlers send event data to a remote socket.
• Handler sets. Handler sets (also called “set handlers”) are used to group event handlers, making it easy to manage groups of actions that should be executed for certain types of events.

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 to be executed by the Sensu backend.

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 groups of handlers (individual collections of actions to take on event data) to be referenced via a single named handler set.

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.

Handling keepalive events

Sensu keepalives are the heartbeat mechanism used to ensure that all registered Sensu agents are operational and able to 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.

Let’s say 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 looks like this:

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

Handler specification

Top-level attributes

"type": "Handler"

"api_version": "core/v2"

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

"spec": {
  "type": "tcp",
  "socket": {
    "host": "10.0.1.99",
    "port": 4444
  },
  "metadata" : {
    "name": "tcp_handler",
    "namespace": "default"
  }
}

Spec attributes

"type": "pipe"

"filters": ["occurrences", "production"]

"mutator": "only_check_output"

"timeout": 30

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

"env_vars": ["API_KEY=0428d6b8nb51an4d95nbe28nf90865a66af5"]

"socket": {}

"handlers": ["pagerduty", "email", "ec2"]

"runtime_assets": ["ruby-2.5.0"]

Metadata attributes

"name": "handler-slack"

"namespace": "production"

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

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

socket attributes

"host": "8.8.8.8"

"port": 4242

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 is an example of a tcp type handler. Changing the type from tcp to udp gives you 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
    }
  }
}

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

Sending event data to a TCP socket

This handler will forward event data to a TCP socket (10.0.1.99:4444) and will 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
    }
  }
}

Sending event data to a UDP socket

The following example will also forward event data but to UDP socket instead (ex: 10.0.1.99:4444).

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

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