New Relic Node preload order and MongoDB trace-verification boundary
Parent: New Relic Integration · Published reference · snapshot 2026-11-02
↓ Facts as markdownall context files
Source-anchored research for New Relic Node preload order and MongoDB trace-verification boundary. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Problems, failure modes and limitations
- New Relic directs applications to preload the Node agent with `node -r newrelic ./dist/server.js`; when startup flags cannot be controlled, place `require('newrelic')` first in the main module, before other packages. Late loading can prevent proper instrumentation. New Relic warns that the first-line fallback causes instrumentation issues with Babel or a similar transpiler. (medium confidence) (verified as of 2026-11-02) [source 1] [source 2]
- For an ESM application that uses a configuration file, New Relic requires changing its extension from `.js` to `.cjs` because the CommonJS agent reads the file with `require()`; otherwise startup can fail with `ERR_REQUIRE_ESM`. (low confidence) (verified as of 2026-11-02) [source 1] [source 2]
- New Relic documents that `newrelic.instrumentLoadedModule` is unsupported for ESM: ESM bindings cannot be assigned, preventing replacement of exports after loading. Do not plan an ESM verification procedure around retrofitting this API after imports. (low confidence) (verified as of 2026-11-02) [source 1] [source 2]
- In the MongoDB issue opened on Nov 4, 2025, the reporter said the application continued working while instrumentation failed and MongoDB metrics were not collected; the reported error was `TypeError: Cannot read properties of undefined (reading 'prototype')`. A maintainer requested runnable reproduction code on Jan 23, 2026, then closed the issue on Mar 3, 2026 and invited reopening with a reproduction. These are attributed observations, and that closure does not establish a released instrumentation fix or a general compatibility rule. (low confidence) [source]
Facts and statements
- For ESM applications, New Relic requires the ESM loader together with the agent: `node --import newrelic/esm-loader.mjs -r newrelic ./dist/server.js`. Loading the agent alone does not fulfill this documented ESM bootstrap requirement. The ESM setup page labels this instrumentation experimental and warns that breaking changes can occur while its loader dependency is experimental. (medium confidence) (verified as of 2026-11-02) [source 1] [source 2] [source 3] [source 4]
- The pinned Node release 22.14.0 CLI documents that modules preloaded with --require run before modules preloaded with --import. Repeated import preloads execute sequentially in order, beginning with those supplied in NODE_OPTIONS. The option order shown in New Relic examples does not reverse that runtime ordering. (medium confidence) [source 1] [source 2] [source 3]
- New Relic instructs users to generate application traffic and wait a few minutes for APM data. Its troubleshooting guide warns that short-lived tests may exit before data is reported and that configuration, framework or Apdex settings can explain missing transaction traces. The default agent log is newrelic_agent.log in the application directory unless logging settings have changed. (medium confidence) (verified as of 2026-11-02) [source 1] [source 2]
- In a separate ESM issue, rChaoz reported an empty database tab despite manually created `newrelic.startSegment()` segments. A maintainer explained that recording database segments and attributes requires appropriate shim methods. The reporter later named SvelteKit and Prisma. This attributed exchange illustrates the distinction between custom segments and database telemetry; it does not establish MongoDB or Mongoose version support. (low confidence) [source]
Children
- No children recorded.