mirror of
https://github.com/elastic/logstash.git
synced 2025-04-25 07:07:54 -04:00
104 lines
3 KiB
Text
104 lines
3 KiB
Text
= Extending Logstash
|
|
|
|
== Extending Logstash
|
|
|
|
You can add your own input, output, or filter plugins to Logstash.
|
|
|
|
If you're looking to extend Logstash today, please look at the existing plugins.
|
|
|
|
== Good examples of plugins
|
|
|
|
* https://github.com/logstash-plugins/logstash-input-tcp/blob/master/lib/logstash/inputs/tcp.rb[inputs/tcp]
|
|
* https://github.com/logstash-plugins/logstash-filter-multiline/blob/master/lib/logstash/filters/multiline.rb[filters/multiline]
|
|
* https://github.com/logstash-plugins/logstash-output-mongodb/blob/master/lib/logstash/outputs/mongodb.rb[outputs/mongodb]
|
|
|
|
== 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 config options.
|
|
* The `register` method is called per plugin instantiation. Do any of your initialization here.
|
|
|
|
=== Required modules
|
|
|
|
All plugins should require the Logstash module.
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
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:
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
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 the LogStash::Inputs::Base class:
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
require '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 the LogStash::Filters::Base class:
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
require '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 the LogStash::Outputs::Base class:
|
|
|
|
[source,js]
|
|
----------------------------------
|
|
require 'logstash/outputs/base'
|
|
----------------------------------
|
|
|
|
Outputs have two methods: `register` and `receive`.
|
|
|
|
* The `register` method is called per plugin instantiation. Do any of your initialization here.
|
|
* The `receive` method is called when an event gets pushed to your output
|
|
|
|
== Example: a new filter
|
|
|
|
Learn by example how to http://foo.com/example-add-a-new-filter[add a new filter to Logstash]
|
|
|
|
|