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.
Updating to latest agent versionedit
The Elastic Node.js APM Agent is updated frequently and releases are not strongly tied to other components in the Elastic Stack. Therefore, updating to the most recently released agent version is often the recommended first troubleshooting step.
See upgrading documentation for more details.
To capture enough information for troubleshooting, perform these steps:
Start your app with "trace"-level logging. This can be done by setting the
logLevel: 'trace'to the
Disable a possible custom
loggerconfig, because a custom logger can result in structured log data being lost. This can be done by setting the environment variable
- Send a few HTTP requests to some of the app endpoints and/or reproduce the issue you are seeing.
Wait at least 10 seconds to allow the agent to try and connect to the APM
Server (controlled by
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.
No data is sent to the APM Serveredit
If there is no data for your service in the Kibana APM app, check the log output for messages like the following.
The most common source of problems are connection issues between the agent and
the APM server. Look for a log message of the form
APM Server transport error ....
APM Server transport error (ECONNREFUSED): connect ECONNREFUSED 127.0.0.1:8200
These may indicate an issue with the agent configuration (see
apiKey), a network problem between agent and server, or
that the APM server is down or misconfigured (see
the APM server troubleshooting docs).
Also look for error messages starting with
Elastic APM .... Some examples:
Elastic APM agent disabled (`active` is false)
This indicates that you have likely set the
active option or the
ELASTIC_APM_ACTIVE environment variable to
false. See the
active configuration variable docs.
Elastic APM is incorrectly configured: serverUrl "..." contains an invalid port! (allowed: 1-65535)
No metrics or trace data is sent to APM Serveredit
Errors get tracked just fine, but you don’t see any performance metrics or trace data.
Make sure that the agent is both required and started at the very top of your main app file (usually the
It’s important that the agent is started before any other modules are
`require`d. 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.
See Start gotchas for a number of possible surprises in correctly starting the APM agent when used with some compilers or bundlers.
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
You’ll need to restart your application for the changes to apply.