APM Server binary

edit

This guide will explain how to set up and configure the APM Server binary.

Prerequisites
edit

First, see the Elastic Support Matrix for information about supported operating systems and product compatibility.

You’ll need:

  • Elasticsearch for storing and indexing data.
  • Kibana for visualizing with the Applications UI.

We recommend you use the same version of Elasticsearch, Kibana, and APM Server. See Installing the Elastic Stack for more information about installing these products.

Install Elastic APM yourself
Step 1: Install
edit

Before you begin: If you haven’t installed the Elastic Stack, do that now. See Learn how to install the Elastic Stack on your own hardware.

To download and install APM Server, use the commands below that work with your system. If you use apt or yum, you can install APM Server from our repositories to update to the newest version more easily.

See our download page for other installation options, such as 32-bit images.

deb:

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.17.0-amd64.deb
sudo dpkg -i apm-server-8.17.0-amd64.deb

RPM:

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.17.0-x86_64.rpm
sudo rpm -vi apm-server-8.17.0-x86_64.rpm

Other Linux:

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.17.0-linux-x86_64.tar.gz
tar xzvf apm-server-8.17.0-linux-x86_64.tar.gz

Mac:

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-8.17.0-darwin-x86_64.tar.gz
tar xzvf apm-server-8.17.0-darwin-x86_64.tar.gz

Windows:

  1. Download the APM Server Windows zip file from the downloads page.
  2. Extract the contents of the zip file into C:\Program Files.
  3. Rename the apm-server-<version>-windows directory to APM-Server.
  4. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select Run As Administrator). If you are running Windows XP, you may need to download and install PowerShell.
  5. From the PowerShell prompt, run the following commands to install APM Server as a Windows service:

    PS > cd 'C:\Program Files\APM-Server'
    PS C:\Program Files\APM-Server> .\install-service.ps1

If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service.ps1.

Docker:

See Running on Docker for deploying Docker containers.

Step 2: Set up and configure
edit

Configure APM by editing the apm-server.yml configuration file. The location of this file varies by platform—​see the Installation layout for help locating it.

A minimal configuration file might look like this:

apm-server:
  host: "localhost:8200" 
output.elasticsearch:
  hosts: ["localhost:9200"] 
  username: "elastic" 
  password: "changeme"

The host:port APM Server listens on.

The Elasticsearch host:port to connect to.

This example uses basic authentication. The user provided here needs the privileges required to publish events to Elasticsearch. To create a dedicated user for this role, see Create a writer role.

All available configuration options are outlined in configuring APM Server.

Step 3: Start
edit

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

The -e global flag enables logging to stderr and disables syslog/file output. Remove this flag if you’ve enabled logging in the configuration file. For Linux systems, see APM Server status and logs.

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 in apm-server.yml or by supplying a different address on the command line:

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

For Debian package and RPM installations, we recommend the apm-server process runs as a non-root user. Therefore, these installation methods create an apm-server user which you can use to start the process. In addition, APM Server will only start if the configuration file is owned by the user running the process.

To start the APM Server in this case, run:

sudo -u apm-server apm-server [<argument...>]

By default, APM Server loads its configuration file from /etc/apm-server/apm-server.yml. See the deb & rpm default paths for a full directory layout.

Step 4: Install APM agents
edit

Manually set up and configure the agent with the -javaagent JVM option. No application code change is required, but this requires an application restart. See below for more information on this setup method.

1. Download the APM agent

The first step in getting started with the Elastic APM Java agent is to retrieve a copy of the agent JAR. Java agent releases are published to Maven central. In order to get a copy you can either:

  • download the latest agent or previous releases from Maven central.
  • download with curl:

    curl -o 'elastic-apm-agent.jar' -L 'https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=co.elastic.apm&a=elastic-apm-agent&v=LATEST'

2. Add -javaagent flag

When starting your application, add the JVM flag -javaagent:/path/to/elastic-apm-agent-<version>.jar

3. Configure

Different application servers have different ways of setting the -javaagent flag and system properties. Start your application (for example a Spring Boot application or other embedded servers) and add the -javaagent JVM flag. Use the -D prefix to configure the agent using system properties:

java -javaagent:/path/to/elastic-apm-agent-<version>.jar -Delastic.apm.service_name=my-cool-service -Delastic.apm.application_packages=org.example,org.another.example -Delastic.apm.server_url=http://127.0.0.1:8200 -jar my-application.jar

Refer to Manual setup with -javaagent flag to learn more.

Alternate setup methods

  • Automatic setup with apm-agent-attach-cli.jar
    Automatically set up the agent without needing to alter the configuration of your JVM or application server. This method requires no changes to application code or JVM options, and allows attaching to a running JVM. Refer to the Java agent documentation for more information on this setup method.
  • Programmatic API setup to self-attach
    Set up the agent with a one-line code change and an extra apm-agent-attach dependency. This method requires no changes to JVM options, and the agent artifact is embedded within the packaged application binary. Refer to the Java agent documentation for more information on this setup method.
Step 5: View your data
edit

