Skip to content


Repository files navigation

ci Smoke Tests Package status

APM Server

The APM Server receives data from Elastic APM agents and transforms it into Elasticsearch documents. Read more about Elastic APM at

For questions and feature requests, visit the discussion forum.

Getting Started

To get started with APM, see our Quick start guide.

APM Server Development


  • Go 1.22.x


  • Fork the repo with the GitHub interface and clone it:
git clone[USER]/apm-server.git

Note that it should be cloned from the fork (replace [USER] with your GitHub user), not from origin.

  • Add the upstream remote:
git remote add elastic


To build the binary for APM Server run the command below. This will generate a binary in the same directory with the name apm-server.


If you make code changes, you may also need to update the project by running the additional command below:

make update


To run APM Server with debugging output enabled, run:

./apm-server -c apm-server.yml -e -d "*"

APM Server expects index templates, ILM policies, and ingest pipelines to be set up externally. This should be done by installing the APM integration. When running APM Server directly, it is only necessary to install the integration and not to run an Elastic Agent.


You can also run APM Server in a containerized environment using Tilt.

tilt up

See dev docs testing for additional information.


For Testing check out the testing guide


To clean up the build directory and generated artifacts, run:

make clean


See contributing for details about reporting bugs, requesting features, or contributing to APM Server.


See releases for an APM Server release checklist.

Updating dependencies

APM Server uses Go Modules for dependency management, without any vendoring.

In general, you should use standard go get commands to add and update modules. The one exception to this is the dependency on libbeat, for which there exists a special Make target: make update-beats, described below.

Updating libbeat

By running make update-beats the module will be updated to the most recent commit from the main branch, and a minimal set of files will be copied into the apm-server tree.

You can specify an alternative branch or commit by specifying the BEATS_VERSION variable, such as:

make update-beats BEATS_VERSION=7.x
make update-beats BEATS_VERSION=f240148065af94d55c5149e444482b9635801f27

Updating go-elasticsearch

It is important to keep the go-elasticsearch client in sync with the according major version. We also recommend to use the latest available client for minor versions.

You can use go get -u -m to update to the latest commit on the 7.x branch.


To build all apm-server packages from source, run:

make package

This will fetch and create all images required for the build process. The whole process can take several minutes. When complete, packages can be found in build/distributions/.

Building docker packages

To customize image configuration, see the docs.

To build docker images from source, run:

make package-docker

When complete, Docker images can be found at build/distributions/*.docker.tar.gz, and the local Docker image IDs are written at build/docker/*.txt.

Building pre-release images can be done by running make package-docker-snapshot instead.


Documentation for the APM Server can be found in the Observability guide's APM section. Most documentation files live in the elastic/observability-docs repo's docs/en/observability/apm/ directory.

However, the following content lives in this repo: