Get started with Expressedit

Getting Elastic APM set up for your Express app is easy, and there are various ways you can tweak it to fit your needs.

Follow the guide below and refer to the API documentation for all the advanced stuff.


Add the elastic-apm module as a dependency to your application:

npm install elastic-apm --save


It’s important that the agent is started before you require any other modules in your Node.js application - i.e. before express, http, 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 Express example with the Elastic APM agent installed:

// Add this to the VERY top of the first file loaded in your app
var apm = require('elastic-apm').start({
  // Set required app name (allowed characters: a-z, A-Z, 0-9, -, _, and space)
  appName: '',

  // Use if APM Server requires a token
  secretToken: '',

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

var app = require('express')()

app.get('/', function (req, res) {
  res.send('Hello World!')

// any errors caught by Express can be logged by the agent as well


The agent will now monitor the performance of your Express application and record any uncaught exceptions.

Advanced configurationedit

In the above example we initialize the agent by calling the start() function. This function takes an optional options object used to configure the agent. Any option not supplied via the options object can instead be configured using environment variables. So if you prefer, you can set the same configuration options using environment variables:


And then just start the agent like so:

// Start the agent before any thing else in your app
var apm = require('elastic-apm').start()

See all possible ways to configure the agent in the API documentation.

Full documentationedit

Performance monitoringedit

Elastic APM automatically measures the performance of your Express application. It records traces for database queries, external HTTP requests, and other slow operations that happen during requests to your Express app.

By default the agent will trace the most common modules. To trace other events, you can use custom traces. For information about custom traces, see the Custom Traces section.

Traces are grouped in transactions - by default one for each incoming HTTP request. But it’s possible to create custom transactions not associated with an HTTP request. See the Custom Transactions section for details.

Unknown routesedit

When viewing the performance metrics of your application in Elastic APM, you might see some transactions named "unknown route". This indicates that the agent detected an incoming HTTP request to your application, but didn’t know which route in your Express app the HTTP request matched.

This might simply be 404 requests, which by definition don’t match any route, or it might be a symptom that the agent wasn’t installed correctly. If you see this or can’t get any meaningful metrics to show up, please follow the Troubleshooting Guide.

Error loggingedit

The Node.js agent will by default watch for uncaught exceptions and log these with Elastic APM. But in most cases you also want to log non-thrown errors. This section explains how.

Express error handlersedit

Express works by funneling all incoming http requests through a series of middleware functions (one of which being your router). If an error is either thrown synchronously inside one of the middleware functions or is passed as the first argument to the middleware next() function, it will be passed to the Express error handler.

In the case where you have multiple Express error handlers, the Elastic APM error handler should be the first in the chain to ensure that it will receive the error correctly.

var apm = require('elastic-apm').start()
var express = require('express')

var app = express()

// Your regular middleware and router...

// Add the Elastic APM middleware after your regular middleware

// ...but before any other error handler
app.use(function (err, req, res, next) {
  // Custom error handling goes here

Manual error loggingedit

By default the Node.js agent will watch for uncaught exceptions and send them to Elastic APM automatically. But in most cases errors are not thrown but returned via a callback, caught by a promise, or simply manually created. Those errors will not automatically be sent to Elastic APM. To manually send an error to Elastic APM, simply call apm.captureError() with the error:

var err = new Error('Ups, something broke!')


For advanced logging of errors, including adding extra metadata to the error, see the API documentation.

Ignore "404 Not Found" errorsedit

By default Express will treat http requests that do not match any route as an error. This is a good idea in development, but usually not something you want in production. To avoid sending "404 Not Found" errors to Elastic APM, make sure you handle those before they reach the Elastic APM middleware:

// Your regular middleware and router...

// Put a catch-all route handler as the very last route handler
app.use(function (req, res) {
  // If we reach this point it means that no prior route matched.
  // This means that we should render a "404 Not Found" page. Notice
  // that we do not call next() here as we don't want to forward the
  // request to the error handler below.

  // Send a 404 to the user
  res.status(404).send('This isn\'t the page you\'re looking for..')

// After the 404 Not Found handler, add the Elastic APM error handler

Filter sensitive informationedit

By default the Node.js agent will filter common sensitive information before sending errors and metrics to the Elastic APM server.

It’s possible for you to tweak these defaults or remove any information you don’t want to send to Elastic APM:

  • By default the Node.js agent will not log the body of HTTP requests. To enable this, use the logBody config option
  • By default the Node.js agent will filter certain HTTP headers known to contain sensitive information. To disable this, use the filterHttpHeaders config option
  • To apply custom filters, use the apm.addFilter() function

Add your own dataedit

The Node.js agent will keep track of the active HTTP request and will link it to errors and recorded transaction metrics when they are sent to the Elastic APM server. This allows you to see details about which request resulted in a particular error or which requests cause a certain HTTP endpoint to be slow.

But in many cases, information about the HTTP request itself isn’t enough. To add even more metadata to errors and transactions, use one of the two functions below:

  • apm.setUserContext() - Call this to enrich collected performance data and errors with information about the user/client
  • apm.setCustomContext() - Call this to enrich collected performance data and errors with any information that you think will help you debug performance issues and errors (this data is only stored, but not indexed in Elasticsearch)
  • apm.setTag() - Call this to enrich collected performance data and errors with simple key/value strings that you think will help you debug performance issues and errors (tags are indexed in Elasticsearch)


See the Compatibility section for details.


If you can’t get the Node.js agent to work as expected, please follow the Troubleshooting Guide.