Related Pages

Related topics: Instrumentation Framework and Subscribers, OpenTelemetry, Hybrid Agent, and Modern Runtimes, AI/LLM Monitoring and Modern Integrations

Overview and Core Architecture

The newrelic Node.js agent instruments application code to collect performance metrics, traces, and events for the New Relic observability platform. The repository bundles a runtime loader, a configuration system, a metric/transaction engine, and dozens of package-specific instrumentation modules (called "shims" and "subscribers") that activate when the host application requires or imports a supported dependency. Source: README.md:1-12.

The published newrelic npm package targets Node.js >=22 and ships a focused set of entry points: index.js, api.js, stub_api.js, newrelic.js, load-externals.js, and esm-loader.mjs. Source: package.json:50-60. The package's optional dependencies include @newrelic/native-metrics, @newrelic/fn-inspect, @datadog/pprof, and @prisma/prisma-fmt-wasm, which are used for native profiling, function inspection, continuous profiling, and Prisma schema parsing respectively. Source: package.json:80-86.

High-Level Architecture

The agent is structured around three cooperating layers:

1. Bootstrap & Configuration Layer — Loads newrelic.js (or an environment-supplied config), resolves environment variables, and instantiates the Agent object.
2. Instrumentation Layer — A pluggable registry of shim modules and subscribers that hook into Node.js core APIs and third-party packages. Each module declares a functionQuery (which symbol to wrap) and an instrumentation callback. Source: lib/subscribers/README.md:5-30.
3. Telemetry Layer — Collects metrics (per-recorder), segments, transactions, and spans, then normalizes them via OpenTelemetry semantic-convention constants and transformation rules before shipping to the collector.

