Sensu Plugins

Reference documentation

What is a Sensu plugin?

Sensu plugins provide executable scripts or other programs that can be used as Sensu checks (i.e. to monitor server resources, services, and application health, or collect & analyze metrics), Sensu handlers (i.e. to send notifications or perform other actions based on Sensu events), or Sensu mutators (i.e. to modify event data prior to handling).

The Sensu Plugin specification

Sensu Plugins provide executable scripts or other programs that can be used as a Sensu check command, pipe handler command, or mutator command. Sensu plugins must comply with a simple specification:

  • Accept input/data via STDIN (handler and mutator plugins only)
    • Optionally able to parse a JSON data payload (i.e. event data)
  • 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

PRO TIP: Those familiar with the Nagios monitoring system may recognize this specification, as it is the same one used by Nagios plugins. As a result, Nagios plugins can be used with Sensu without any modification.

Where to find Sensu Plugins

The Sensu Plugins project

The Sensu Plugins project is a community-powered open source software project that is organized by members of the Sensu community, in collaboration with the Sensu development team. The Sensu Plugins project currently maintains hundreds of plugins providing various checks, handlers, and mutators which are used by thousands of organizations around the world. Most of the plugins maintained by the Sensu Plugins project are Ruby-based plugins which are distributed via (and installable via sensu-install).

To help new users discover some of the most popular plugins for instrumenting their infrastructure and integrating Sensu with popular tools and services, a featured plugins page is provided on the Sensu website. These featured plugins are the same plugins developed and maintained by the Sensu plugins project.

Nagios plugins and the Nagios Exchange

As previously mentioned, the Sensu Plugin specification is 100% compatible with the Nagios plugin specification; as a result, Nagios plugins may be used with Sensu without any modification. Sensu allows you to bring new life to the 50+ plugins in the official Nagios Plugins project (which began life in 1999, making it a very mature source for monitoring plugins), and over 4000 plugins available in the Nagios Exchange.

Write your own custom plugins

With a simple specification, which makes it possible to write Sensu plugins in almost any programming language, it’s very easy to write your own custom plugins for Sensu.

Example plugins

The following example demonstrates how to write a very basic Sensu Plugin in the Ruby programming language.

#!/usr/bin/env ruby
# A simple example handler plugin.

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 doesn’t provide much in terms of functionality (it would simply be logged to the Sensu server log file), but it does provide a starting point for a simple custom plugin.

Plugin execution

How and where are plugins executed?

As mentioned elsewhere in the documentation (see: check commands, pipe handler commands, and mutator commands), all plugins are executed by a Sensu client or Sensu server as the sensu user. Plugins must be executable files that are discoverable on the Sensu system (i.e. installed in a system $PATH directory), or they must be referenced with an absolute path (e.g. /opt/path/to/my/plugin).

NOTE: By default, the 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;

e.g.: "command": "check-http.rb -u"

What programming languages are supported?

Any programming language that can satisfy the Sensu plugin specification requirements – which is nearly any programming language in the world – can be used to write Sensu plugins. One of the primary advantages of writing Sensu plugins in the Ruby programming language is that Sensu itself is written in Ruby, and all Sensu installer packages provide an embedded Ruby, eliminating the need to install or depend on a separate runtime.

NOTE: plugins written in programming languages other than Ruby will require the corresponding runtime to be installed in order for the plugin to run.

What is Sensu’s EMBEDDED_RUBY?

All Sensu Core installer packages provide an embedded Ruby runtime (i.e. even if a system Ruby is installed, Sensu will run on its own Ruby). This “vendored” Ruby runtime can be accessed by Ruby-based plugins by setting Sensu’s EMBEDDED_RUBY configuration variable to true.

NOTE: in Sensu versions >0.21.0, all init/service scripts provided by the Sensu Core installer packages are setting Sensu’s EMBEDDED_RUBY environment variable to true, making the use of Sensu’s embedded Ruby the default behavior in modern Sensu releases.

Installing Sensu Plugins

Use sensu-install to install Sensu Plugins

The Sensu Core package provides a tool called sensu-install (a simple wrapper around the Ruby gem utility). The Sensu Install tool (sensu-install) simplifies installation of Ruby-based plugins. The sensu-install tool can be run with one or more arguments that determine the action(s) to take.

$ sensu-install -h
Usage: sensu-install [options]
    -h, --help                       Display this message
    -v, --verbose                    Enable verbose logging
    -p, --plugin PLUGIN              Install a Sensu PLUGIN
    -P, --plugins PLUGIN[,PLUGIN]    PLUGIN or comma-delimited list of Sensu plugins to install
    -e, --extension EXTENSION        Install a Sensu EXTENSION
    -E, --extensions EXTENSION[,EXT] EXTENSION or comma-delimited list of Sensu extensions to install
    -s, --source SOURCE              Install Sensu plugins and extensions from a custom SOURCE
    -c, --clean                      Clean up (remove) other installed versions of the plugin(s) and/or extension(s)
    -x, --proxy PROXY                Install Sensu plugins and extensions via a PROXY URL

