A newer version is available. For the latest information, see the current release documentation.

« Components and documentation Quick start development environment »

›

Quick start guide

edit

Quick start guide

edit

This guide describes how to get started quickly with Elastic APM. You’ll learn how to:

Spin up Elasticsearch, Kibana, and APM Server on Elasticsearch Service
Install APM agents
Basic configuration options
Visualize your APM data in Kibana

Step 1: Spin up the Elastic Stack

edit

There’s no faster way to get started with Elastic APM than with our hosted Elasticsearch Service on Elastic Cloud. Elasticsearch Service is available on AWS, GCP, and Azure, and automatically configures APM Server to work with Elasticsearch and Kibana:

Get a free trial.
Log into Elastic Cloud.
Click Create deployment.
Select Elastic Observability and give your deployment a name.
Click Create deployment and copy the password for the elastic user.
Select APM from the menu on the left and make note of the APM endpoint and APM Server secret token. You’ll need these in step two.

To install and run Elasticsearch and Kibana, see getting started with the Elastic Stack.

Next, install, set up, and run APM Server:

Use the config file if you need to change the default configuration that APM Server uses to connect to Elasticsearch, or if you need to specify credentials:

Configuring APM Server
- General configuration options
- Configure the Elasticsearch output

If you change the listen address from localhost to something that is accessible from outside of the machine, we recommend setting up firewall rules to ensure that only your own systems can access the API. Alternatively, you can use a TLS and a secret token or API key.

If you have APM Server running on the same host as your service, you can configure it to listen on a Unix domain socket.

For detailed instructions on how to install and secure APM Server in your server environment, including details on how to run APM Server in a highly available environment, please see the full APM Server documentation.

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 URL, and Secret token or API key.

Service name: Service names are used to differentiate data from each of your services. Elastic APM includes the service name field on every document that it saves in Elasticsearch. If you change the service name after using Elastic APM, you will see the old service name and the new service name as two separate services. Make sure you choose a good service name before you get started.

The service name can only contain alphanumeric characters, spaces, underscores, and dashes (must match ^[a-zA-Z0-9 _-]+$).
APM Server URL: The host and port that APM Server listens for events on.
Secret token or API key: Authentication method for Agent/Server communication. See secure communication with APM Agents to learn more.

Select your service’s language for installation instructions:

Install the agent

Install the APM agent packages for Go.

go get go.elastic.co/apm

Configure the agent

Agents are libraries that run inside of your application process. APM services are created programmatically based on the executable file name, or the ELASTIC_APM_SERVICE_NAME environment variable.

# Initialize using environment variables:

# Set the service name. Allowed characters: a-z, A-Z, 0-9, -, _, and space.
# If ELASTIC_APM_SERVICE_NAME is not specified, the executable name will be used.
export ELASTIC_APM_SERVICE_NAME=

# Set custom APM Server URL. Default: http://localhost:8200.
export ELASTIC_APM_SERVER_URL=

# Use if APM Server requires a token
export ELASTIC_APM_SECRET_TOKEN=

Instrument your application

Instrument your Go application by using one of the provided instrumentation modules or by using the tracer API directly.

import (
	"net/http"

	"go.elastic.co/apm/module/apmhttp"
)

func main() {
	mux := http.NewServeMux()
	...
	http.ListenAndServe(":8080", apmhttp.Wrap(mux))
}

Learn more in the agent reference

Download the APM agent

Download the agent jar from Maven Central. Do not add the agent as a dependency to your application.

Start your application with the javaagent flag

Add the -javaagent flag and configure the agent with system properties.

Set required service name
Set custom APM Server URL (default: http://localhost:8200)
Set the base package of your application

java -javaagent:/path/to/elastic-apm-agent-<version>.jar \
     -Delastic.apm.service_name=my-application \
     -Delastic.apm.server_urls=http://localhost:8200 \
     -Delastic.apm.secret_token= \
     -Delastic.apm.application_packages=org.example \
     -jar my-application.jar

Learn more in the agent reference

Download the APM agent

Add the agent packages from NuGet to your .NET application. There are multiple NuGet packages available for different use cases.

For an ASP.NET Core application with Entity Framework Core, download the Elastic.Apm.NetCoreAll package. This package will automatically add every agent component to your application.

To minimize the number of dependencies, you can use the Elastic.Apm.AspNetCore package for just ASP.NET Core monitoring, or the Elastic.Apm.EfCore package for just Entity Framework Core monitoring.

If you only want to use the public agent API for manual instrumentation, use the Elastic.Apm package.

Add the agent to the application

For an ASP.NET Core application with the Elastic.Apm.NetCoreAll package, call the UseAllElasticApm method in the Configure method within the Startup.cs file:

public class Startup
{
  public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
    app.UseAllElasticApm(Configuration);
    //…rest of the method
  }
  //…rest of the class
}

Passing an IConfiguration instance is optional and by doing so, the agent will read config settings through this IConfiguration instance, for example, from the appsettings.json file:

{
    "ElasticApm": {
    "SecretToken": "",
    "ServerUrls": "http://localhost:8200", //Set custom APM Server URL (default: http://localhost:8200)
    "ServiceName" : "MyApp", //allowed characters: a-z, A-Z, 0-9, -, _, and space. Default is the entry assembly of the application
  }
}

