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 (that is, 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.

Use Nagios plugins

The Sensu plugin specification is compatible with the Nagios plugin specification, so you can use the 50+ plugins in the official Nagios Plugins project and 4000+ plugins in the Nagios Exchange with Sensu without any modification.

Plugin execution

All plugins are executed by the Sensu backend. Plugins must be executable files that are discoverable on the Sensu system (that is, installed in a system $PATH directory) or referenced with an absolute path (for example, /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 (for example, 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": "http-check --url".

Plugin configuration overrides

Many plugins support configuration overrides on a per-entity or per-check basis. For example, some plugins allow you to use annotations in individual entities and checks to set arguments that will override any arguments set in a resource command or in backend runtime environment variables for only that entity or check.

Read the Bonsai documentation for a plugin to learn about any configuration overrides the plugin supports.

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.