Troubleshooting mutator-handler interaction


I have a handler that works fine. I wanted to add a mutator and did the following:

  1. Wrote an executable script in ruby that takes in a JSON from stdin like this

    event = JSON.parse(

The event is mutated as desired and then is output like this

puts JSON.dump(event)
  1. I added my mutator to the handler yaml as shown in sensu docs
  2. In my mutator definition set the command to: test_mutator.rb (which is the name of the executable file) and I added the runtime assets which contained the actual executable

When i trigger a check (without the mutator in the handler configuration, it works as expected. But when I add the mutator nothing happens. I know something is either wrong with the executable itself or how i have configured it, but I do not know what. Any help would be greatle appreciated!!

Thank you

First thing I would suggest is turning on debug logging for the backend to see if any errors are reported when trying to run the mutator and/or handler once the mutator is in place.

You also mention that you “added the runtime assets”, does this mean you are packaging up your mutator as an internal asset?


Thank you for your response. I made some changes and looked at the logs and the error was “pipe mutator execution returned non-zero exit status” and the message “failed to mutate the event”. When I pipe a JSON file into my mutator on my local machine it works perfectly. Is there something else I might be missing ?

So when you pipe a JSON into your mutator on your local machine, is it, in fact, exiting with a non-zero status?

my_mutator_script < event.json
echo $?

Yes it is. Someone mentioned needing to have chmod a+x at the top of the file but I haven’t seen that in any examples. I’m out of ideas on what to try

If it is returning a non-zero exit status, that’s the issue. The Sensu backend is expecting it to return a zero exit status (shell true) upon successful exit (e.g. was able to mutate the event). It assumes non-zero (shell false) as a failure.

When I pipe an example event into my mutator as you suggested and checked the exit code following that it said 0. Are mutators expected to explicitly return an exit code like
if error exit 2 else exit 0

The initial error was a missing sensu-ruby-runtime asset but even with the asset it says unable to mutate event

Yes, it is good form for your mutator to return an exit status like that (non-zero if error, zero if successful). It’s up to you whether it’s explicit or simply based on the last portion of code executed prior to exiting.

Does your ruby script reference ruby like this #! /usr/bin/env ruby?

@lazygazelle I see there’s also the support ticket open about this and it look like the issue might be Windows line endings (I think Alpine has issues with those). Can you convert your line endings and redeploy the mutator to see what you get?

@lazygazelle any updates re: line endings?

Hi Aaron,

Line endings weren’t the issue, but the issue has been resolved. Thank you