mirror of
https://github.com/elastic/logstash.git
synced 2025-06-29 02:03:30 -04:00
0de53939e9
* Breaking change to codec.encode method * Sink output for discarding events * URI and password config types * Utility methods for packaging Java plugins * Plugin API validation, fix gemspec generation * Plugin Jar validation * Update developer documentation * Update codec metrics for new encode method * Beta: Isolated classloaders for Java plugins * Address code review comments Fixes #10620
83 lines
3.5 KiB
Text
83 lines
3.5 KiB
Text
[float]
|
|
=== Package and deploy
|
|
|
|
Java plugins are packaged as Ruby gems for dependency management and
|
|
interoperability with Ruby plugins. Once they are packaged as gems, they may
|
|
be installed with the `logstash-plugin` utility just as Ruby plugins are.
|
|
Because no knowledge of Ruby or its toolchain should be required for Java
|
|
plugin development, the procedure for packaging Java plugins as Ruby gems
|
|
has been automated through a custom task in the Gradle build file provided
|
|
with the example Java plugins. The following sections describe how to
|
|
configure and execute that packaging task as well as how to install the
|
|
packaged Java plugin in Logstash.
|
|
|
|
[float]
|
|
==== Configuring the Gradle packaging task
|
|
|
|
The following section appears near the top of the `build.gradle` file supplied
|
|
with the example Java plugins:
|
|
|
|
[source,java]
|
|
[subs="attributes"]
|
|
-----
|
|
// ===========================================================================
|
|
// plugin info
|
|
// ===========================================================================
|
|
group 'org.logstashplugins' // must match the package of the main plugin class
|
|
version "${file("VERSION").text.trim()}" // read from required VERSION file
|
|
description = "Example Java filter implementation"
|
|
pluginInfo.licenses = ['Apache-2.0'] // list of SPDX license IDs
|
|
pluginInfo.longDescription = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using \$LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"
|
|
pluginInfo.authors = ['Elasticsearch']
|
|
pluginInfo.email = ['info@elastic.co']
|
|
pluginInfo.homepage = "http://www.elastic.co/guide/en/logstash/current/index.html"
|
|
pluginInfo.pluginType = "filter"
|
|
pluginInfo.pluginClass = "JavaFilterExample"
|
|
pluginInfo.pluginName = "java_filter_example"
|
|
// ===========================================================================
|
|
-----
|
|
|
|
You should configure the values above for your plugin.
|
|
|
|
* The `version` value will be automatically read from the `VERSION` file in the
|
|
root of your plugin's codebase.
|
|
* `pluginInfo.pluginType` should be set to one of `input`, `filter`, `codec`,
|
|
or `output`.
|
|
* `pluginInfo.pluginName` must match the name specified on the `@LogstashPlugin`
|
|
annotation on the main plugin class. The Gradle packaging task will validate
|
|
that and return an error if they do not match.
|
|
|
|
[float]
|
|
==== Running the Gradle packaging task
|
|
|
|
Several Ruby source files along with a `gemspec` file and a `Gemfile` are
|
|
required to package the plugin as a Ruby gem. These Ruby files are used only
|
|
for defining the Ruby gem structure or at Logstash startup time to register
|
|
the Java plugin. They are not used during runtime event processing. The
|
|
Gradle packaging task automatically generates all of these files based on
|
|
the values configured in the section above.
|
|
|
|
You run the Gradle packaging task with the following command:
|
|
|
|
[source,shell]
|
|
-----
|
|
./gradlew gem
|
|
-----
|
|
|
|
For Windows platforms: Substitute `gradlew.bat` for `./gradlew` as appropriate in the command.
|
|
|
|
That task will produce a gem file in the root directory of your
|
|
plugin's codebase with the name `logstash-{plugintype}-<pluginName>-<version>.gem`
|
|
|
|
[float]
|
|
==== Installing the Java plugin in Logstash
|
|
|
|
After you have packaged your Java plugin as a Ruby gem, you can install it in
|
|
Logstash with this command:
|
|
|
|
[source,shell]
|
|
-----
|
|
bin/logstash-plugin install --no-verify --local /path/to/javaPlugin.gem
|
|
-----
|
|
|
|
For Windows platforms: Substitute backslashes for forward slashes as appropriate in the command.
|