Sensu Extensions

Reference documentation

What is a Sensu extension?

Unlike Sensu plugins, which spawn a new child process at every execution, Sensu
extensions execute directly inside the EventMachine reactor thread of a
Sensu client or server process. Because they avoid the overhead of spawning a
new process at every invocation, Sensu extensions can fulfill the same functions
as plugins, acting as checks, filters, mutators or handlers, but with much
greater efficiency.

WARNING: While their performance characteristics are quite desirable, Sensu
extensions come with major caveats: extensions have full access to Sensu’s
internals, and any extension which blocks the EventMachine reactor for any
period of time (e.g. blocking on disk IO or network request) will have a very
significant negative impact on Sensu’s performance and functionality. The
details of evented programming as implemented by EventMachine are outside the
scope of this document, but Javier Acero has helpfully written on the
implications of blocking the reactor.

Installing Sensu extensions

As of version 0.28, Sensu supports loading extensions from properly packaged
gems. This approach takes advantage of the existing RubyGems infrastructure and
tools to make publishing and installing Sensu extensions easy.

Sensu extensions can be installed using the sensu-install executable:

EXAMPLE

sensu-install -e sensu-extensions-system-profile

Configuring Sensu to load extensions

Once an extension is installed via gem, Sensu must be explicitly configured to
load the extension. This is accomplished by providing
configuration under the top level extensions attribute:

EXAMPLE

Once extensions have been explicitly enabled in Sensu’s configuration, they will
be loaded the next time Sensu processes are restarted. Informational messages
are printed to the log when extensions are loaded:

NOTE: Explicit extension loading does not apply to legacy
extensions, which are loaded by virtue of
being placed in the extension directory.

Installing Sensu legacy extensions

Sensu extensions which are not properly packaged as gems are considered
“legacy”, meaning they predate the new specification for loading Sensu
Extensions from gems.

These legacy extensions are loaded from the directory specified by the
--extension_dir flag provided when Sensu processes are started. On most
systems this defaults to /etc/sensu/extensions, as specified by the command
flags passed to the sensu-client or sensu-server process via the service
supervision scheme in use (e.g. init, runit, upstart, systemd, etc).
Extensions should be installed directly into the extensions directory.

When an legacy extension has dependencies on third-party Ruby gems or other external
applications, those dependencies must be installed into the Sensu embedded Ruby
environment as well.

Configuring Sensu Extensions

The configurability of Sensu extensions is entirely a function of the extension code.
For example, filters and mutators cannot be applied to an extension via a standard
handler definition. Instead, these aspects of the extension’s configuration must be
defined in code by overriding the Sensu::Extension::Base definition method:

EXAMPLE

The above code would configure the associated extension to apply the
occurrences filter, and then the only_check_output mutator, prior to
executing the extension’s custom run method.

By virtue of being loaded into the Sensu client or server process, Sensu
extensions have access to the running Sensu configuration. As such an extension
can make use of any available configuration scopes, but the prevailing
convention is for extensions to use unique top-level configuration scopes.

The system_profile extension installed in a previous example looks to the
top-level system_profile configuration scope. The following configuration
added to /etc/sensu/conf.d would change the system_profile extension’s
Graphite path prefix from a default value of “system” to “profile”:

EXAMPLE

{"system_profile":{"path_prefix":"profile"}}

The sensu-extension gem

Unlike Sensu plugins, which may be written in any programming language, Sensu
extensions must be written in Ruby. The sensu-extension gem provides
Sensu::Extension::Base and other classes which Sensu extensions should
subclass.

The sensu-extensions gem template

The sensu-extensions gem template provides a starting point for those who wish
to author their own Sensu extension as a Ruby gem. It is recommended that your
gem follow the naming pattern “sensu-extension-$NAME” in order to ensure it can
be easily installed with sensu-install.

NOTE: if you choose not to use this template for your extension, note the
directory structure it demonstrates (e.g. placing extension code under
lib/sensu/extensions/) are required to ensure the extension is properly loaded.

Newsletter

Subscribe to the newsletter to get product updates about Sensu, including notifications when new releases are available. No more than one email per week, no less than one email per month. #monitoringlove.