Get started with application traces and APM

edit

This guide describes how to:

  • Collect Application Performance Monitoring (APM) data
  • Send APM data to the Elastic Stack
  • Explore and visualize the data in real-time

For feedback and questions, please contact us in the discuss forum.

Prerequisites

edit

To follow the steps in this guide, you need an Elastic Stack deployment that includes:

  • Elasticsearch for storing and searching data
  • Kibana for visualizing and managing data
  • Kibana user with All privileges on Fleet and Integrations. Since many Integrations assets are shared across spaces, users need the Kibana privileges in all spaces.
  • Integrations Server (included by default in every Elasticsearch Service deployment)

To get started quickly, spin up a deployment of our hosted Elasticsearch Service. The Elasticsearch Service is available on AWS, GCP, and Azure. Try it out for free.

Step 1: Configure the APM integration

edit

Elastic Cloud runs a hosted version of Integrations Server that includes the APM integration.

  1. In Kibana, navigate to Fleet > Agent policies and select the Elastic Cloud agent policy. This is the default agent policy for Elastic Agents hosted on Elastic Cloud.

    Elastic Cloud agent policy
  2. Next to Elastic APM in the Actions column, select Edit integration to configure the APM integration.

    Edit the APM integration
  3. Make a note of the predefined URL that the APM Server is listening on—​you’ll need this in the next step.
  4. If you made any changes to your configuration, click save and continue.

Step 2: Install APM agents

edit

APM agents are written in the same language as your service. To monitor a new service, you must install the agent and configure it with a service name, APM Server host, and Secret token.

  • Service name: The APM integration maps an instrumented service’s name–defined in each APM agent’s configuration– to the index that its data is stored in Elasticsearch. Service names are case-insensitive and must be unique. For example, you cannot have a service named Foo and another named foo. Special characters will be removed from service names and replaced with underscores (_).
  • APM Server URL: The host and port that APM Server listens for events on. This should match the host and port defined when setting up the APM integration.
  • Secret token: Authentication method for APM agent and APM Server communication. This should match the secret token defined when setting up the APM integration.

You can edit your APM integration settings if you need to change the APM Server URL or secret token to match your APM agents.

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 3: View your data

edit

Back in Kibana, under Observability, select APM. You should see application performance monitoring data flowing into the Elastic Stack!

The built-in apm_user role is not compatible with the APM integration as it only provides read access to apm-* indices. For a list of indices users need access to, refer to APM data streams

APM app with data

Not seeing any data? Review our list of common problems for helpful tips.

What’s next?

edit
  • Now that data is streaming into the Elastic Stack, take your investigation to a deeper level! Use Elastic Observability to unify your logs, metrics, uptime, and application performance data.
  • Want to protect your endpoints from security threats? Try Elastic Security. Adding endpoint protection is just another integration that you add to the agent policy!
  • Are your eyes bleary from staring at a wall of screens? Create alerts and find out about problems while sipping your favorite beverage poolside.
  • Want Elastic to do the heavy lifting? Use machine learning to detect anomalies.
  • Got everything working like you want it? Roll out your agent policies to other hosts by deploying Elastic Agents across your infrastructure!