• 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:

#+BEGIN_SRC ruby 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_SRC

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.

#+BEGIN_SRC ruby require 'sensu-plugin/metric/cli'

class MyJSONMetric < Sensu::Plugin::Metric::CLI::JSON

def run
  ok "foo" => 1, "bar" => "anything"

end #+END_SRC

#+BEGIN_SRC ruby require 'sensu-plugin/metric/cli'

class MyGraphiteMetric < Sensu::Plugin::Metric::CLI::Graphite

def run
  ok "sensu.baz", 42

end #+END_SRC

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


** Contributing

- Fork repository
- Add functionality and any applicable tests
- Ensure all tests pass by executing =bundle exec rake test=
- Open a pull request

You may run individual tests by executing =bundle exec rake test TEST=test/external_handler_test.rb=

  • License

Copyright 2011 Decklin Foster

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