NOTE: sensu-install is only available in Sensu Core >= 0.21.0.


The following instructions will install the Sensu HTTP plugin, using the sensu-install utility:

$ sudo sensu-install -p nginx
[SENSU-INSTALL] installing Sensu plugins ...
[SENSU-INSTALL] determining if Sensu plugin gem 'sensu-plugins-nginx' is already installed ...
[SENSU-INSTALL] Sensu plugin gems to be installed: ["sensu-plugins-nginx"]
[SENSU-INSTALL] installing Sensu plugin gem 'sensu-plugins-nginx'
Fetching: sensu-plugins-nginx-1.0.0.gem (100%)
You can use the embedded Ruby by setting EMBEDDED_RUBY=true in /etc/default/sensu
Successfully installed sensu-plugins-nginx-1.0.0
1 gem installed
[SENSU-INSTALL] successfully installed Sensu plugins: ["nginx"]

To install a specific version of a plugin, simply provide a version number after the plugin name (separated by a colon); for example:

$ sudo sensu-install -p nginx:0.0.6
[SENSU-INSTALL] installing Sensu plugins ...
[SENSU-INSTALL] determining if Sensu plugin gem 'sensu-plugins-nginx:0.0.6' is already installed ...
[SENSU-INSTALL] Sensu plugin gems to be installed: ["sensu-plugins-nginx:0.0.6"]
[SENSU-INSTALL] installing Sensu plugin gem 'sensu-plugins-nginx:0.0.6'
Fetching: mixlib-cli-1.5.0.gem (100%)
Successfully installed mixlib-cli-1.5.0
Fetching: sensu-plugin-1.2.0.gem (100%)
Successfully installed sensu-plugin-1.2.0
Fetching: sensu-plugins-nginx-0.0.6.gem (100%)
You can use the embedded Ruby by setting EMBEDDED_RUBY=true in /etc/default/sensu
Successfully installed sensu-plugins-nginx-0.0.6
3 gems installed
[SENSU-INSTALL] successfully installed Sensu plugins: ["nginx:0.0.6"]

NOTE: as shown in the examples above, the sensu-install utility will show the output of any gems (including gem dependencies) installed using sensu-install.

Alternative installation methods

Coming soon…

The Sensu Plugin gem

What is the sensu-plugin gem?

Although Sensu Plugins may be written in any programming language, there are certain advantages of writing plugins in Ruby. From an operations perspective, Ruby-based plugins are convenient because they are able to run on Sensu’s embedded Ruby. Ruby-based plugins also benefit from the sensu-plugin gem — a Ruby library that provides some built-in functionality and a number of helper classes and that simplify custom plugin development.

Much of the built-in functionality provided by the sensu-plugin gem depends on custom client, check, and/or handler definition attributes, as documented below.

Plugin configuration

Example check plugin definition

The following is an example Sensu check definition that uses the check-http.rb script provided by the Sensu HTTP Plugin, and a custom check definition attribute called refresh. Although the refresh attribute itself is not directly supported by Sensu, the sensu-plugin gem does provide built-in support for reducing alert fatigue via the Sensu::Plugin::Handler class (i.e. only handling events on the first occurrence, and again every N occurrences, where N = refresh).

  "checks": {
    "api_health": {
      "command": "check-http.rb -u",
      "standalone": true,
      "interval": 60,
      "refresh": 60

Sensu plugin definition specification

NOTE: plugins based on the sensu-plugin gem derive configuration from custom check definition attributes. The configuration example(s) provided above, and the “specification” provided here are for clarification and convenience only (i.e. this “specification” is just an extension of the check definition specification, and not a definition of a distinct Sensu primitive).

Check definition attributes

The number of event occurrences that must occur before an event is handled for the check. NOTE: Sensu Enterprise users will need to define occurrences as part of handle_when configuration, see Built in Filters for more information.
"occurrences": 3
Time in seconds until the event occurrence count is considered reset for the purpose of counting occurrences, to allow an event for the check to be handled again. For example, a check with a refresh of 1800 will have its events (recurrences) handled every 30 minutes, to remind users of the issue. NOTE: Sensu Enterprise users will need to define refresh as part of handle_when configuration, see Built in Filters for more information.
"refresh": 3600
An array of check dependencies. Events for the check will not be handled if events exist for one or more of the check dependencies. A check dependency can be a check executed by the same Sensu client (eg. check_app), or a client/check pair (eg.db-01/check_mysql).
"dependencies": [
The notification message used for events created by the check, instead of the commonly used check output. This attribute is used by most notification event handlers that use the sensu-plugin library.
"notification": "the shopping cart application is not responding to requests"

Start your FREE trial today.

Already using Sensu Core? Upgrade to Sensu Enterprise today to take advantage of its enterprise console, added-value features, built-in integrations, FREE annual training, and enterprise-class support.