Docs
APM Node.js Agent Reference [3.x] » Troubleshooting
« Performance Tuning Upgrading »

Troubleshootingedit

Is something not working as expected? Don’t worry if you can’t figure out what the problem is; we’re here to help! As a first step, ensure your app is compatible with the agent’s supported technologies.

If you’re an existing Elastic customer with a support contract, please create a ticket in the Elastic Support portal. Other users can post in the APM discuss forum.

Please upload your complete debug logs to a service like GitHub Gist so that we can analyze the problem. Logs should include everything from when the application starts up until the first request executes. See Debug mode for more information.

No data is sent to the APM Serveredit

If neither errors nor 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 serviceNameedit
Elastic APM isn't correctly configured: Missing serviceName

Ensure that the agent is correctly configured with a serviceName 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 serviceName for details.

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

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

See the API documentation on serviceName for details.

No performance metrics sent to APM Serveredit

Errors get 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.

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, such as:

  • 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 for troubleshooting, perform these steps:

  1. Start your app with "trace"-level logging. This can be done by setting the environment variable ELASTIC_APM_LOG_LEVEL=trace or adding logLevel: 'trace' to the apm.start(options) call (see logLevel for details).
  2. Disable a possible custom logger config, because a custom logger can result in structured log data being lost. This can be done by setting the environment variable ELASTIC_APM_LOGGER=false.
  3. Send a few HTTP requests to some of the app endpoints and/or reproduce the issue you are seeing.
  4. Wait at least 10 seconds to allow the agent to try and connect to the APM Server (controlled by apiRequestTime).

For example:

ELASTIC_APM_LOG_LEVEL=trace ELASTIC_APM_LOGGER=false node app.js | tee -a apm-debug.log

If you are capturing debugging output for Elastic support, for help on the Elastic forums, or for a GitHub issue, please upload the complete debug output to a service like GitHub Gist so that we can analyze the problem.

Disable the Agentedit

In the unlikely event the agent causes disruptions to a production application, you can disable the agent while you troubleshoot.

To disable the agent, set active to false. You’ll need to restart your application for the changes to apply.

« Performance Tuning Upgrading »