Configuring and running APM Server

In a production environment, you would put APM Server on its own machines, similar to how you run Elasticsearch. You can run it on the same machines as Elasticsearch, but this is not recommended, as the processes will be competing for resources.

To start APM Server, run:

./apm-server -e

You should see APM Server start up. It will try to connect to Elasticsearch on localhost port 9200 and expose an API to agents on port 8200. You can change the defaults by supplying a different address on the command line:

./apm-server -e -E output.elasticsearch.hosts=ElasticsearchAddress:9200 -E apm-server.host=localhost:8200

Or you can update the apm-server.yml configuration file to change the defaults.

apm-server:
  host: localhost:8200

output:
  elasticsearch:
    hosts: ElasticsearchAddress:9200

See apm-server.reference.yml for more configuration options.

APM Server exposes a HTTP endpoint and as with anything that opens ports on your servers, you should be careful about who can connect to it. We recommend using firewall rules to ensure only authorized systems can connect.

There is also the option of setting up SSL to ensure data sent to the APM Server is encrypted.

To enable SSL/TLS you need a private key and a certificate issued by a certification authority (CA). Then you can specify the path to those files in the configuration properties apm-server.ssl.key and apm-server.ssl.certificate respectively. This will make the APM Server to serve HTTPS requests instead of HTTP. Hence, you also need to enable SSL in the agent. For agent specific details, please check the {apm-agent-ref}/index.html[agent documentation] for how to do it.

You can configure a secret token which is sent with every request from the APM agents to the server. This string is used to ensure that only your agents can send data to your APM servers. Both the agents and the APM servers have to be configured with the same secret token.

The API exposed by APM Server is a regular HTTP JSON API. To achieve high availability, you can place multiple instances of APM Server behind a regular HTTP load balancer, for example HAProxy or nginx.

If an instance of APM Server should fail, the load balancer will remove it from the load balancing rotation after a short period of time.

APM Server endpoint /healthcheck always returns a HTTP 200. You can configure your load balancer to send HTTP requests to this endpoint to determine if a given APM Server is up and running.

APM Server maintains a small buffer internally. Data coming from agents is kept here until it can be delivered to Elasticsearch. Under normal circumstance, data is forwarded to Elasticsearch immediately. In situations in which Elasticsearch is down briefly or in situations where there is a sudden influx of data and Elasticsearch cannot ingest it all at once, the buffer acts as a temporary storage until the data can be ingested by Elasticsearch.

This also means that if a given APM Server process fails, for example because the machine its running on experiences an issue, the data that has not yet been forwarded to Elasticsearch is lost.

The same APM Server process can handle data from multiple apps. If you want to send data from each app to separate indices, you can include the app name in the Elasticsearch index pattern in the following manner:

output.elasticsearch:
  index: "apm-%{[app.name]}-%{[beat.version]}-%{+yyyy.MM.dd}"

This will have the effect that all events end up in app-specific indices. It will enable you to set security restrictions based on your index pattern.