Handling Sensu Plugin handlers in Sensu Go

In case you missed it, Sensu Go is here! And, as I wrote about previously, one of the hurdles with migrating workloads from the original version of Sensu to Sensu Go are the changes in the internal event data structure. The existing handlers and mutators in the community maintained Sensu Plugins collection might not work as expected in Sensu Go because of these event data model changes. But friends, I’m here to tell you that we’ve got this problem licked.

The new 3.0.0 release of the sensu-plugin gem has opt-in logic to help you transition workloads using existing Ruby mutators and handlers from the Sensu Community Plugins collection. Once the community plugins you rely on are updated to require the 3.0 sensu-plugin gem, you’ll have a much easier time migrating your existing workflows without having to write your own mutator for event data. This post marks the first in a series in which I help folks migrate their workloads to Sensu Go.

Using updated handlers and mutators

Once a plugin has been updated to depend on the latest version of sensu-plugin, all the provided handlers and mutators gain the option to enable mapping from Sensu Go to Sensu Ruby events. You can activate the logic using either an additional command line option or by setting an environment variable in your Sensu Go handler/mutator resource environment. If you want to see how it works in practice, grab the latest sensu-plugin gem and ask mutator-sensu-go-into-ruby.rb for its help output:

mutator-sensu-go-into-ruby.rb --help
Usage: /usr/local/bin/mutator-sensu-go-into-ruby.rb (options)
 --map-go-event-into-ruby Enable Sensu Go to Sensu Ruby event mapping.
Alternatively set envvar SENSU_MAP_GO_EVENT_INTO_RUBY=1.

Using the mix-in magic in sensu-plugin, the command line option and usage are added to every handler and mutator built from the base classes in sensu-plugin.

By default, the new mapping logic won’t be used in any handler or mutator command, so once your plugins are upgraded, (if you’re an existing Sensu 1.x user) you won’t have to do anything different for your configs. But when you’re ready to migrate to Sensu Go, you’ll be able to either use an environment variable to turn on the mapping for all handlers and mutators that support it or selectively enable the mapping using a command-line argument.

This event mapping logic is meant to be a transitional helper to keep existing handlers and mutators working until Sensu Go native implementations can be spun up. I say transitional because this approach uses a mutator operation to rewrite the event data, and is going to be suboptimal compared to a handler that can parse the Sensu Go event data directly because of the additional overhead to mutate the data object.

How you can help

Now with the new sensu-plugin package released, the next step is to get the other Sensu Community Plugins updated to make use of the new version. This is a great opportunity for Sensu users — like you — to contribute and help make the Sensu Go experience better for everyone! If you haven’t done a pull request against any of the community maintained plugins before, these plugin updates should make for a great first-time technical contribution. You can use this search query to get a listing of open issues for plugins that are a candidate.

Feel free to take a look at the open issues list and see if there is a plugin you can help update. If you want to try to help out and contribute a fix, take a look at the Sensu Plugins pull request process. I’ll be watching the Sensu Go enablement issues and following up on relevant pull requests, but if you get stuck you can ping me in the Sensu Community Slack (@jspaleta) or raise an issue in our Community Forum and I’ll see if I can help.

For most plugins, this should be a very simple change to the gemspec to bump the sensu-plugin runtime dependency, then running the local verification tests to ensure the plugin still builds as expected. Some plugins may need additional changes to update other runtime dependencies. I can help with that if needed — just ping me on Slack.

I am currently working on updating sensu-plugins-logs, but there are several other community-maintained plugins that need to be updated. I have filed issues against all the Sensu Plugins I’m aware of with handlers or mutators in the Sensu Plugins GitHub organization. And please, if there are Sensu Plugins you’re using that are maintained outside of the Sensu Plugins organization, please file issues to encourage them to update their runtime dependency to sensu-plugin 3.0 (and let me know you filed the issue so I can keep track).

Testing with the provided mutator

In the meantime, if you have event pipelines making use of Sensu Plugin handlers without need of a mutator, those can be tested for Sensu Go compatibility using the new mutator-sensu-go-into-ruby.rb mutator provided in the latest sensu-plugin version.

To manually test on the commandline, you can export a json representation of an event in Sensu Go using sensuctl and feed that into the mutator-sensu-go-into-ruby.rb command. The output should be a Sensu Core 1.x compatible event.

Here is a command line example using the Sensu Go keepalive event from the sensu-go-sandbox entity to test the event mapping logic.

$ sensuctl event info sensu-go-sandbox keepalive --format json|jq .

The first command above shows the JSON representation of Sensu Go event nicely formatted. Notice there is no client defined .

$ sensuctl event info sensu-go-sandbox keepalive --format json|
mutator-sensu-go-into-ruby.rb | jq .

The output of the mapping mutator should look more familiar to Sensu 1.x users, having a top-level client hash defined. The mapping logic does the minimal changes necessary to provide a Sensu 1.x compatible event.

But wait! There’s more!

One of our excellent Community Maintainers, Barry O’Rourke, has ported this work into the sensu-plugins-python package! If you’re building Python-based handlers, you’ll soon be able to take advantage of a similar opt-in mechanism if you’ve based your handler on this Python package.

Thanks to everyone for contributing to Sensu! Once we have more of the Community Plugins updated to use the sensu-plugin 3.0 release series, I plan to put together a blog post showing how to migrate workloads using community plugin handlers from Sensu 1.x to Sensu Go.