Instrument applications with APM
editInstrument applications with APM
editElastic APM monitors software services and applications in real time, collects unhandled errors and exceptions, and automatically picks up basic host-level metrics and agent specific metrics.
If you haven’t already, you need to install Elasticsearch for storing and searching your data, Kibana for visualizing and managing it, and APM Server. For more information, see Spin up the Elastic Stack.
Step 1: Install APM agents
editInstall 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
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.
Add the agent dependency to your project
Add the Elastic APM iOS Agent as a
package dependency
to your Xcode project or your Package.swift
:
Package( dependencies:[ .package(name: "iOSAgent", url: "git@github.com:elastic/apm-agent-ios.git", .branch("main")), ], targets:[ .target( name: "MyApp", dependencies: [ .product(name: "iOSAgent", package: "iOSAgent") ] ), ])
Initialize the agent
If you’re using SwiftUI
to build your app, add the following to App.swift
:
import SwiftUI import iOSAgent @main struct MyApp: App { init() { var config = AgentConfiguration() config.collectorAddress = "127.0.0.1" config.collectorPort = 8200 config.collectorTLS = false config.secretToken = "<secret token>" Agent.start(with: config) } var body: some Scene { WindowGroup { ContentView() } } }
APM Server URL or IP address |
|
APM Server port number |
|
Enable TLS for Open telemetry exporters |
|
Set secret token for APM server connection |
If you’re not using SwiftUI
, you can add the same thing to your AppDelegate file:
AppDelegate.swift
import UIKit import iOSAgent @main class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { var config = AgentConfiguration() config.collectorAddress = "127.0.0.1" config.collectorPort = 8200 config.collectorTLS = false config.secretToken = "<secret token>" Agent.start(with: config) return true } }
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
Step 2: Configure APM
editNow that you’re up and running with Elastic APM, you may want to adjust some configuration settings. Luckily, there are many different ways to tweak and tune the Elastic ecosystem to adapt it to your needs.
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.
For a full list of agent configuration options, see the relevant agent reference:
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 3: View your data in Kibana
editTo view the Observability Overview page:
-
Launch Kibana:
- Log in to your Elastic Cloud account.
- 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, select Observability, and click Overview.