Node.js Troubleshooting Framework Configuration

General Configuration Troubleshooting

  1. Confirm the app is receiving traffic, has been for at least 5 min, and continues to receive traffic during troubleshooting.

  2. Run the Diagnostics CLI to collect data then validate:

    1. Confirm Node.js and NPM version meets requirements.
    2. Verify host information meets requirements.
    3. Verify the existence of newrelic module in the package.json/package-lock.json
    4. Check top level npm ls dependencies for newrelic module.
    5. Check if the newrelic.js file is copied to the root directory of the application as described in step 3 of our install documentation.
    6. Ensure configuration is valid with a license key and app name.
    7. Check for the existence of agent logs in default path.
    8. Check that agent can connect to the New Relic collector.
    9. Verify agent isn’t an EOL version.
    10. Check for a “reporting to” line in the logs.
    11. Check that High Security Mode settings for the application and account match.
  3. Look at the newrelic.js file and make sure the configuration options you want enabled are there and formatted correctly.

    1. While you are here, check that the exports line isexports.config = {... and NOT exports.config = () => ({... The latter is a function call and is usually there if the default.js was edited instead of copying and editing the base newrelic.js.
  4. Are you using Server Side Configuration settings? Anything set via SSC will override all other config options for the agent.

    1. Once enabled, SSC can only be disabled by support.
  5. If you used New Relic environment variables for configuration.

    1. Check where you store environment variables, such as in an .env file.

    2. command line: env | grep NEW_RELIC_ or printenv

    3. Use console.log(process.env) before require(newrelic); to make sure the env vars are correctly loading in time

    4. All Node agent New Relic ENV variables start with NEW_RELIC_, confirm these are set correctly.

    5. Every standard config option has an ENV variable option, except for these two: NEW_RELIC_NO_CONFIG and NEW_RELIC_HOME

      1. If NEW_RELIC_NO_CONFIG_FILE=true, make sure that you have all the required ENV variable configuration equivalents. Ex: app_name, license_key, etc.
      2. If NEW_RELIC_HOME is set, make sure that the newrelic.js file is in the path it specifies.
  6. Ensure you are using a supported Node.js framework.

  7. Look through trace logs and make sure the configuration is reaching New Relic.

    1. You’ll usually see the configuration settings in a giant log entry that follows a “Posting to” message.
  8. If you are using Lambda, review our Lambda documentation.

Advanced Configuration Troubleshooting

Docker Configuration

  1. Make sure you have installed the Node.js agent correctly in a Docker container
  2. Check your Dockerfile, package.json and the ENV variables you are using. Make sure they are aligned with the above doc.

Browser Injection Configuration

  1. Check to see if the browser snippet is being injected and showing in a pages source code by searching for NREUM. If not, check the console for errors mentioned in the docs.
  2. Ensure you have called newrelic.getBrowserTimingheader() at the beginning of your html page’s head tag.
  3. Check and make sure that your html template has access to the New Relic module. Examples can be found in our docs.
  4. Review Browser troubleshooting framework

Proxy Issues

  1. Check configuration for any proxy settings and ensure they are formatted correctly.
  2. Verify that you included https or http as required by your proxy. These need to be included or else there will be a connection issue.
  3. Try having the entire proxy under the proxy configuration value. Sometimes issues occur when a you uses the separate config options (usually because of formatting nuances).
  4. If the config options look normal then you will likely need to contact your network admin for more help.

Distributed Tracing/CAT

  1. The number one issue with DT is formatting the configuration option incorrectly in your newrelic.js. It needs to looks like this:
distributed_tracing: {

enabled: true,

  1. Ensure all applications that should communicate have DT enabled and are using the latest version of the agent.

Transaction Trace Configuration

  1. Transaction Trace reporting is enabled by default

  2. If Transaction Traces are not reporting:

    1. Confirm tracer_enabled is set to true

    2. Confirm that the transaction_threshold is set low enough to capture queries. Use the below queries to help determine what to set this value at. Be aware these queries return milliseconds and transaction_threshold is set in seconds

      1. For traces to be captured, there needs to be Transactions where the maximum duration exceeds your transaction_threshold. It is recommended to set this value above the average duration to ensure you are capturing transaction duration outliers:
SELECT average(duration) AS 'Average', max(duration) AS 'Max' FROM Transaction WHERE (appName = '<application name as reported in New Relic>') SINCE 1 week ago TIMESERIES MAX
  1. The first query ‘Max’ value will only show the duration of the slowest Transaction in the time window, in order to get more context on the range of durations, you can use the below query:
SELECT percentile(duration, 50, 75, 95) FROM Transaction WHERE (appName = '<application name as reported in New Relic>') SINCE 1 week ago TIMESERIES MAX
  1. If you would like to increase or decrease the diversity of requests eligible for transaction traces, you can configure the top_n. This defines the maximum number of requests eligible for transaction traces grouped by request name.
    1. To record the absolute slowest transaction over the last minute, you can set top_n: 0 or top_n: 1. However, this causes one very slow route to dominate your transaction traces.

Database Reporting Configuration

  1. Datastore instance and name reporting is enabled by default

  2. If Slow queries or explain plans are not reporting:

    1. Confirm the slow query configuration is enabled and record_sql is set to either obfuscated or raw
      1. Before changing the record_sql configuration, review the Security and Transaction Traces document
    2. Confirm no security settings are preventing data from being captured
    3. Confirm that the explain_threshold is set low enough to capture queries.
      1. Database operation duration needs to exceed the threshold to be eligible for slow queries to be captured:
SELECT max(apm.service.datastore.operation.duration) FROM Metric WHERE (entity.guid = '<add app entity.guid here>') FACET `datastoreType`, `operation` SINCE 1 month ago TIMESERIES MAX
  1. Configuring Slow Queries
    1. To increase the number of queries captured, raise the max_samples value. This raises the upper limit of slow queries the agent can capture per minute before beginning sampling, but will not guarantee this number of queries will be captured as Transaction and Database operation duration still needs to exceed the threshold in order to be eligible for a slow query
      1. Warning: Raising this limit will increase memory usage as the agent will be storing more data between 60 second harvest cycles
    2. Configure the minimum query duration for a transaction to be eligible for a slow query with the explain_threshold configuration. Use the below query to find average query duration which you can use to help determine what value to set your threshold at. In order to capture duration outliers, you will want the threshold to exceed the average:
SELECT average(apm.service.datastore.operation.duration) FROM Metric WHERE (entity.guid = '<add app entity.guid here>') FACET `datastoreType`, `operation` SINCE 1 month ago TIMESERIES MAX

Naming Rules

You can group your own transaction names using this config option. You must format the regex correctly and put the options in the correct order. Our docs have a good example of how to use this. Be mindful to not create a Metric Grouping Issue


  1. There’s a great explanation of attributes for the Node.js agent in our docs.
  2. Check the related EventType in Insights for the attribute to see if it exists and troubleshoot from there.