IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Get started with a custom Node.js stack API Reference »
Elastic Docs ›

Advanced Setup and Configuration

edit

Advanced Setup and Configuration

edit

Starting the agent

edit

The Elastic APM agent for Node.js needs to be started as the first thing in your application - before any other module is required/imported. This means that you should probably require and start it in your applications main file (usually index.js, server.js, or app.js).

There are two ways to start the Elastic APM agent for Node.js:

  • Require the elastic-apm-node module and call the start function on the returned agent:

    var apm = require('elastic-apm-node').start({
  // add configuration options here
})

  • Require the elastic-apm-node/start script:

    var apm = require('elastic-apm-node/start')

    If using this approach, you can’t configure the agent by passing in an options object, but instead have to rely on one of the other methods of configuration.

If you are using Babel, you need to use the elastic-apm-node/start approach. Read more.

Configuring the agent

edit

There are three ways to configure the Node.js agent:

  1. If calling the start function, you can supply a configurations object as the first argument. The option parameters given here will take precedence over config options provided by other means
  2. If a given config option is not provided in the call to the start function (or if requiring the elastic-apm-node/start script), the agent will look for the config option in the optional agent configuration file
  3. If a config option is not provided in any of the above means, the agent will look for its associated environment variable. You can see the expected names of these environment variables in the documentation for the start options below

For information on the available configuration properties, see the API reference.

Agent configuration file

edit

The Node.js agent will look for a file named elastic-apm-node.js in the current working directory. You can specify a custom path for this file using the ELASTIC_APM_CONFIG_FILE environment variable (this path must include the filename), e.g:

ELASTIC_APM_CONFIG_FILE=/path/to/elastic-apm-node.js

The configuration file is expected to export an object following the same conventions as the options object given as the first argument to the start function, e.g.:

module.exports = {
  // 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: ''
}

Babel / ES Modules support

edit

If you are using ES Modules, for instance with the help of Babel, all import statements are evaluated prior to calling any functions. In this case, you can’t configure the agent by passing a configuration object to the start function, as this call will happen after all of the modules have been loaded. Instead you need to import the elastic-apm-node/start module:

import apm from 'elastic-apm-node/start'

Now, you can either configure the agent using the environment variables associated with each config option, or use the optional agent configuration file.

« Get started with a custom Node.js stack API Reference »