Once you have at least one APM agent sending data to APM Server, you can start visualizing your data in the Kibana Applications UI.

Applications UI with data
Repositories for APT and YUM
edit

We have repositories available for APT and YUM-based distributions. Note that we provide binary packages, but no source packages.

We use the PGP key D88E42B4, Elasticsearch Signing Key, with fingerprint

4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4

to sign all our packages. It is available from https://pgp.mit.edu.

APTedit

To add the apm-server repository for APT:

  1. Download and install the Public Signing Key:

    wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
  2. You may need to install the apt-transport-https package on Debian before proceeding:

    sudo apt-get install apt-transport-https
  3. Save the repository definition to /etc/apt/sources.list.d/elastic-8.x.list:

    echo "deb https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-8.x.list

    To add the Elastic repository, make sure that you use the echo method shown in the example. Do not use add-apt-repository because it will add a deb-src entry, but we do not provide a source package.

    If you have added the deb-src entry by mistake, you will see an error like the following:

    Unable to find expected entry 'main/source/Sources' in Release file (Wrong sources.list entry or malformed file)

    Simply delete the deb-src entry from the /etc/apt/sources.list file, and the installation should work as expected.

  4. Run apt-get update, and the repository is ready for use. For example, you can install APM Server by running:

    sudo apt-get update && sudo apt-get install apm-server
  5. To configure APM Server to start automatically during boot, run:

    sudo systemctl enable apm-server
YUMedit

To add the apm-server repository for YUM:

  1. Download and install the public signing key:

    sudo rpm --import https://packages.elastic.co/GPG-KEY-elasticsearch
  2. Create a file with a .repo extension (for example, elastic.repo) in your /etc/yum.repos.d/ directory and add the following lines:

    [elastic-8.x]
    name=Elastic repository for 8.x packages
    baseurl=https://artifacts.elastic.co/packages/8.x/yum
    gpgcheck=1
    gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
    enabled=1
    autorefresh=1
    type=rpm-md

    Your repository is ready to use. For example, you can install APM Server by running:

    sudo yum install apm-server
  3. To configure APM Server to start automatically during boot, run:

    sudo systemctl enable apm-server
Run APM Server on Docker
edit

Docker images for APM Server are available from the Elastic Docker registry. The base image is ubuntu:22.04.

A list of all published Docker images and tags is available at www.docker.elastic.co.

These images are free to use under the Elastic license. They contain open source and free commercial features and access to paid commercial features. Start a 30-day trial to try out all of the paid commercial features. See the Subscriptions page for information about Elastic license levels.

Pull the imageedit

Obtaining APM Server for Docker is as simple as issuing a docker pull command against the Elastic Docker registry and then, optionally, verifying the image.

  1. Pull the Docker image:

    docker pull docker.elastic.co/apm/apm-server:8.17.0

    Alternately, you can use the hardened Wolfi image.

    docker pull docker.elastic.co/apm/apm-server-wolfi:8.17.0
  2. Verify the Docker image:

    wget https://artifacts.elastic.co/cosign.pub
    cosign verify --key cosign.pub docker.elastic.co/apm/apm-server:8.17.0

    The cosign command prints the check results and the signature payload in JSON format:

    Verification for docker.elastic.co/apm/apm-server:8.17.0 --
    The following checks were performed on each of these signatures:
      - The cosign claims were validated
      - Existence of the claims in the transparency log was verified offline
      - The signatures were verified against the specified public key
Configure APM Server on Dockeredit

The Docker image provides several methods for configuring APM Server. The conventional approach is to provide a configuration file via a volume mount, but it’s also possible to create a custom image with your configuration included.

Example configuration fileedit

Download this example configuration file as a starting point:

curl -L -O https://raw.githubusercontent.com/elastic/apm-server/8.17/apm-server.docker.yml
Volume-mounted configurationedit

One way to configure APM Server on Docker is to provide apm-server.docker.yml via a volume mount. With docker run, the volume mount can be specified like this.

docker run -d \
  -p 8200:8200 \
  --name=apm-server \
  --user=apm-server \
  --volume="$(pwd)/apm-server.docker.yml:/usr/share/apm-server/apm-server.yml:ro" \
  docker.elastic.co/apm/apm-server:8.17.0 \
  --strict.perms=false -e \
  -E output.elasticsearch.hosts=["elasticsearch:9200"]  

Substitute your Elasticsearch hosts and ports.

If you are using the hosted Elasticsearch Service in Elastic Cloud, replace the -E output.elasticsearch.hosts line with the Cloud ID and elastic password using the syntax shown earlier.

Customize your configurationedit

The apm-server.docker.yml downloaded earlier should be customized for your environment. See Configure APM Server for more details. Edit the configuration file and customize it to match your environment then re-deploy your APM Server container.

Custom image configurationedit

It’s possible to embed your APM Server configuration in a custom image. Here is an example Dockerfile to achieve this:

FROM docker.elastic.co/apm/apm-server:8.17.0
COPY --chmod=0644 --chown=1000:1000 apm-server.yml /usr/share/apm-server/apm-server.yml