Get started with traces and APM
editGet started with traces and APM
edit[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
Required role
The Admin role or higher is required to send APM data to Elastic. To learn more, refer to Assign user roles and privileges.
In this guide you’ll learn how to collect and send Application Performance Monitoring (APM) data to Elastic, then explore and visualize the data in real time.
Step 1: Add data
editYou’ll use APM agents to send APM data from your application to Elastic. Elastic offers APM agents written in several languages and supports OpenTelemetry. Which agent you’ll use depends on the language used in your service.
To send APM data to Elastic, you must install an APM agent and configure it to send data to your project:
- Create a new Observability project, or open an existing one.
-
To install and configure one or more APM agents, do one of following:
- In your Observability project, go to Add data → Monitor my application performance → Elastic APM and follow the prompts.
-
Use the following instructions:
1. Install the agent
Install the APM agent package using
go get
:go get -u go.elastic.co/apm/v2
2. Configure the agent
To simplify development and testing, the agent defaults to sending data to Elastic at
http://localhost:8200
. To send data to an alternative location, you must configureELASTIC_APM_SERVER_URL
.# The APM integration host and port export ELASTIC_APM_SERVER_URL= # If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the # executable name. For example, if your executable is called "my-app.exe", then your # service will be identified as "my-app". export ELASTIC_APM_SERVICE_NAME= # Secret tokens are used to authorize requests to the APM integration export ELASTIC_APM_SECRET_TOKEN=
3. Instrument your application
Instrumentation is the process of extending your application’s code to report trace data to Elastic APM. Go applications must be instrumented manually at the source code level. To instrument your applications, use one of the following approaches:
- Built-in instrumentation modules.
- Custom instrumentation and context propagation with the Go Agent API.
Learn more in the APM agent reference
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 a previous release 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
flagWhen 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.
Set up the APM agent
- Profiler runtime instrumentation: The agent supports auto instrumentation without any code change and without any recompilation of your projects. See Profiler auto instrumentation.
- NuGet packages: The agent ships as a set of NuGet packages available on nuget.org. You can add the Agent and specific instrumentations to a .NET application by referencing one or more of these packages and following the package documentation.
- Host startup hook: On .NET Core 3.0+ or .NET 5+, the agent supports auto instrumentation without any code change and without any recompilation of your projects. See Zero code change setup on .NET Core for more details.
Learn more in the APM agent reference
1. Install the APM agent
Install the APM agent for Node.js as a dependency to your application.
npm install elastic-apm-node --save
2. Initialization
It’s important that the agent is started before you require any other modules in your Node.js application - i.e. before
http
and before your router etc.This means that you should probably require and start the agent in your application’s main file (usually
index.js
,server.js
orapp.js
).Here’s a simple example of how Elastic APM is normally required and started:
// Add this to the VERY top of the first file loaded in your app var apm = require('elastic-apm-node').start({ // Override service name from package.json // Allowed characters: a-z, A-Z, 0-9, -, _, and space serviceName: '', // Use if APM integration requires a token secretToken: '', // Use if APM integration uses API keys for authentication apiKey: '', // Set custom APM integration host and port (default: http://127.0.0.1:8200) serverUrl: '', })
The agent will now monitor the performance of your application and record any uncaught exceptions.
Learn more in the APM agent reference
1. Install the agent
Install the PHP agent using one of the published packages.
To use the RPM Package (RHEL/CentOS and Fedora):
rpm -ivh <package-file>.rpm
To use the DEB package (Debian and Ubuntu):
dpkg -i <package-file>.deb
To use the APK package (Alpine):
apk add --allow-untrusted <package-file>.apk
If you can’t find your distribution, you can install the agent by building it from the source. The following instructions will build the APM agent using the same docker environment that Elastic uses to build our official packages.
The agent is currently only available for Linux operating system.
- Download the agent source.
- Execute the following commands to build the agent and install it:
cd apm-agent-php # for linux glibc - libc distributions (Ubuntu, Redhat, etc) export BUILD_ARCHITECTURE=linux-x86-64 # for linux with musl - libc distributions (Alpine) export BUILD_ARCHITECTURE=linuxmusl-x86-64 # provide a path to php-config tool export PHP_CONFIG=php-config # build extensions make -f .ci/Makefile build # run extension tests PHP_VERSION=`$PHP_CONFIG --version | cut -d'.' -f 1,2` make -f .ci/Makefile run-phpt-tests # install agent extensions sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/ext/elastic_apm-*.so `$PHP_CONFIG --extension-dir` # install automatic loader sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/loader/code/elastic_apm_loader.so `$PHP_CONFIG --extension-dir`
2. Enable and configure the APM agent
Enable and configure your agent inside of the
php.ini
file:extension=elastic_apm_loader.so elastic_apm.bootstrap_php_part_file=<repo root>/agent/php/bootstrap_php_part.php
Learn more in the APM agent reference
Django and Flask are two of several frameworks that the Elastic APM Python Agent supports. For a complete list of supported technologies, refer to the Elastic APM Python Agent documentation.
Django
$ pip install elastic-apm
1. Install the APM agent
Install the APM agent for Python as a dependency.
$ pip install elastic-apm
2. Configure the APM agent
Agents are libraries that run inside of your application process. APM services are created programmatically based on the
SERVICE_NAME
.# Add the agent to the installed apps INSTALLED_APPS = ( 'elasticapm.contrib.django', # ... ) ELASTIC_APM = { # Set required service name. Allowed characters: # a-z, A-Z, 0-9, -, _, and space 'SERVICE_NAME': '', # Use if APM integration requires a token 'SECRET_TOKEN': '', # Set custom APM integration host and port (default: http://localhost:8200) 'SERVER_URL': '', } # To send performance metrics, add our tracing middleware: MIDDLEWARE = ( 'elasticapm.contrib.django.middleware.TracingMiddleware', #... )
Flask
1. Install the APM agent
Install the APM agent for Python as a dependency.
$ pip install elastic-apm[flask]
2. Configure the APM agent
Agents are libraries that run inside of your application process. APM services are created programmatically based on the
SERVICE_NAME
.# initialize using environment variables from elasticapm.contrib.flask import ElasticAPM app = Flask(__name__) apm = ElasticAPM(app) # or configure to use ELASTIC_APM in your application settings from elasticapm.contrib.flask import ElasticAPM app.config['ELASTIC_APM'] = { # Set required service name. Allowed characters: # a-z, A-Z, 0-9, -, _, and space 'SERVICE_NAME': '', # Use if APM integration requires a token 'SECRET_TOKEN': '', # Set custom APM integration host and port (default: http://localhost:8200) 'SERVER_URL': '', } apm = ElasticAPM(app)
Learn more in the APM agent reference
1. Install the APM agent
Add the agent to your Gemfile.
gem 'elastic-apm'
2. Configure the agent
Ruby on Rails
APM is automatically started when your app boots. Configure the agent by creating the config file
config/elastic_apm.yml
:# config/elastic_apm.yml: # Set service name - allowed characters: a-z, A-Z, 0-9, -, _ and space # Defaults to the name of your Rails app service_name: 'my-service' # Use if APM integration requires a token secret_token: '' # Set custom APM integration host and port (default: http://localhost:8200) server_url: 'http://localhost:8200'
Rack
For Rack or a compatible framework, like Sinatra, include the middleware in your app and start the agent.
# config.ru app = lambda do |env| [200, {'Content-Type' => 'text/plain'}, ['ok']] end # Wraps all requests in transactions and reports exceptions use ElasticAPM::Middleware # Start an instance of the Agent ElasticAPM.start(service_name: 'NothingButRack') run app # Gracefully stop the agent when process exits. # Makes sure any pending transactions are sent. at_exit { ElasticAPM.stop }
Create a config file
config/elastic_apm.yml
:# config/elastic_apm.yml: # Set service name - allowed characters: a-z, A-Z, 0-9, -, _ and space # Defaults to the name of your Rack app's class. service_name: 'my-service' # Use if APM integration requires a token secret_token: '' # Set custom APM integration host and port (default: http://localhost:8200) server_url: 'http://localhost:8200'
Learn more in the APM agent reference
Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to Elastic.
For more information on how to combine Elastic and OpenTelemetry, refer to Use OpenTelemetry with APM.
While there are many configuration options, all APM agents require:
Option Description Service name
The APM integration maps an instrumented service’s name — defined in each APM agent’s configuration — to the index where its data is stored. Service names are case-insensitive and must be unique.
For example, you cannot have a service named
Foo
and another namedfoo
. Special characters will be removed from service names and replaced with underscores (_
).Server URL
The host and port that the managed intake service listens for events on.
To find the URL for your project:
- Go to the Cloud console.
- Next to your project, select Manage.
- Next to Endpoints, select View.
- Copy the APM endpoint.
API key
Authentication method for communication between APM agent and the managed intake service.
You can create and delete API keys in Applications Settings:
- Go to any page in the Applications section of the main menu.
- Click Settings in the top bar.
- Go to the Agent keys tab.
Environment
The name of the environment this service is deployed in, for example "production" or "staging".
Environments allow you to easily filter data on a global level in the UI. It’s important to be consistent when naming environments across agents.
- If you’re using the step-by-step instructions in the UI, after you’ve installed and configured an agent, you can click Check Agent Status to verify that the agent is sending data.
To learn more about APM agents, including how to fine-tune how agents send traces to Elastic, refer to Send APM data to Elastic.
Step 2: View your data
editAfter one or more APM agents are installed and successfully sending data, you can view application performance monitoring data in the UI.
In the Applications section of the main menu, select Services. This will show a high-level overview of the health and general performance of all your services.
Learn more about visualizing APM data in View and analyze traces.
Not seeing any data? Find helpful tips in Troubleshooting.
Next steps
editNow that data is streaming into your project, take your investigation to a deeper level. Learn how to use Elastic’s built-in visualizations for APM data, alert on APM data, or fine-tune how agents send traces to Elastic.