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 SERVER or CONSUMER span, 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.

See Also