Troubleshootingedit

No data is sent to the APM Serveredit

If neither errors or performance metrics are being sent to the APM Server, it’s a good idea to first check your log file and look for output just as the app starts.

Explanation of error messagesedit

Agent Inactiveedit
Elastic APM agent is inactive due to configuration

You’ve most likely set the active option or the ELASTIC_APM_ACTIVE environment variable to false. Ensure that it’s set to true and try again.

See the API documentation about active for details.

Missing appNameedit
Elastic APM isn't correctly configured: Missing appName

Ensure that the agent is correctly configured with an appName config option either by passing it to the start() function, by specifying it in the optional configuration file, or by using environment variables.

See the API documentation on appName for details.

Invalid appNameedit
Elastic APM isn't correctly configured: appName "..." contains invalid characters! (allowed: a-z, A-Z, 0-9, _, -, <space>)

The appName you provided contained invalid characters. You can only use the the letters a-z (both upper and lowercase), numbers, underscore (_), hyphen (-), and space (` `).

See the API documentation on appName for details.

No performance metrics sent to APM Serveredit

Errors gets tracked just fine, but you don’t see any performance metrics.

First make sure you have the latest version of the Elastic APM Node.js agent. Issues are fixed and support for new metrics are added all the time, so make sure you keep your dependency up to date.

If you are using the latest version but still don’t see any performance metrics, make sure that the agent is both required and started at the very top of your main app file (usually the index.js, server.js or app.js file). It’s important that the agent is started before any other modules are required. If not, the agent will not be able to hook into any modules and will not be able to measure the performance of your application.

Important

If you are using Babel / ES modules in your application, make sure you have read about the Babel / ES Module support.

If this is not the issue, your app dependencies might be incompatible with the agent. Please create a new topic in the Elastic APM discuss forum and try to include as much information as possible, e.g:

  • The dependencies in you package.json file
  • Your app’s main js file showing how the agent is initialized (usually the index.js, server.js or app.js file)
  • Your server logs with Elastic APM debugging enabled

Debug modeedit

To enable agent debugging and capture enough information, perform these steps:

  1. Start your app with the environment variable DEBUG=elastic-apm
  2. Send a few HTTP requests to some of the app endpoints
  3. Wait at least one minute to allow the agent to try and connect to the APM Server