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"
end
end
This will output the string “my_awesome_check OK: All is well” (like a Nagios plugin), and exit with a code of 0. The available exit methods, which will immediately end the process, are:
ok
warning
critical
unknown
You can also call message
first to set the message, then call an exit
method without any arguments (for example, if you want to choose between
WARNING and CRITICAL based on a threshold, but use the same message in
both cases).
For a metric, you can subclass either Sensu::Plugin::Metric::CLI::JSON
or Sensu::Plugin::Metric::CLI::Graphite
. Instead of outputting a
Nagios-style line of text, these classes will output JSON-serialized
objects or Graphite messages.
require 'sensu-plugin/metric/cli'
class MyJSONMetric < Sensu::Plugin::Metric::CLI::JSON
def run
ok "foo" => 1, "bar" => "anything"
end
end
require 'sensu-plugin/metric/cli'
class MyGraphiteMetric < Sensu::Plugin::Metric::CLI::Graphite
def run
ok "sensu.baz", 42
end
end
JSON output takes one argument (the object), and adds a ‘timestamp’ key
if missing. Graphite output takes two arguments, the metric path and the
value, and optionally the timestamp as a third argument. Time.now.to_i
is used for the timestamp if it is not specified.
Exit codes do not affect metric output, but they can still be used by your handlers.
Some metrics may want to output multiple values in a run. To do this,
use the output
method, with the same arguments as the exit methods, as
many times as you want, then call an exit method without any arguments.
For either checks or metrics, you can override output
if you want
something other than these formats.
Options
For help on setting up options, see the mixlib-cli
documentation.
Command line arguments that are not parsed as options are available via
the argv
method.
Utilities
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.
Handlers
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
. The instance variable @event
will be set
for you if a JSON event can be read from stdin; otherwise, the handler
will abort. 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 } }
License
Copyright 2011 Decklin Foster
Released under the same terms as Sensu (the MIT license); see LICENSE for details.