IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Logstash Plugins Community Maintainer Guide Glossary of Terms »
Elastic Docs ›Logstash Reference [2.3] ›Contributing to Logstash

Submitting your plugin to RubyGems.org and the logstash-plugins repository

edit

Submitting your plugin to RubyGems.org and the logstash-plugins repository

edit

Logstash uses RubyGems.org as its repository for all plugin artifacts. Once you have developed your new plugin, you can make it available to Logstash users by simply publishing it to RubyGems.org.

Licensing

edit

Logstash and all its plugins are licensed under Apache License, version 2 ("ALv2"). If you make your plugin publicly available via RubyGems.org, please make sure to have this line in your gemspec:

  • s.licenses = ['Apache License (2.0)']

Publishing to RubyGems.org

edit

To begin, you’ll need an account on RubyGems.org

After creating an account, obtain an API key from RubyGems.org. By default, RubyGems uses the file ~/.gem/credentials to store your API key. These credentials will be used to publish the gem. Replace username and password with the credentials you created at RubyGems.org:

curl -u username:password https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
chmod 0600 ~/.gem/credentials

Before proceeding, make sure you have the right version in your gemspec file and commit your changes.

  • s.version = '0.1.0'

To publish version 0.1.0 of your new logstash gem:

bundle install
bundle exec rake vendor
bundle exec rspec
bundle exec rake publish_gem

Executing rake publish_gem:

  1. Reads the version from the gemspec file (s.version = '0.1.0')
  2. Checks in your local repository if a tag exists for that version. If the tag already exists, it aborts the process. Otherwise, it creates a new version tag in your local repository.
  3. Builds the gem
  4. Publishes the gem to RubyGems.org

That’s it! Your plugin is published! Logstash users can now install your plugin by running:

bin/logstash-plugin install logstash-output-mypluginname

Contributing your source code to logstash-plugins

edit

It is not required to contribute your source code to logstash-plugins github organization, but we always welcome new plugins!

Benefits

edit

Some of the many benefits of having your plugin in the logstash-plugins repository are:

  • Discovery Your plugin will appear in the Logstash Reference, where Logstash users look first for plugins and documentation.
  • Documentation Your plugin documentation will automatically be added to the Logstash Reference.
  • Testing With our testing infrastructure, your plugin will be continuously tested against current and future releases of Logstash. As a result, users will have the assurance that if incompatibilities arise, they will be quickly discovered and corrected.

Acceptance Guidelines

edit
  • Code Review Your plugin must be reviewed by members of the community for coherence, quality, readability, stability and security.
  • Tests Your plugin must contain tests to be accepted. These tests are also subject to code review for scope and completeness. It’s ok if you don’t know how to write tests — we will guide you. We are working on publishing a guide to creating tests for Logstash which will make it easier. In the meantime, you can refer to http://betterspecs.org/ for examples.

To begin migrating your plugin to logstash-plugins, simply create a new issue in the Logstash repository. When the acceptance guidelines are completed, we will facilitate the move to the logstash-plugins organization using the recommended github process.

« Logstash Plugins Community Maintainer Guide Glossary of Terms »