Get started with application traces and APM
editGet started with application traces and APM
editThis 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
editTo 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
editElastic Cloud runs a hosted version of Integrations Server that includes the APM integration.
-
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.
-
Next to Elastic APM in the Actions column, select Edit integration to configure the APM integration.
- Make a note of the predefined URL that the APM Server is listening on—you’ll need this in the next step.
- If you made any changes to your configuration, click save and continue.
Step 2: Install APM agents
editAPM 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 namedfoo
. 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.
1. Add the agent to your project
First, add the Elastic APM agent plugin to your application’s build.gradle
file as shown below:
// Android app's build.gradle file plugins { id "com.android.application" id "co.elastic.apm.android" version "[latest_version]" }
The Elastic plugin declaration must be added below the Android app plugin declaration ( |
2. Configure the agent
After adding the agent plugin, configure it. A minimal configuration sets the Elastic APM integration endpoint as shown below:
// Android app's build.gradle file plugins { //... id "co.elastic.apm.android" version "[latest_version]" } elasticApm { // Minimal configuration serverUrl = "https://your.elastic.server" // Optional serviceName = "your app name" serviceVersion = "0.0.0" apiKey = "your server api key" secretToken = "your server auth token" }
You can find the latest version in the Gradle plugin portal. |
|
Defaults to your |
|
Defaults to your |
|
Defaults to null. More info on API Keys here. |
|
Defaults to null. |
When both secretToken
and apiKey
are provided, apiKey has priority and secretToken is ignored.
3. Initialize the agent
After syncing your project with the Gradle changes above, the Elastic APM agent needs to be initialized within your Application class. This example shows the simplest way to configure the agent:
// Your Application class class MyApp extends android.app.Application { @Override public void onCreate() { super.onCreate(); ElasticApmAgent.initialize(this); } }
All that’s left is to compile and run your application. That’s it!
Learn more in the agent reference
Read more in the APM Android Agent Reference.
1. Install the agent
Install the Elastic APM Go 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 the Elastic APM integration at http://localhost:8200
.
To send data to an alternative location, you must configure ELASTIC_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 agent reference
1. Add the agent dependency to your project
Add the Elastic APM iOS Agent to your Xcode project or your Package.swift
.
Here are instructions for adding a package dependency to a standard Xcode project.
Refer to Add a Dependency on Another Swift Package for details about adding dependencies to your Package.swift
.
Here is a helpful code-snippet:
Package( dependencies:[ .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios.git", from: "1.0.0"), ], targets:[ .target( name: "MyApp", dependencies: [ .product(name: "ElasticApm", package: "apm-agent-ios") ] ), ])
2. Initialize the agent
If you’re using SwiftUI
to build your app, add the following to your App.swift
:
import SwiftUI import ElasticApm class AppDelegate : NSObject, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { var config = AgentConfigBuilder() .withServerUrl(URL(string:"http://127.0.0.1:8200")) .withSecretToken("<SecretToken>") .build() ElasticApmAgent.start(with: config) return true } } @main struct MyApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate init() { } var body: some Scene { WindowGroup { ContentView() } } }
If you’re not using SwiftUI
, you can alternatively add the same thing to your AppDelegate.swift
file:
import UIKit import ElasticApm @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { var config = AgentConfigBuilder() .withServerUrl(URL(string:"http://127.0.0.1:8200")) .withSecretToken("<SecretToken>") .build() ElasticApmAgent.start(with: config) return true } }
Learn more in the agent reference
Read more in the APM iOS 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 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 extraapm-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
The .NET agent can be added to an application in a few different ways:
- 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 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
or app.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 agent reference
1. Install the agent
Install the agent using one of the packages for supported platforms.
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 from https://github.com/elastic/apm-agent-php/.
- 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 agent reference
- Django
-
1. Install the APM agent
Install the APM agent for Python as a dependency.
$ pip install elastic-apm
2. Configure the 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 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 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
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 agent reference
1. Enable Real User Monitoring (RUM)
RUM is disabled by default. Enable it by setting Enable RUM
to true
.
2. Set up the agent
Set up the agent with <script>
tags or by using a bundler.
Synchronous / Blocking Pattern
Add a <script> tag to load the bundle and use the elasticApm
global
object to initialize the agent:
<script src="https://<your-cdn-host>.com/path/to/elastic-apm-rum.umd.min-<version>.js" crossorigin></script> <script> elasticApm.init({ serviceName: '<instrumented-app>', serverUrl: '<apm-server-url>', }) </script>
Asynchronous / Non-Blocking Pattern
Loading the script asynchronously ensures the agent script will not block other
resources on the page, however, it will still block browsers onload
event.
<script> ;(function(d, s, c) { var j = d.createElement(s), t = d.getElementsByTagName(s)[0] j.src = 'https://<your-cdn-host>.com/path/to/elastic-apm-rum.umd.min-<version>.js' j.onload = function() {elasticApm.init(c)} t.parentNode.insertBefore(j, t) })(document, 'script', {serviceName: '<instrumented-app>', serverUrl: '<apm-server-url>'}) </script>
Using Bundlers
Install the Real User Monitoring APM agent as a dependency to your application:
npm install @elastic/apm-rum --save
Configure the agent:
import { init as initApm } from '@elastic/apm-rum' const apm = initApm({ // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space) serviceName: '', // Set custom APM integration host and port (default: http://localhost:8200) serverUrl: 'http://localhost:8200', // Set service version (required for sourcemap feature) serviceVersion: '' })
Learn more in the agent reference
Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the Elastic Stack.
For more information on how to combine Elastic and OpenTelemetry, see OpenTelemetry integration.
Step 3: View your data
editBack 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
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!