If you don’t pass an IConfiguration instance to the agent, for example, in a non-ASP.NET Core application, you can configure the agent with environment variables. See the agent reference for more information.

Learn more in the agent reference

Install the APM agent

Install the APM agent for Node.js as a dependency to your application.

npm install elastic-apm-node --save

Configure the agent

Agents are libraries that run inside of your application process. APM services are created programmatically based on the serviceName. This agent supports a variety of frameworks but can also be used with your custom stack.

// 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 Server requires a token
  secretToken: '',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: ''
})

Learn more in the agent reference

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.

Configure the agent

Configure your agent inside of the php.ini file:

elastic_apm.server_url=http://localhost:8200
elastic_apm.secret_token=SECRET_TOKEN
elastic_apm.service_name="My-service"

Learn more in the agent reference

Django

Install the APM agent

Install the APM agent for Python as a dependency.

$ pip install elastic-apm

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 Server requires a token
  'SECRET_TOKEN': '',

  # Set custom APM Server URL (default: http://localhost:8200)
  'SERVER_URL': '',
}

# To send performance metrics, add our tracing middleware:
MIDDLEWARE = (
  'elasticapm.contrib.django.middleware.TracingMiddleware',
  #...
)

Flask

Install the APM agent

Install the APM agent for Python as a dependency.

$ pip install elastic-apm[flask]

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 Server requires a token
  'SECRET_TOKEN': '',

  # Set custom APM Server URL (default: http://localhost:8200)
  'SERVER_URL': '',
}

apm = ElasticAPM(app)

Learn more in the agent reference

Install the APM agent

Add the agent to your Gemfile.

gem 'elastic-apm'

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 Server requires a token
secret_token: ''

# Set custom APM Server URL (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
  require 'sinatra/base'

  class MySinatraApp < Sinatra::Base
    use ElasticAPM::Middleware

    # ...
  end

  ElasticAPM.start(
    app: MySinatraApp, # required
    config_file: '' # optional, defaults to config/elastic_apm.yml
  )

  run MySinatraApp

  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 Server requires a token
secret_token: ''

# Set custom APM Server URL (default: http://localhost:8200)
server_url: 'http://localhost:8200'

Learn more in the agent reference

Enable Real User Monitoring support in APM Server

APM Server disables RUM support by default. To enable it, set apm-server.rum.enabled: true in your APM Server configuration file.

Set up the agent

Once RUM support enabled, you can set up the RUM agent. There are two ways to do this: add the agent as a dependency, or set it up with <script> tags.

Set up the agent as a dependency

You can install the agent as a dependency to your application with npm install @elastic/apm-rum --save.

The agent can then be initialized and configured in your application like this:

import { init as initApm } from '@elastic/apm-rum'
var apm = initApm({

  // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space)
  serviceName: 'your-app-name',

  // Set custom APM Server URL (default: http://localhost:8200)
  serverUrl: '',

  // Set service version (required for source map feature)
  serviceVersion: ''
})

Framework integrations, like React or Angular, have custom dependencies. See framework integrations for more information.

Set up the agent with <script> tags

Alternatively, you can use <script> tags to set up and configure the agent. Add a <script> tag to the HTML page and use the elasticApm global object to load and initialize the agent. Don’t forget to download the latest version of the RUM agent from GitHub or UNPKG, and host the file on your Server/CDN before deploying to production.

<script src="https://your-cdn-host.com/path/to/elastic-apm-rum.umd.min.js" crossorigin></script>
<script>
  elasticApm.init({
    serviceName: 'your-app-name',
    serverUrl: 'http://localhost:8200',
  })
</script>

Learn more in the agent reference

Check the Agent/Server compatibility matrix to ensure you’re using agents that are compatible with your version of Elasticsearch.

Step 3: Advanced configuration (optional)

edit

There are many different ways to tweak and tune the Elastic APM ecosystem to your needs.

Configure APM agents

APM agents have a number of configuration options that allow you to fine tune things like environment names, sampling rates, instrumentations, metrics, and more. Broadly speaking, there are two ways to configure APM agents:

Central configuration allows you to fine-tune your agent configuration from within the APM app. Changes are automatically propagated to your APM agents, and there’s no need to redeploy.

A select number of configuration options are supported. See Agent configuration in Kibana for more information and a configuration reference.

Configure APM Server

If you’re running APM Server in Elastic cloud, you can configure your own user settings right in the Elasticsearch Service Console. Any changes are automatically appended to the apm-server.yml configuration file for your instance.

Full details are available in the APM user settings documentation.

If you’ve installed APM Server yourself, you can edit the apm-server.yml configuration file to make changes. More information is available in configuring APM Server.

Don’t forget to also read about securing APM Server, and monitoring APM Server.

Step 4: Visualize in Kibana

edit

The APM app in Kibana allows you to monitor your software services and applications in real-time; visualize detailed performance information on your services, identify and analyze errors, and monitor host-level and agent-specific metrics like JVM and Go runtime metrics.

To open the APM app:

Lauch Kibana:
1. Log in to your Elastic Cloud account.
2. Navigate to the Kibana endpoint in your deployment.
Point your browser to http://localhost:5601, replacing localhost with the name of the Kibana host.
In the side navigation, under Observability, select APM.

What’s next?

edit

Now that you have APM data streaming into Elasticsearch, head over to the APM app reference to learn more about what you can do with Kibana’s APM app.

« Components and documentation Quick start development environment »