flowchart TB
  App[Host Application] -->|require/import newrelic| Loader[index.js / newrelic.js]
  Loader --> Config[Configuration System]
  Loader --> Agent[Agent Instance]
  Agent --> Shims[Shim Registry]
  Agent --> Subs[Subscriber Registry]
  Shims --> Core[lib/instrumentation/core/*]
  Shims --> Pkg[Package-Specific Shims]
  Subs --> Otel[OpenTelemetry Bridge]
  Subs --> Aws[AWS SDK v3 Subscriber]
  Subs --> Kfk[KafkaJS Subscriber]
  Otel --> Rules[Transformation Rules JSON]
  Otel --> Collector[New Relic Collector]
  Shims --> Collector
  Subs --> Collector

Source: lib/instrumentation/core/timers.js:7-15, lib/subscribers/aws-sdk/send.js:11-30, lib/otel/traces/segments/utils.js:1-20.

Instrumentation Patterns

The agent uses two complementary wrapping mechanisms. The legacy shim model wraps core modules (for example, timers.js patches setTimeout, setInterval, and clearTimeout on both the timers module and global, then attaches a RecorderSpec to each call). Source: lib/instrumentation/core/timers.js:9-20. The newer subscriber model is declarative: each subscriber exports a configuration object identifying the target module by name, versionRange, and filePath, plus a functionQuery (e.g., className/methodName or moduleName/expressionName) and a kind of Sync or Async. Source: lib/subscribers/README.md:5-42.

Metric recorders are tiny, single-purpose functions. The middleware recorder, for example, reads both inclusive and exclusive segment durations and records them under a scoped and unscoped metric name. Source: lib/metrics/recorders/middleware.js:9-20. A KafkaJS helper similarly records per-broker produce/consume counts under a stable MessageBroker/Kafka/Nodes/<broker>/<Produce|Consume>/<topic> namespace. Source: lib/subscribers/kafkajs/utils/record-linking-metrics.js:1-22.

OpenTelemetry Integration

The agent can ingest OpenTelemetry spans and convert them into New Relic segments through a transformation-rules engine. Each rule (a JSON file under lib/otel/traces/transformation-rules/) declares a matcher (required span kinds and attribute keys) and a segment template. Rule 499-FallbackProducer.json matches any span with kind=producer and emits a MessageBroker/unknown/unknown/Produce segment when no other rule applies. Source: lib/otel/traces/transformation-rules/499-FallbackProducer.json:1-14. Rule 312-OtelHttpClient1_23.json demonstrates attribute remapping: it renames server.address to the segment host, url.full to the URL, and produces a segment name via the template External/${host}${path}. Source: lib/otel/traces/transformation-rules/312-OtelHttpClient1_23.json:1-30.

Trace context is propagated bidirectionally. The helper propagateTraceContext reads spanContext() and parentSpanId from the active OTel span, constructs a W3C Traceparent object, and calls transaction.acceptTraceContextPayload on the local transaction, preserving the upstream traceState. Source: lib/otel/traces/segments/utils.js:11-25. Attribute names follow OpenTelemetry semantic conventions maintained in lib/otel/traces/constants.js. Source: lib/otel/traces/constants.js:1-25.

AWS SDK v3, Distributed Tracing, and Deployment Surfaces

The SmithyClientSendSubscriber is a single subscriber that hooks @smithy/smithy-client's Client.send() and dispatches service-specific middleware for BedrockRuntime, DynamoDB, Lambda, SNS, and SQS clients. Source: lib/subscribers/aws-sdk/send.js:1-30. The W3C distributed-tracing headers used for AWS propagation are enumerated in a single constant: ['traceparent', 'tracestate', 'newrelic']. Source: lib/subscribers/aws-sdk/utils/constants.js:1-5. SQS message attributes are bounded by AWS's 10-attribute limit, so attachHeaders reserves slots and inserts headers in priority order. Source: lib/subscribers/aws-sdk/utils/attach-headers.js:1-30.

For Azure App Service deployments, the repository ships a NuGet-distributed site extension that drops the agent into C:\home\site\wwwroot\node_modules and injects the NODE_OPTIONS preload variable via an applicationHost.xdt transform. Source: cloud-tooling/azure-site-extension/Content/README.md:1-20.

Runtime Compatibility and Known Gaps

The engines field pins Node.js >=22, so older LTS lines are unsupported. Source: package.json:25-30. Community-reported gaps include Prisma (which uses its own query engine rather than pg/mysql2, so its queries are not auto-instrumented), ESM configuration discovery (the loader looks for newrelic.js and does not yet auto-pick newrelic.cjs for "type": "module" projects), Bun runtime compatibility, native Next.js support (addressed in v14.1.0 via the Hybrid Agent), and Deno support. These are tracked in issues #991, #553, #1959, #904, and #1727 respectively.

See Also

• Configuration and Environment Variables
• Instrumentation Authoring Guide (Shims and Subscribers)
• OpenTelemetry Transformation Rules
• Distributed Tracing and W3C Trace Context
• AWS SDK v3 Instrumentation
• Azure Site Extension Deployment

Related Pages

Related topics: Overview and Core Architecture, OpenTelemetry, Hybrid Agent, and Modern Runtimes, AI/LLM Monitoring and Modern Integrations

Instrumentation Framework and Subscribers

Overview

The New Relic Node.js agent instruments Node applications through a layered framework that combines shims, subscribers, core instrumentations, and metric recorders. The framework allows the agent to automatically measure the performance of third-party modules (databases, message brokers, AWS SDK, GraphQL servers) and built-in Node.js modules (timers, fs) without requiring manual instrumentation from the application developer.

The minimum supported runtime is declared in package.json: node >= 22 and npm >= 6.0.0. This floor matters because subscribers rely on node:diagnostics_channel and orchestrion features that are only available in modern Node versions, and several community requests (such as #553 for ESM and #1959 for BunJS support) are directly constrained by this baseline. Source: package.json:28-31

Architecture

The framework is composed of cooperating layers that hook into a target module, extract timing and context information, and forward it to the agent's metrics engine.

graph LR
    A[Target Module<br/>e.g. kafkajs, fs, AWS SDK] --> B[Hook Layer<br/>require-in-the-middle /<br/>diagnostics_channel]
    B --> C[Subscriber or Core Init]
    C --> D[Segment / Transaction]
    C --> E[Metric Recorder]
    D --> F[Agent Metrics]
    E --> F
    F --> G[New Relic Backend]
    D --> H[OTEL Bridge]
    H --> G

Core instrumentations wrap built-in modules directly via the shim layer, while third-party instrumentations register subscribers that activate when the target module is require()d. The agent also runs an OpenTelemetry bridge that converts OTel spans into its own segment model, which is the mechanism behind the new native Next.js support shipped in v14.1.0.

Subscriber System

Subscribers are the primary extension point for adding new instrumentation. The contributor documentation states that all subscribers inherit from the base Subscriber class defined in lib/subscribers/base.js, with the exception of subscribers that hook into node:diagnostics_channel channels directly — those inherit from dc-base.js instead. Source: lib/subscribers/README.md:54-58

The framework defines specialized base classes for the most common categories:

• DbQuerySubscriber — for database query-level tracing (e.g. SQL execution)
• DbOperationSubscriber — for connection pool, transaction, and lifecycle operations
• MessageProducerSubscriber — for outgoing message queue publishing
• MessageConsumerSubscriber — for incoming message queue consumption
• PropagationSubscriber — for context propagation across AsyncLocalStorage boundaries

Source: lib/subscribers/README.md:62-70

Function Query Selectors

Each subscriber declares one or more function queries to identify the code being instrumented. Supported selectors include expressionName, functionName, className + methodName, and moduleName + expressionName. The kind property is set to Sync or Async to indicate whether the target function returns a promise. When code structure changes between versions, multiple query objects can be added to the same instrumentations array to cover both shapes. Source: lib/subscribers/README.md:78-86

AWS SDK v3 Subscriber

The SmithyClientSendSubscriber in lib/subscribers/aws-sdk/send.js demonstrates the modern subscriber pattern. It hooks a single Client.send call on @smithy/smithy-client and dispatches service-specific middleware from a middlewareByClient map covering BedrockRuntime, DynamoDB, DynamoDBDocument, Lambda, SNS, and SQS. This consolidation means a single hook covers every AWS SDK v3 client because they all extend @smithy/smithy-client.Client. Source: lib/subscribers/aws-sdk/send.js:10-32

For services that publish messages, the attachHeaders utility mutates the message's MessageAttributes to inject distributed-tracing headers. It enforces the AWS-imposed limit of 10 attributes per message and prioritizes header insertion in order so the most important headers survive when capacity is tight. Source: lib/subscribers/aws-sdk/utils/attach-headers.js:18-44

The set of propagated headers is centralized as a single constant: traceparent, tracestate, and newrelic. Source: lib/subscribers/aws-sdk/utils/constants.js:5-7

Kafka Subscriber Utilities

The Kafka instrumentation uses two helper recorders. recordLinkingMetrics increments a MessageBroker/Kafka/Nodes/<broker>/<Produce|Consume>/<topic> metric for every broker contacted during message production or consumption. Source: lib/subscribers/kafkajs/utils/record-linking-metrics.js:16-30

A separate recordMethodMetric utility records a generic call count using the KAFKA.PREFIX constant from the agent's metrics name registry. Source: lib/subscribers/kafkajs/utils/record-method-metric.js:7-15

Core Instrumentation Modules

Built-in Node.js modules are instrumented through dedicated initializers that use the shim's record and wrap helpers.

The timers initializer instruments setTimeout, setInterval, and clearTimeout on both the timers module and the global object. The wrappedClearTimeout function marks the corresponding segment as ignore = true so cancelled timers do not contribute to transaction duration. Source: lib/instrumentation/core/timers.js:20-47

The fs initializer records a large set of filesystem methods including rename, readFile, writeFile, and — on Node 22+ — glob. High-level and low-level variants are recorded separately to distinguish synchronous from asynchronous usage. Source: lib/instrumentation/core/fs.js:10-50

Metric Recorders

Metric recorders transform segment and transaction data into New Relic metric records. The framework ships several reusable recorders:

• makeMiddlewareRecorder produces a closure that records both scoped and unscoped versions of a middleware metric, using segment duration and exclusive time. Source: lib/metrics/recorders/middleware.js:11-21
• recordResolveSegment extracts FIELD_NAME_ATTR and PARENT_TYPE_ATTR from segment attributes to produce a RESOLVE_PREFIX/<ParentType>.<fieldName> metric for Apollo GraphQL resolvers, disambiguating duplicate field names across different types. Source: lib/metrics/recorders/apollo-resolver.js:16-33

OpenTelemetry Bridge

The agent also bridges OpenTelemetry spans into its own transaction model. The propagateTraceContext helper reads the span context and constructs a W3C Traceparent object that the transaction accepts, forwarding the trace state to the New Relic backend under a transport tag (e.g. http, kafkajs, rabbitmq). Source: lib/otel/traces/segments/utils.js:13-31

Transformation rules describe how to map OTel spans onto agent segments. For example, the FallbackProducer rule converts any producer span into a MessageBroker/unknown/unknown/Produce segment when no more specific rule matches. Source: lib/otel/traces/transformation-rules/499-FallbackProducer.json:1-13

The v14.1.0 release extended this OTEL bridge to support native Next.js instrumentation, demonstrating how the framework can absorb new runtimes and frameworks without changes to the subscriber contract.

See Also

• Configuration and installation: README.md
• Cloud deployment tooling: cloud-tooling/README.md
• Azure site extension: cloud-tooling/azure-site-extension/Content/README.md
• Community issue #991 — Prisma instrumentation gap
• Community issue #553 — ESM support
• Community issue #904 — Next.js support
• Community issue #1959 — BunJS compatibility
• Community issue #1727 — Deno runtime support

Related Pages

Related topics: Overview and Core Architecture, Instrumentation Framework and Subscribers, AI/LLM Monitoring and Modern Integrations

OpenTelemetry, Hybrid Agent, and Modern Runtimes

1. Purpose and Scope

The node-newrelic agent ships an OpenTelemetry (OTEL) bridge that allows the agent to consume spans produced by upstream OTEL instrumentations and translate them into native New Relic APM segments. This is the foundation of the Hybrid Agent approach introduced in v14.1.0, which enables first-class support for runtimes and frameworks (such as Next.js) that already ship their own OTEL instrumentation rather than relying solely on the agent's shim-based hooks.

The OTEL bridge is registered through SetupTraces, which builds a BasicTracerProvider configured with a custom sampler and a New Relic span processor. Once installed globally, the bridge reuses the agent's existing tracer, segment tree, and metric pipeline, so OTEL spans appear in the same transaction trace as the agent's native segments.

flowchart LR
    A[OTEL Instrumentation<br/>e.g. Next.js] -->|spans| B[BasicTracerProvider]
    B --> C[NrSampler]
    C -->|sampled spans| D[NrSpanProcessor]
    D --> E[SegmentSynthesizer]
    E --> F[New Relic Segments / Metrics]
    D --> G[AttributeReconciler]
    G --> F

A supportability metric is emitted when the bridge is enabled, making it possible to confirm in the New Relic UI that the bridge is active in a given process — Source: lib/otel/traces/index.js:17-19.

2. Sampling, Rules, and Span Processing

Sampler

NrSampler decides whether an incoming OTEL span should be recorded. A span is sampled if any of the following is true:

• An active New Relic transaction is already in progress on the OTEL context.
• The parent span context is isRemote (i.e. propagated across a process boundary).
• The span is of kind SERVER or CONSUMER.

In all other cases the sampler returns NOT_RECORD, avoiding double-counting for internal spans that are already part of an instrumented transaction. Source: lib/otel/traces/sampler.js:9-21.

Rules Engine

OTEL spans do not carry the same semantic metadata as the agent's internal segments, so the bridge needs a rules engine to decide how each span should be mapped. OtelRuleMatcher in lib/otel/traces/rules.js defines the matchable properties — required span kinds (server, client, internal), required attribute keys, attribute value conditions, and an instrumentationScope.name filter. This allows transformation rules (loaded from transformation-rules/index.js) to target only the spans produced by specific OTEL instrumentations.

Span Processor

NrSpanProcessor runs on every emitted OTEL span. It:

• Pulls context from the agent tracer to find the active transaction and parent segment.
• Creates a new segment using the OTEL spanId to keep correlation stable.
• Reconciles attributes via AttributeReconciler.
• Synthesizes child segments through SegmentSynthesizer (see lib/otel/traces/span-processor.js).
• Forwards the final segments into the agent's existing transaction and metrics pipeline.

The processor reuses the agent's logger (defaultLogger.child({ component: 'span-processor' })) so OTEL-derived events appear in the same newrelic_agent.log file as native instrumentation logs. Source: lib/otel/traces/span-processor.js:13-44.

3. Segment Synthesis and Distributed Trace Propagation

Internal Segments

For spans that match an internal rule, the bridge creates a plain internal segment and attaches it to the active transaction's segment tree. The factory in lib/otel/traces/segments/internal.js reuses agent.tracer.createSegment with the OTEL span id and a genericRecorder, ensuring the segment inherits the same naming, timing, and exclusive-duration semantics as any other internal segment produced by the agent.

Trace Context Propagation

Distributed trace headers are produced via propagateTraceContext in lib/otel/traces/segments/utils.js. When the OTEL span has a parent, the helper builds a W3C traceparent from the span context (prefixing traceFlags with 0 to match the parsed integer stored on spanContext) and calls transaction.acceptTraceContextPayload, ensuring that the OTEL span and any outbound HTTP/message-broker calls made by the same handler share a single distributed trace id. Source: lib/otel/traces/segments/utils.js:8-29.

Semantic Convention Constants

lib/otel/traces/constants.js provides a curated copy of OTEL semantic-convention attribute names (e.g. aws.region, db.namespace). The file's docblock notes that the upstream conventions are "still very much in flux" as of early 2025, so the agent maintains its own copy to insulate downstream code from breakage. Source: lib/otel/traces/constants.js:11-20.

4. Modern Runtimes and Community Gaps

The Hybrid Agent strategy is particularly relevant for runtimes where the agent's traditional shim-based instrumentation either cannot run or is incomplete. The agent itself still targets Node.js 22+ as documented in package.json ("node": ">=22"), and existing core instrumentations such as timers and DNS in lib/instrumentation/core/timers.js and lib/instrumentation/core/dns.js operate against Node's built-in modules.

Several long-running community requests illustrate the boundary of the current model:

• Next.js (#904, addressed in v14.1.0): the release notes for v14.1.0 explicitly call out "support for native Next.js OTEL instrumentation via the Hybrid Agent," which is the first framework to be brought on board through the OTEL bridge described above.
• Bun (#1959) and Deno (#1727): both runtimes execute npm packages but expose a different global surface than Node. Because the agent's bootstrap and core/timers instrumentation assumes Node's setTimeout/setInterval on global, these runtimes remain community feature requests rather than supported configurations.
• ESM (#553): the default config file lookup uses newrelic.js, which fails when a project sets "type": "module". A newrelic.cjs workaround is mentioned in the issue, but the agent does not yet auto-detect the extension.
• Prisma (#991): because Prisma bypasses the standard pg/mysql2 drivers, neither the agent's shim-based datastore instrumentation nor the OTEL bridge will see the queries, leaving a gap that requires either an upstream Prisma OTEL exporter or a dedicated instrumentation.

For deployments, the agent is also packaged for Azure App Services via the Azure site extension, which installs the package and sets NODE_OPTIONS so the agent preloads automatically. The Hybrid Agent does not change that deployment model; the OTEL bridge is simply an additional signal source feeding the same agent core.

See Also

• Configuration and Instrumentation Overview
• OTEL Transformation Rules
• AWS SDK Subscriber
• Azure Site Extension

Related Pages

Related topics: Overview and Core Architecture, Instrumentation Framework and Subscribers, OpenTelemetry, Hybrid Agent, and Modern Runtimes

AI/LLM Monitoring and Modern Integrations

The New Relic Node.js agent has evolved from a classic APM package into a hybrid monitoring tool that supports modern, AI-driven workloads. This page documents the AI/LLM monitoring subsystem (centered on AWS Bedrock), the OpenTelemetry (OTEL) bridge that powers the agent's "Hybrid Agent" mode, and the related modern instrumentation hooks (AWS SDK v3, KafkaJS, core modules). It also calls out runtime and module-format limitations drawn from community discussion.

AI/LLM Monitoring via AWS Bedrock

AI monitoring is gated by a single configuration switch and implemented as AWS SDK v3 middleware that records a set of LLM event types.

• Gate: config.ai_monitoring.enabled — shouldSkipInstrumentation returns true when the flag is false, so the middleware is short-circuited. Source: lib/subscribers/aws-sdk/middleware/bedrock/utils.js:30-35
• Event vocabulary: LlmChatCompletionMessage, LlmChatCompletionSummary, LlmEmbedding, LlmErrorMessage, and BedrockResponse are imported from #agentlib/llm-events/aws-bedrock/index.js. Source: lib/subscribers/aws-sdk/middleware/bedrock/utils.js:10-18
• Streaming: isStreamingEnabled checks both the STREAMING_COMMANDS set and config.ai_monitoring?.streaming?.enabled, delegating to a dedicated StreamHandler or ConverseStreamHandler. Source: lib/subscribers/aws-sdk/middleware/bedrock/utils.js:46-53
• Attribute destinations: messages and tokens are routed through DESTINATIONS from #agentlib/config/attribute-filter.js to keep PII filtering consistent with the rest of the agent. Source: lib/subscribers/aws-sdk/middleware/bedrock/utils.js:11

The Bedrock middleware is registered only for the BedrockRuntime client, alongside the other AWS v3 services (DynamoDB, Lambda, SNS, SQS). Source: lib/subscribers/aws-sdk/send.js:12-19

AWS SDK v3 Subscriber Architecture

Instead of registering a subscriber per AWS service package, the agent hooks @smithy/smithy-client's Client.send once and dispatches middleware per client name. This is the central integration point for AI monitoring as well as standard AWS tracing.

• Subscriber design: SmithyClientSendSubscriber extends the base Subscriber and resolves a middlewareByClient map at load time. Source: lib/subscribers/aws-sdk/send.js:12-19
• Common concerns: the nrMiddleware chain (DT header suppression, response attributes) is applied to every supported client, while service-specific middleware (Bedrock, DynamoDB, Lambda, SNS, SQS) is appended. Source: lib/subscribers/aws-sdk/send.js:12-19
• Distributed-tracing header list: traceparent, tracestate, newrelic. These are the headers that the Bedrock and other AWS middleware suppress on outgoing requests to prevent leaks into non-NR systems. Source: lib/subscribers/aws-sdk/utils/constants.js:7-9
• Middleware contract: each entry in middlewareByClient conforms to the AwsSdkMiddleware typedef (an fn plus optional init and config). Source: lib/subscribers/aws-sdk/index.js:1-32

OpenTelemetry Bridge and Hybrid Agent

The agent can synthesize New Relic segments from raw OTEL spans, enabling interoperability with OTEL-instrumented libraries and frameworks (e.g., the native Next.js OTEL path added in v14.1.0).

• Entry point: SegmentSynthesizer#synthesize(otelSpan) matches the span to a RulesEngine rule and dispatches to one of six segment factories. Source: lib/otel/traces/segment-synthesis.js:30-71
• Supported span kinds: consumer, db, external, internal, producer, server — see createConsumerSegment, createDbSegment, etc. in the dispatch switch. Source: lib/otel/traces/segment-synthesis.js:42-71
• Trace-context propagation: propagateTraceContext builds a W3C Traceparent from the OTEL span context, prepending 0 to traceFlags because OTEL stores the flags as a parsed integer. The transport tag (e.g., kafkajs, rabbitmq) is forwarded to transaction.acceptTraceContextPayload. Source: lib/otel/traces/segments/utils.js:16-30
• Semantic constants: the agent keeps a curated copy of OTEL semantic-convention attribute names (e.g., ATTR_AWS_REGION: 'aws.region') rather than depending on a moving upstream package. Source: lib/otel/traces/constants.js:17-32

flowchart LR
    A[Instrumented Library] -->|OTEL span| B[SegmentSynthesizer]
    B --> C{RulesEngine match}
    C -->|consumer/db/external<br/>internal/producer/server| D[Segment Factory]
    D --> E[Transaction]
    A -->|direct hook| F[AWS SDK Subscriber]
    F --> G[Bedrock LLM Events]
    F --> H[DT header suppression]

Modern Runtime and Integration Notes

A few adjacent "modern" features that AI/LLM and hybrid deployments typically depend on:

• Node version: the package requires node >=22 and npm >=6.0.0, which is what enables newer features such as fs.glob instrumentation. Source: package.json:31-34
• Core fs: glob is recorded only when it is present on the module (added in Node 22); write and read are excluded from the recorder list to avoid high-volume noise. Source: lib/instrumentation/core/fs.js:51-58
• Core timers: setTimeout, setInterval, and clearTimeout are wrapped on both the timers module and global; wrapped timers are tagged with a symbol so clearTimeout can mark the corresponding segment as ignored. Source: lib/instrumentation/core/timers.js:18-49
• Kafka: per-broker linking metrics (MessageBroker/Kafka/Nodes/<broker>/<Produce|Consume>/<topic>) and per-method counters are produced via recordLinkingMetrics and recordMethodMetric. Source: lib/subscribers/kafkajs/utils/record-linking-metrics.js:18-24, lib/subscribers/kafkajs/utils/record-method-metric.js:12-16
• Middleware metrics: makeMiddlewareRecorder is the canonical helper for turning segment durations into scoped + unscoped measurements. Source: lib/metrics/recorders/middleware.js:12-23

Community-Relevant Limitations

Several frequently-requested integrations remain out of scope or partial as of v14.1.0:

• Next.js: native OTEL support landed in v14.1.0 via the Hybrid Agent path, but first-class framework support (custom server, app router specifics) is still requested (issue #904).
• Prisma: Prisma bypasses the standard pg/mysql drivers, so DB instrumentation does not cover Prisma's query engine (issue #991). Custom instrumentation is the current workaround.
• ESM: when package.json declares "type": "module", the loader looks for the default config filename newrelic.js and does not auto-detect newrelic.cjs (issue #553). Users must pass the config path explicitly or rename the file.
• Bun and Deno: both are requested as target runtimes (issues #1959, #1727). The package currently targets Node ≥ 22 only.
• Cloud deployment: an Azure site extension exists that injects NODE_OPTIONS and installs the agent into node_modules; the install log lives under C:\home\SiteExtensions\.... Source: cloud-tooling/azure-site-extension/Content/README.md:1-30

See Also

• Configuration reference: lib/config/default.js (referenced from the stock newrelic.js template in the README).
• General agent installation and -r newrelic bootstrap: README.md.
• LLM event model: #agentlib/llm-events/aws-bedrock/index.js.

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Maintenance risk - Maintenance risk requires verification.

1. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4054

2. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4053

3. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4055

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4056

5. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://www.npmjs.com/package/newrelic

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/3458

7. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://www.npmjs.com/package/newrelic

8. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4050

9. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/newrelic/node-newrelic/issues/4057

10. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/newrelic

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/newrelic

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://www.npmjs.com/package/newrelic

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using node-newrelic with real data or production workflows.

• Fix Next.js tests - github / github_issue
• [[Spike] Explore options to support next.js](https://github.com/newrelic/node-newrelic/issues/3188) - github / github_issue
• Benchmark tests will run in PRs - github / github_issue
• Add supportability metrics to OTEL metrics exporter - github / github_issue
• [[spike] Core instrumentation update](https://github.com/newrelic/node-newrelic/issues/4058) - github / github_issue
• [[spike] Research replacing instrument* api methods](https://github.com/newrelic/node-newrelic/issues/4057) - github / github_issue
• [[spike] Research migrating security agent to use tracing channel instrum](https://github.com/newrelic/node-newrelic/issues/4056) - github / github_issue
• Drop support for restify - github / github_issue
• Drop support for next < 16 - github / github_issue
• Drop support for prisma wasm client - github / github_issue
• Drop support for aws-sdk v2 - github / github_issue
• Add cpu to wall time profiling samples - github / github_issue