Plugin Status

Plugin Status

Plugins (inputs/outputs/filters) now have a status in logstash. This is to provide an indicator to the end-user as to the 'state' of the plugin.

Terminology is still being worked out but there are three general states - experimental, unstable, stable.

The desire here is to allow people to quickly iterate on possible new plugins while conveying to the end-user a set of expectations about that plugin. This allows you to make more informed decisions about when and where to use the functionality provided by the new plugin.

Startup messages

When users use a plugin marked as experimental or unstable, they will get an additional one-time log message conveying to them that they are using a plugin of that status.

Experimental

When a plugin is in the experimental state, it is essentially untested. This does not mean that it does not have any associated unit tests. This applies more to in-the-wild usage. Most new plugins will probably fit in this category. There is a chance that experimental plugins may be removed at some point. It is possible that an experimental plugin will be broken mid-release.

Displayed Message

W, [2012-01-13T22:04:14.955000 #76382] WARN -- : Using experimental plugin zmq. This plugin is untested. Use at your own risk {"timestamp":"2012-01-13T22:04:14.947000 -0500","message":"Using experimental plugin zmq. This plugin is untested. Use at your own risk","level":"warn"}

Unstable

Unstable plugins are plugins that are in the process of being stabalized into a final form. Unstable plugins will have a bit more wide-spread usage in the community. The API for these plugins has stabilized and is unlikely to change mid-release. Test cases may or may not exist.

Displayed Message

I, [2012-01-13T22:01:25.560000 #76277] INFO -- : Using unstable plugin amqp. {"timestamp":"2012-01-13T22:01:25.551000 -0500","message":"Using unstable plugin amqp.","level":"info"}

Stable

Stable plugins are plugins that you can comfortably rely on in production. These have full test cases.

Displayed Message

None

A note about output plugins

It's worth reminding users that output plugins are currently blocking. If any output plugin fails, all output plugins are blocked. Please keep this in mind when using experimental output plugins as it could cause unintended side-effects.

For plugin authors

You MUST set a plugin status in your code now. This should be placed right after the config_name DSL entry:

class LogStash::Inputs::WickedCoolInput < LogStash::Inputs::Base

  config_name "wicked_cool_input"
  plugin_status "experimental"
  
  # All my other cool code
end

Use the guidelines above to determine how to set the status on your plugin. Your plugin will NOT run if it does not have a plugin_status set.