Skip to content
A framework for writing Sensu plugins & handlers with Ruby.
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Sensu Plugin

This is a framework for writing your own Sensu plugins and handlers. It’s not required to write a plugin (most Nagios plugins will work without modification); it just makes it easier.

Examples of plugins written with and without it can be found in the sensu-community-plugins repository.

Checks and Metrics

To implement your own check, subclass Sensu::Plugin::Check::CLI, like this:

require 'sensu-plugin/check/cli'

class MyCheck < Sensu::Plugin::Check::CLI

  check_name 'My awesome check' # defaults to class name
  option :foo, :short => '-f' # Mixlib::CLI is included

  def run
    ok "All is well"


This will output a string, like “My awesome check: OK - All is well”, and exit with a code of 0. The available exit methods, which will immediately end the process, are:

  • ok
  • warning
  • critical
  • unknown

For a metric, subclass Sensu::Plugin::Metric::CLI. Your argument to whichever exit method will be converted to JSON instead of Nagios-style output. check_name doesn’t apply; just set more keys on the object you return if you want to include more information. If your object doesn’t respond to [:timestamp], it will add one for you.

You can override format_output if you want something other than these two formats, but it’s not documented yet.


Various utility methods will be collected under Sensu::Plugin::Util. These won’t depend on any extra gems or include actual CLI checks; it’s just for common things that many checks might want to do.


For your own handler, subclass Sensu::Handler. It looks much like checks and metrics; see the handlers directory for examples. Your class should implement handle(event). It is passed the event, which has been read from stdin and parsed as JSON. Output to stdout will go to the log.

You can decide if you want to handle the event by overriding the filter method; but this also isn’t documented yet (see the source; the built in method does some important filtering, so you probably want to call it with super).

Sensu’s configuration settings are available with the settings method (they will be loaded on first use). We recommend you put your settings in a JSON file in /etc/sensu/conf.d, with a unique top-level key, like:

  "mycheck": {
    "foo": true


Copyright 2011 Decklin Foster

Released under the same terms as Sensu (the MIT license); see LICENSE for details.

Something went wrong with that request. Please try again.