repository·main·Indexed 21 days ago
https://github.com/newrelic/node-newrelicAn instrumentation tool for monitoring Node.js application performance, providing visibility into transactions, errors, and system metrics. Includes documentation on Azure Site Extension installation, distributed tracing sampling configuration, and the subscriber-based instrumentation model using diagnostic_channel TracingChannel objects.
Attributes can be filtered out based on rules defined by New Relic or the user. For example, a rule can be set to drop any attribute with a specific key (e.g., foo.bar).
Filtering configuration can be provided via:
connect event.The New Relic Node.js agent is proprietary software intended solely for use with New Relic's proprietary SaaS service. To use the software, you must have a valid and active subscription to the New Relic Service.
Key Restrictions:
Intellectual Property & Feedback: Any feedback provided to New Relic (including source code or comments) is provided under the terms of the Apache Software License, version 2. This grant is irrevocable.
Termination: This license terminates when the software is no longer provided by New Relic or as described in your subscription agreement. Upon termination, you must remove the software from your systems within a commercially reasonable timeframe.
Starting with v13.2.0, the New Relic Node.js agent is refactoring traditional Shim-based monkey-patching to a subscriber-based model. Instead of patching code directly, the agent subscribes to events emitted by Node.js diagnostic_channel TracingChannel objects.
This mechanism uses @apm-js-collab/tracing-hooks and orchestrion-js to inject tracing channels into instrumented packages. A Subscriber listens to these channels for specific events such as asyncEnd, asyncStart, start, end, and error. Context is preserved across these asynchronous boundaries using AsyncLocalStorage.
The New Relic Node.js agent may contain third-party and open source software (OSS). Each third-party component is governed by its own specific license and terms, which are disclosed in the provided licensing information.
If you require source code disclosure as required by the terms of an OSS component used within the agent, you can request it from New Relic by emailing opensource@newrelic.com.
Span links are a mechanism used to describe how an entity (like a span) relates to the transaction that produced it. They are primarily used to support the propagation of metadata from OpenTelemetry instrumentations, particularly in distributed messaging systems where a single transaction might be decoupled from another via a queue.
Common Use Case: Distributed Messaging
The New Relic Node.js agent automatically configures the OpenTelemetry Metrics API to ship metrics to New Relic.
To ensure metrics are not lost during the agent's initialization, the agent collects metrics in memory during its bootup sequence and flushes them once the sequence is complete. While the agent handles this automatically, for maximum robustness, you should wait for the agent's bootup to complete before initializing your metrics objects.
An instrumentation is a mechanism that allows the New Relic agent to run code immediately after a Node.js program loads a specific module via require. This code can "wrap" (monkey-patch) module methods to create metrics, events, and segments.
Instrumentations use helper objects called shims to perform shared tasks like naming a transaction or creating a segment.
There are three categories of instrumentations:
http).express), where the instrumentation code lives inside the agent.@newrelic/koa).Span creation depends on your configuration for distributed tracing and span events capture. The agent iterates over every segment in the trace and processes it based on the tracing granularity type:
Creates a StreamingSpanEvent and adds it to the StreamingSpanEventAggregator stream.
Creates a SpanEvent and adds it to the SpanEventAggregator.
Runs logic based on the specific partial granularity type and enqueues the span back to the trace on a trace.spans Array. If a span is dropped, its ID and parent are tracked in the trace.droppedSpans map to allow for reparenting later.
Partial Granularity Types:
reduced: Creates a SpanEvent. It keeps entry point spans, LLM spans, and exit spans (e.g., span.kind of client) if they have at least one attribute used for entity relationships.essential: Uses reduced logic, but also keeps all intrinsic attributes, only keeps agent attributes used for entity relationships, and drops all user attributes.compact: Uses reduced and essential logic, but further restricts the trace to only one exit span per entity.Finalization in Partial Granularity: Unlike infinite or full granularity, partial granularity traces undergo a finalization process once spans are generated:
reduced or essential. If the type is compact, all exit spans are re-parented to the entry point span.nr.ids: An array of exit span IDs that were dropped for the same entity.nr.durations: A float representing the total unique duration of all exit spans for that entity.In New Relic, attributes are key-value pairs used as metadata for transactions and segments. Keys are strings (which can be dot-separated paths), and values are either strings or numbers.
Attributes are categorized into three main buckets:
Data is typically sent to the collector as a collection of these three buckets.
Unlike other language agents that name transactions after the class or method handling the response, the Node Agent uses a routing-based naming scheme. This is designed to align with the middleware paradigm common in Node.js web frameworks (like Express).
Transactions are named based on the mounting paths of the middleware that eventually responds to the request. This approach ensures that transaction names reflect the API structure (routes) rather than internal function names, which are often anonymous in Node.js.