OpenTelemetry Bridge
The agent can act as the backend for the OpenTelemetry API: spans, metrics, and logs that your code or OpenTelemetry instrumentation libraries create with @opentelemetry/api are turned into New Relic transactions, segments, metrics, and log events — without running the OpenTelemetry SDK or an OTLP exporter yourself. This is the OpenTelemetry bridge. It is off by default.
Enabling the Bridge
exports.config = {
opentelemetry: {
enabled: true,
traces: { enabled: true },
metrics: { enabled: true },
logs: { enabled: true }
}
}
| Setting | Default | Env var | Effect |
|---|---|---|---|
opentelemetry.enabled |
false |
NEW_RELIC_OPENTELEMETRY_ENABLED |
Global switch. When false, no signal is set up, whatever the sub-settings say. |
opentelemetry.traces.enabled |
true |
NEW_RELIC_OPENTELEMETRY_TRACES_ENABLED |
Register a tracer provider that maps spans to New Relic data. |
opentelemetry.metrics.enabled |
true |
NEW_RELIC_OPENTELEMETRY_METRICS_ENABLED |
Register a meter provider that exports metrics to New Relic. |
opentelemetry.logs.enabled |
true |
NEW_RELIC_OPENTELEMETRY_LOGS_ENABLED |
Register a logger provider that feeds New Relic application logging. |
opentelemetry.metrics.export_interval |
60000 |
NEW_RELIC_OPENTELEMETRY_METRICS_EXPORT_INTERVAL |
Milliseconds between metric exports. |
opentelemetry.metrics.export_timeout |
10000 |
NEW_RELIC_OPENTELEMETRY_METRICS_EXPORT_TIMEOUT |
Milliseconds an export may take. |
The sub-signals default to true, so opentelemetry.enabled: true alone turns on all three.
Required packages
The bridge needs the agent's @opentelemetry/* dependencies (@opentelemetry/api, @opentelemetry/sdk-metrics, @opentelemetry/resources, the OTLP exporter packages, and so on) to be resolvable from the agent's install location. If any is missing, the agent refuses to start and logs OpenTelemetry bridge enabled, but packages are missing. Not starting!. newrelic validate-config performs the same check relative to the configuration file it validates.
Your own code should import the same @opentelemetry/api (a 1.x version). The API uses a global registry, so instrumentation that resolves a compatible copy of the API sees the providers the agent registered.
What Happens to Each Signal
At setup the bridge installs, through @opentelemetry/api, a context manager backed by the agent's own context, a propagator backed by the agent's distributed tracing, and the providers for the enabled signals.
Traces
The tracer provider uses a sampler that records a span when:
- there is an active New Relic transaction, or
- the span is a
SERVERorCONSUMERspan, or its parent context is remote.
Other spans (for example a CLIENT span created outside any transaction) are not recorded.
Recorded spans become New Relic data through transformation rules: JSON rules shipped in lib/otel/traces/transformation-rules/ that match spans by kind and semantic-convention attributes, and say how to name the segment or transaction and which attributes to copy. There are rules for HTTP servers (including Next.js), RPC servers, messaging consumers and producers (including SQS), database clients (generic, Redis, MongoDB, DynamoDB, Prisma), HTTP and RPC clients, Lambda clients, and fallbacks for each category. So an OpenTelemetry HTTP server span starts a web transaction, a database client span becomes a datastore segment, and so on.
The rule format is documented in otel-transformation-rules.md.
url_obfuscation also applies to the URL path of inbound transactions created from OpenTelemetry spans (see Transaction Naming).
Metrics
The meter provider collects metrics (with delta temporality) in memory. Because metrics must be associated with your application entity, export only starts once the agent has connected and received its entity.guid; metrics recorded earlier are kept and flushed at that point. The exporter sends OTLP to https://<host>:<port>/v1/metrics with your license key, honoring the agent's proxy settings.
When the bridge is ready, the agent emits otelMetricsBootstrapped. To make sure no metrics are recorded too early, wait for it:
'use strict'
const newrelic = require('newrelic')
const { metrics } = require('@opentelemetry/api')
newrelic.agent.on('otelMetricsBootstrapped', () => {
const counter = metrics.getMeter('checkout').createCounter('orders.placed')
startServer({ counter })
})
If export_interval is not greater than export_timeout, the agent logs a warning and uses 60000 and 10000 instead.
In serverless mode, metrics are not sent on an interval: they are captured and included in the agent's own harvest at the end of the invocation.
The repository's metrics guide walks through a Fastify example.
Logs
The logger provider forwards OpenTelemetry log records into New Relic application logging. It is only installed when application_logging.enabled is true. Records then count toward logging metrics (application_logging.metrics.enabled) and are forwarded as log events with linking metadata (application_logging.forwarding.enabled).
OTEL_* Environment Variables
When opentelemetry.enabled is true, a few standard OpenTelemetry environment variables are mapped to their New Relic equivalents — but only if the New Relic variable is not set:
| OpenTelemetry variable | Mapped to |
|---|---|
OTEL_SERVICE_NAME |
NEW_RELIC_APP_NAME |
OTEL_LOG_LEVEL |
NEW_RELIC_LOG_LEVEL (lowercased and validated) |
OTEL_SDK_DISABLED |
The inverse of NEW_RELIC_ENABLED |
Any other OTEL_* variable is logged at debug level and ignored. When the bridge is disabled, no OTEL_* variable is read.
Interplay with Distributed Tracing
The bridge's propagator uses the agent's distributed tracing, so traceparent/tracestate handling and sampling decisions follow the distributed_tracing configuration. Spans from OpenTelemetry instrumentation and segments from New Relic instrumentation share the same trace.