Get started with traces and APM

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 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=

# API keys are used to authorize requests to the APM integration
export ELASTIC_APM_API_KEY=

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:

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:

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

Set up the APM agent

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 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: '',

  // API keys are used to authorize requests to the APM integration
  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.

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': '',

  # API keys are used to authorize requests to the APM integration
  'API_KEY': '',

  # 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': '',

  # API keys are used to authorize requests to the APM integration
  'API_KEY': '',

  # 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'

# API keys are used to authorize requests to the APM integration
api_key: ''

# 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'

# API keys are used to authorize requests to the APM integration
api_key: ''

# 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 OpenTelemetry.