[[creating-beat-from-metricbeat]]
=== Creating a Beat based on Metricbeat

The metricset Beat generator enables you to create a Beat that uses Metricbeat as a library and has your
own metricsets.

[float]
==== Requirements

To create your own Beat, you must have Go {go-version} or later installed, and the `$GOPATH`
must be set up correctly. In addition, the following tools are required:

* https://www.python.org/downloads/[python]
* https://docs.python.org/3/library/venv.html[python venv module]
* https://github.com/magefile/mage[mage]

Python venv module is already included in the standard library. In Ubuntu/Debian
it requires additional support scripts that can be installed with the
`python3-venv` package:

[source,bash]
----
sudo apt-get install python3-venv
----

[float]
==== Step 1 - Get the metricbeat source code

The first step is to get the metricbeat source code:

[source,bash]
----
go get github.com/elastic/beats/metricbeat
----

This will clone the beats repository into `GOPATH`. By default `go get`  fetches the master branch. To build your beat
on a specific version of libbeat, check out the specific branch ({branch} in the example below):

["source","sh",subs="attributes"]
----
cd ${GOPATH}/src/github.com/elastic/beats
git checkout {branch}
----

Note: If you have multiple go paths use `${GOPATH%%:*}`instead of `${GOPATH}`.

Now change to the directory where you want to create the beat.
This directory is normally located under `$GOPATH/src/github.com/{your-github-name}`. Inside this directory, run the command to create the beat.


[float]
==== Step 2 - Create the Beat

Run the command from the root `beats` directory:

[source,bash]
----
NEWBEAT_TYPE=metricbeat mage GenerateCustomBeat
----

When prompted, enter the Beat name and path, along with an initial module and metricset name for your beat. For more details about creating a metricset, see the docs <<creating-metricsets>>.

After creating the Beat, change the directory to `$GOPATH/src/github.com/{your-github-name}/{beat}`


[float]
==== Step 3 - Build & Run

To create a binary run the `make` command. This will create the binary in your beats directory.

To run it, execute the binary. This will automatically load the default configuration which was generated by `make update`.

[source,bash]
----
./beatname -e -d "*"
----

This will run the beat with debug output enabled to the console to directly see what is happening. Stop the beat with `CTRL-C`.

[float]
==== Step 4 - Package

To create packages and binaries for different platforms, https://www.docker.com/[docker] is required.
The first step is to get the most recent packaging tools into your beat:

[source,bash]
----
make release
----

This will fetch the most recent packaging tools and start the packaging of your beat. This can take a little bit longer.

For more details about creating a metricset, see the docs about <<creating-metricsets>>.
