Installing & Managing Plugins

Sensu’s functionality can be extended through the use of plugins. Plugins can provide executables for performing status or metric checks, mutators for changing data to a desired format, or handlers for performing an action on a Sensu event. You can find a number of plugins in the Sensu Plugins repository.

NOTE: Plugins found in the Sensu Plugins GitHub organization are community-maintained, meaning that anyone can improve on a plugin found there. If you have a question about how you can get involved in adding to, or providing a plugin, head to the Sensu Community Slack channel. Our maintainers are always happy to help answer questions and point you in the right direction.

Linux

To install a Ruby-based plugin, you can use the sensu-install tool provided as part of the Sensu package.

sensu-install --help
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

As an example, let’s install the Sensu Disk Checks Plugin:

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

To install a specific version of the Sensu Disk Checks Plugin with sensu-install, run:

sensu-install -p 'sensu-plugins-disk-checks:3.1.0'

We strongly recommend using a configuration management or orchestration tool to pin the versions of any plugins installed in production. For more information about enforcing plugin versions with configuration management, see the Sensu Community best practices documentation.

Removing Plugins

If you find that you need to remove a plugin, you can use the embedded gem command to remove a plugin. See the example below:

/opt/sensu/embedded/bin/gem uninstall sensu-plugins-disk-checks

Windows

To install a Ruby-based plugin on Windows, you can use the sensu-install utility provided as part of the Sensu MSI package, located in C:\opt\sensu\embedded\bin.

For example, to install the Sensu Windows Plugin, run the following from an administrative command prompt:

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

NOTE: When installing plugins on Windows, double check that the executable you’re using is compatible with Windows. You can always check by examining the executable in the respective GitHub repo in the bin directory.

To install a specific version of the Sensu Windows Plugin, run the following from an administrative command prompt:

c:\opt\sensu\embedded\bin\sensu-install -p 'sensu-plugins-windows:2.8.1'

We strongly recommend using a configuration management or orchestration tool to pin the versions of any plugins installed in production. For more information about enforcing plugin versions with configuration management, see the Sensu Community best practices documentation.

Removing Plugins

If you find that you need to remove a plugin, you can use the embedded gem command to remove a plugin. See the example below as run from an administrative command prompt:

$ c:\opt\sensu\embedded\bin\gem uninstall sensu-plugins-windows
Remove executables:
        check-windows-cpu-load.rb, check-windows-disk.rb, check-windows-process.rb, check-windows-processor-queue-length.rb, check-windows-ram.rb, check-windows-service.rb, metric-windows-cpu-load.rb, metric-windows-disk-usage.rb, metric-windows-network.rb, metric-windows-processor-queue-length.rb, metric-windows-ram-usage.rb, metric-windows-uptime.rb, powershell_helper.rb

in addition to the gem? [Yn]  y
Removing check-windows-cpu-load.rb
Removing check-windows-disk.rb
Removing check-windows-process.rb
Removing check-windows-processor-queue-length.rb
Removing check-windows-ram.rb
Removing check-windows-service.rb
Removing metric-windows-cpu-load.rb
Removing metric-windows-disk-usage.rb
Removing metric-windows-network.rb
Removing metric-windows-processor-queue-length.rb
Removing metric-windows-ram-usage.rb
Removing metric-windows-uptime.rb
Removing powershell_helper.rb
Successfully uninstalled sensu-plugins-windows-2.8.1

We hope you’ve found this useful! If you find any issues or have a question, feel free to reach out in our Community Slack, or open an issue on GitHub.