Contributing to Beats
editContributing to Beats
editIf you have a bugfix or new feature that you would like to contribute, please start by opening a topic on the forums. It may be that somebody is already working on it, or that there are particular issues that you should know about before implementing the change.
We enjoy working with contributors to get their code accepted. There are many approaches to fixing a problem and it is important to find the best approach before writing too much code.
The process for contributing to any of the Elastic repositories is similar.
Contribution Steps
edit- Please make sure you have signed our Contributor License Agreement. We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once.
- Send a pull request! Push your changes to your fork of the repository and submit a pull request using our pull request guidelines. In the pull request, describe what your changes do and mention any bugs/issues related to the pull request. Please also add a changelog entry to CHANGELOG.next.asciidoc.
Adding a New Beat
editIf you want to create a new Beat, please read Creating a New Beat. You don’t need to submit the code to this repository. Most new Beats start in their own repository and just make use of the libbeat packages. After you have a working Beat that you’d like to share with others, open a PR to add it to our list of community Beats.
Setting Up Your Dev Environment
editThe Beats are Go programs, so install the 1.12.4 version of Go which is being used for Beats development.
After installing Go, set the
GOPATH environment variable to point to
your workspace location, and make sure $GOPATH/bin
is in your PATH.
The location where you clone is important. Make a directory structure under
GOPATH
that matches the URL used for Elastic repositories, then clone the
beats repository under the new directory:
mkdir -p ${GOPATH}/src/github.com/elastic git clone https://github.com/elastic/beats ${GOPATH}/src/github.com/elastic/beats
If you have multiple go paths, use ${GOPATH%%:*}
instead of ${GOPATH}
.
Then you can compile a particular Beat by using the Makefile. For example, for Packetbeat:
cd beats/packetbeat make
Some of the Beats might have extra development requirements, in which case you’ll find a CONTRIBUTING.md file in the Beat directory.
We use an EditorConfig file in the beats repository to standardise how different editors handle whitespace, line endings, and other coding styles in our files. Most popular editors have a plugin for EditorConfig and we strongly recommend that you install it.
Update scripts
editThe Beats use a variety of scripts based on Python to generate configuration files and documentation. The primary command used for this is:
make update
Another command properly formats go source files and adds a copyright header:
make fmt
These commands have the following dependencies:
- Python >= 2.7.9
- virtualenv for Python
Virtualenv can be installed with the command easy_install virtualenv
or pip
install virtualenv
. More details can be found
here. Both of these commands should be run before submitting a PR.
Testing
editYou can run the whole testsuite with the following command:
make testsuite
Running the testsuite has the following requirements:
- Python >= 2.7.9
- Docker >= 1.12
- Docker-compose >= 1.11
For more details check the Testing guide.
Documentation
editThe documentation for each Beat is located under {beatname}/docs
and is based
on asciidoc. After changing the docs, you should verify that the docs are still
building to avoid breaking the automated docs build. To build the docs run
make docs
. If you want to preview the docs for a specific Beat, run
make docs-preview
inside the folder for the Beat. This will automatically open
your browser with the docs for preview.
Dependencies
editTo manage the vendor/
folder we use
govendor. Please see
the govendor documentation on how to add or update vendored dependencies.
In most cases govendor fetch your/dependency@version +out
will get the job done.
Changelog
editTo keep up to date with changes to the official Beats for community developers, follow the developer changelog here.