Get started with application traces and APM

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]" 
}

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" 
}

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:

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:

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

The .NET agent can be added to an application in a few different ways:

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.

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

Learn more in the agent reference

1. Install the APM agent

Add the agent to your Gemfile.

gem 'elastic-apm'

2. Configure the agent

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.