Step 2: Set up and configureedit

Elastic Cloudedit

If you’re running APM Server in Elastic cloud, you can configure your own user settings right in the Elasticsearch Service Console. Any changes are automatically appended to the apm-server.yml configuration file for your instance.

Full details are available in the APM user settings documentation.

Self installationedit

It is recommend that you run the setup command before starting APM Server.

The setup command sets up the initial environment, including the Elasticsearch index template, and ILM write alias. In Elasticsearch, index templates are used to define field settings and mappings.

The Kibana APM UI relies on specific mappings. Changing the default mapping or failing to setup the initial mapping may break the APM UI.

The recommended index template file for APM Server is installed by the APM Server packages. To see the template that comes bundled with APM Server, run apm-server export template. If you accept the default configuration, APM Server will load the template automatically after successfully connecting to Elasticsearch. If a template already exists, it will not be overwritten unless you’ve explicitly configured APM Server to do so. Running apm-server -e setup template will force a template overwrite.

Index templates cannot be applied retroactively. They are only applied at index creation time. Changing a template will have no impact on existing indices. This means you need to ensure the correct index template is loaded from day one.

Full details on the setup command are below:

apm-server setup [FLAGS]


-h, --help
Shows help for the setup command.
Sets up components related to Elasticsearch index management including template, ILM policy, and write alias (if supported and configured).
Registers the pipeline definitions set in ingest/pipeline/definition.json.
[7.2] Deprecated in 7.2. Sets up the index template only. It is recommended to use --index-management instead.
[7.2] Deprecated in 7.2. Sets up the index lifecycle management policy. It is recommended to use --index-management instead.

Also see Global flags.


apm-server setup --index-management
apm-server setup --pipelines

Once APM Server has been set up, you can edit the apm-server.yml configuration file to customize it to your needs. The location of this file varies by platform, but the Directory layout will help you locate it. All available configuration options are outlined in configuring APM Server.