Contributing to Beats

If 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. After committing your code, check out the Elastic Contributor Program where you can earn points and rewards for your contributions.

The process for contributing to any of the Elastic repositories is similar.

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.

The Beats are Go programs, so install the 1.17.10 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.

mkdir -p ${GOPATH}/src/github.com/elastic
git clone https://github.com/elastic/beats ${GOPATH}/src/github.com/elastic/beats

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.

The Beats use a variety of scripts based on Python, make and mage to generate configuration files and documentation. The primary command used for this is:

make update

Each Beat has its own update target, as well as a master update in the repository root. If a PR adds or removes a dependency, run make update in the root beats directory.

Another command properly formats go source files and adds a copyright header:

make fmt

Both of these commands should be run before submitting a PR. You can view all the available make targets with make help.

These commands have the following dependencies:

Python venv module is included in the standard library in Python 3. On Debian/Ubuntu systems it also requires to install the python3-venv package, that includes additional support scripts:

sudo apt-get install python3-venv

Beats is built using the make release target. By default, make will select from a limited number of preset build targets:

You can change build targets using the PLATFORMS environment variable. Targets set with the PLATFORMS variable can either be a GOOS value, or a GOOS/arch pair. For example, linux and linux/amd64 are both valid targets. You can select multiple targets, and the PLATFORMS list is space delimited, for example darwin windows will build on all supported darwin and windows architectures. In addition, you can add or remove from the list of build targets by prepending + or - to a given target. For example: +bsd or -darwin.

You can find the complete list of supported build targets with go tool dist list.

You can run the pre-configured linter against your change:

mage llc

llc stands for Lint Last Change which includes all the Go files that were changed in either the last commit (if you’re on the main branch) or in a difference between your feature branch and the main branch.

It’s expected that sometimes a contributor will be asked to fix linter issues unrelated to their contribution since the linter was introduced later than changes in some of the files.

You would need Mage to run this task.

You can run the whole testsuite with the following command:

make testsuite

Running the testsuite has the following requirements:

For more details check the Testing guide.

The 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 learn more about contributing docs, see the Docs HOWTO.

In order to create Beats we rely on Golang libraries and other external tools.

To manage the vendor/ folder we use go modules.

To update the contents of vendor/, run mage vendor.

Besides Go libraries, we are using development tools to generate parsers for inputs and processors.

The following packages are required to run go generate:

To keep up to date with changes to the official Beats for community developers, follow the developer changelog here.