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 serviceName
edit
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 serviceName
edit
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
orapp.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:
-
Start your app with "trace"-level logging. This can be done by setting the
environment variable
ELASTIC_APM_LOG_LEVEL=trace
or addinglogLevel: 'trace'
to theapm.start(options)
call (seelogLevel
for details). -
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 variableELASTIC_APM_LOGGER=false
. - 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
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.