Reference » Extending Logstash
«  Logstash Config Language     Input plugins  »

Extending Logstash

Getting Started with Logstash
Adding a sample filter to Logstash
Command-line flags
Logstash Config Language
Extending Logstash
Input plugins
Output plugins
Filter plugins
Codec plugins

You can add your own input, output, or filter plugins to Logstash.

If you’re looking to extend Logstash today, the best way is to look at how some existing plugins are written.

Good examples of plugins

Common concepts

  • The config_name sets the name used in the config file.
  • The milestone sets the milestone number of the plugin. See Plugin Milestones for more info.
  • The config lines define this plugin’s configuration options.
  • The register method is called per plugin instantiation. Do any of your initialization here.

Required modules

All plugins should require the Logstash module.

require 'logstash/namespace'

Plugin name

Every plugin must have a name set with the config_name method. If this is not specified plugins will fail to load with an error.

Milestones

Every plugin needs a milestone set using milestone. See <../plugin-milestones> for more info.

Config lines

The config lines define configuration options and are constructed like so:

config :host, :validate => :string, :default => "0.0.0.0"

The name of the option is specified, here :host and then the attributes of the option. They can include :validate, :default, :required (a Boolean true or false), and :deprecated (also a Boolean).

Inputs

All inputs require and extend the LogStash::Inputs::Base class, like so:

require 'logstash/inputs/base'
...

class LogStash::Inputs::YourPlugin < LogStash::Inputs::Base
...

Inputs have two methods: register and run.

  • Each input runs as its own thread.
  • The run method is expected to run-forever.

Filters

All filters require and extend the LogStash::Filters::Base class, like so:

require 'logstash/filters/base'
...

class LogStash::Filters::YourPlugin < LogStash::Filters::Base
...

Filters have two methods: register and filter.

  • The filter method gets an event.
  • Call event.cancel to drop the event.
  • To modify an event, simply make changes to the event you are given.
  • The return value is ignored.

Outputs

All outputs require and extend the LogStash::Outputs::Base class, like so:

require 'logstash/outputs/base'
...

class LogStash::Outputs::YourPlugin < LogStash::Outputs::Base
...

Outputs have two methods: register and receive.

  • The receive method is called when an event gets pushed to your output

Example: a new filter

Learn by example how to [add a new filter to Logstash](example-add-a-new-filter)

«  Logstash Config Language     Input plugins  »