Plugins reference

Sensu plugins provide executable scripts or other programs that you can use as Sensu checks, handlers, and mutators. Sensu plugins must comply with the following specification:

  • Accept input/data via STDIN (handler and mutator plugins only)
    • Optionally able to parse a JSON data payload (i.e. observation data in an event)
  • Output data to STDOUT or STDERR
  • Produce an exit status code to indicate state:
    • 0 indicates OK
    • 1 indicates WARNING
    • 2 indicates CRITICAL
    • exit status codes other than 0, 1, or 2 indicate an unknown or custom status
  • Optionally able to parse command line arguments to modify plugin behavior

Supported programming languages

You can use any programming language that can satisfy the Sensu plugin specification requirements — which is nearly any programming language in the world — to write Sensu plugins.

Using plugins written in programming languages other than Go requires you to install the corresponding runtime. For example, to use a Ruby plugin with Sensu Go, you must install the Sensu Go Ruby Runtime asset.

Plugin execution

All plugins are executed by the Sensu backend. Plugins must be executable files that are discoverable on the Sensu system (i.e. installed in a system $PATH directory) or referenced with an absolute path (e.g. /opt/path/to/my/plugin).

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 (e.g. plugins) located in /etc/sensu/plugins will be valid commands. This allows command attributes to use relative paths for Sensu plugin commands, such as "command": "check-http.rb -u".

Go plugin example

The following example shows the structure for a very basic Sensu Go plugin.

package main

import (


// Config represents the check plugin config.
type Config struct {
	Example string

var (
	plugin = Config{
		PluginConfig: sensu.PluginConfig{
			Name:     "check_name",
			Short:    "Description for check_name",
			Keyspace: "",

	options = []*sensu.PluginConfigOption{
			Path:      "example",
			Env:       "CHECK_EXAMPLE",
			Argument:  "example",
			Shorthand: "e",
			Default:   "",
			Usage:     "An example string configuration option",
			Value:     &plugin.Example,

func main() {
	check := sensu.NewGoCheck(&plugin.PluginConfig, options, checkArgs, executeCheck, false)

func checkArgs(event *types.Event) (int, error) {
	if len(plugin.Example) == 0 {
		return sensu.CheckStateWarning, fmt.Errorf("--example or CHECK_EXAMPLE environment variable is required")
	return sensu.CheckStateOK, nil

func executeCheck(event *types.Event) (int, error) {
	log.Println("executing check with --example", plugin.Example)
	return sensu.CheckStateOK, nil

To create this scaffolding for a Sensu Go check, handler, mutator, or sensuctl plugin, use the Sensu Plugin Tool along with a default plugin template. The plugin template repositories wrap the Sensu Plugin SDK, which provides the framework for building Sensu Go plugins.

For a step-by-step walkthrough, read How to publish an asset with the Sensu Go SDK — you’ll learn how to create a check plugin and a handler plugin with the Sensu Plugin SDK. You can also watch our 30-minute webinar, Intro to assets with the Sensu Go SDK, and learn to build a check plugin for Sensu Go.

Ruby plugin example

The following example demonstrates a very basic Sensu plugin in the Ruby programming language.

#!/usr/bin/env ruby
require 'json'

# Read the incoming JSON data from STDIN
event = JSON.parse(, :symbolize_names => true)

# Create an output object using Ruby string interpolation
output = "The check named #{event[:check][:name]} generated the following output: #{event[:output]}"

# Convert the mutated event data back to JSON and output it to STDOUT
puts output

NOTE: This example is intended as a starting point for building a basic custom plugin in Ruby. It does not provide functionality.