The observability landscape is shifting rapidly. As engineering organizations scale and modern micro-service architectures grow in complexity, standardizing telemetry collection is no longer a luxury, it is a necessity. OpenTelemetry (OTel) has established itself as the industry standard for telemetry collection, promising portable, vendor-neutral instrumentation.
Adopting OTel often presents a dilemma. Teams have already made significant investments in mature Application Performance Monitoring (APM) agents, such as the New Relic agent, which provide rich, out-of-the-box auto-instrumentation and curated experiences for applications and infrastructure. Swapping out a fully functional APM agent across dozens of micro-services for a pure OTel SDK can be a costly, risky "big-bang" migration.
Fortunately, New Relic hybrid agent, introduces support for OpenTelemetry API in New Relic agents, which can help ease your migration to OTel. The hybrid agent allows you to incrementally adopt future-proof instrumentation using standard OTel APIs while continuing to route telemetry through your existing New Relic agent, smoothing the transition without losing your current APM capabilities.
Understanding OpenTelemetry APIs
To understand how the hybrid approach works, we must first look at the design of OTel. OTel explicitly separates its architecture into two distinct components:
- The OpenTelemetry API: The developer-facing instrumentation layer. It defines how data (traces, metrics, and logs) is recorded within the application codebase. This layer is generic and completely decoupled from any downstream destination.
- The OpenTelemetry SDK: The underlying implementation layer. It manages resource attributes, processes spans (like queueing and batching), aggregates measurements, and handles the exporter configurations that ship telemetry to backends (e.g., OTLP exporters).
Because instrumentation is embedded directly inside business logic, changing API calls across a large codebase is extremely expensive. By contrast, configuring the SDK and exporters happens in a single initialization place.
The takeaway is simple: instrumentation with the OpenTelemetry API to future-proof your code-level instrumentation, while leaving the routing and transmission details to the platform layer.
Using OpenTelemetry APIs with New Relic Agents
New Relic agents feature built-in OpenTelemetry hybrid agent support that acts as the bridge for calls made to OpenTelemetry APIs (see our supported languages). Instead of deploying a separate OpenTelemetry SDK and managing OTLP HTTP or gRPC exporters alongside your application, the New Relic agent acts as the OpenTelemetry SDK at runtime.
The hybrid agent intercepts calls made to the standard @opentelemetry/api package and seamlessly routes that data into the New Relic APM agent's native pipeline. The agent then transmits the telemetry to the New Relic platform (collector.newrelic.com) using its existing secure connections and agent protocols.
This hybrid model delivers key advantages:
- No SDK configuration boilerplate: You do not need to configure tracer providers, batch processors, or OTLP HTTP/gRPC exporters in your code.
- Seamless coexistence: Native APM auto-instrumentation and custom OTel instrumentation merge into unified transaction traces.
- Preserved workflows: Your existing New Relic dashboards, alerts, and APM capabilities remain active and unmodified.
- Incremental modernization: Teams can adopt OTel APIs at their own pace, service by service.
Code Sample: From Proprietary to Portable
To demonstrate how the hybrid agent functions, let’s examine a practical example from a Node.js microservice (payment-service). We’ll configure the hybrid agent and compare custom instrumentation using the New Relic Node.js agent API versus the standardized OTel API.
1. Configuring the OpenTelemetry Support
To activate this hybrid feature, configure the opentelemetry settings inside your newrelic.js configuration file. This instructs the New Relic agent to intercept @opentelemetry/api calls:
// newrelic.js - Configuration file for the New Relic agent
exports.config = {
// Other standard New Relic configuration options...
// Enables the OpenTelemetry bridge
opentelemetry: {
enabled: true,
traces: {
enabled: true
},
metrics: {
enabled: true
}
},
distributed_tracing: {
enabled: true
}
};By toggling opentelemetry.enabled to true, the agent dynamically hooks into the OTel API layer.
2. Custom Span and Attributes
Custom span attributes enrich tracing data with business-specific context (such as transaction IDs, order amounts, and payment methods).
Traditional APM Approach (New Relic Proprietary API)
Traditionally, you’d import the newrelic module directly and use its proprietary API:
const newrelic = require('newrelic');
// Create Custom Span wrapping the function execution
await newrelic.startSegment('PaymentGateway/ProcessPayment', true, async () => {
await simulatePaymentGateway(amount, orderId, logger);
});
// Record custom business attributes on the current span
newrelic.addCustomSpanAttributes({
'payment.transaction_id': transactionId,
'order.id': orderId,
'payment.amount': amount,
'payment.method': paymentMethod,
'payment.processing_time': processingTime,
'service.variant': 'apm'
});While this works perfectly, it couples your business routes directly to the newrelic package.
Hybrid Approach - Custom Span using OpenTelemetry API
With the OpenTelemetry support enabled, you write standard, OTel-first code instead. The New Relic agent intercepts this call under the hood:
const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('payment-service-tracer');
await tracer.startActiveSpan('payment.simulatePaymentGateway.OTel', async (span) => {
span.setAttribute('span.source', 'OtelAPI');
try {
await simulatePaymentGateway(amount, orderId, logger);
} finally {
span.end();
}
});Hybrid Approach - Custom Attributes using OpenTelemetry API
Using the same OTel-first code, we can add custom attributes on the active Span, and the New Relic agent intercepts this call under the hood:
const { trace } = require('@opentelemetry/api');
// Retrieve the active span from the OpenTelemetry API
const span = trace.getActiveSpan();
if (span) {
span.setAttributes({
'payment.transaction_id': transactionId,
'order.id': orderId,
'payment.amount': amount,
'payment.method': paymentMethod,
'payment.processing_time': processingTime,
'service.variant': 'hybrid'
});
}Notice that the hybrid code contains no references to New Relic. It is completely portable and adheres to industry-standard APIs.
Custom Span and attributes with OTel API
Context Interoperability (Mixing APIs)
A common challenge during a migration is dealing with mixed instrumentation. You may have heavily customized New Relic API calls deep within a service that are too risky to rewrite simultaneously with the outer route handlers.
The New Relic hybrid agent seamlessly handles context interoperability. This means you can nest New Relic native segments (newrelic.startSegment) directly inside OpenTelemetry spans (tracer.startActiveSpan), and both will appear correctly parented in a single, unified trace waterfall.
For example, inside our simulatePaymentGateway function, we might still have a legacy New Relic segment tracking a processing delay:
const newrelic = require('newrelic');
// A legacy New Relic segment nested inside the OTel span
newrelic.startSegment('PaymentGateway/ProcessingDelay', true, () => {
newrelic.addCustomAttribute('span.source', 'newrelic.SDK');
const start = Date.now();
while (Date.now() - start < ms) {
// blocking delay
}
});Because the hybrid agent maps OTel context into the New Relic transaction state, this legacy segment is perfectly parented to the outer payment.simulatePaymentGateway.OTel span in your distributed tracing UI.
Nested New Relic Span within OTel custom span
See everything in action below
3. Error Capturing
Capturing exceptions along with relevant metadata is vital for debugging errors such as payment failures and runtime errors.
Traditional APM Approach (New Relic Proprietary API)
Using the proprietary API, you’d call newrelic.noticeError to capture an exception:
const newrelic = require('newrelic');
// Capture error and associate it with transaction metadata
newrelic.noticeError(err, {
'payment.transaction_id': transactionId,
'order.id': orderId,
'payment.amount': amount,
'payment.method': paymentMethod,
'service.variant': 'apm'
});Hybrid Approach (OpenTelemetry API)
Under the hybrid model, you’d use standard OTel exception recording. The New Relic agent captures the exception and maps it to the APM error rate and transaction attributes. If you're within an active span block, it looks like this:
// Catch errors inside your OTel span block and record them
try {
await simulatePaymentGateway(amount, orderId, logger);
} catch (err) {
span.recordException(err);
span.setAttributes({
'payment.transaction_id': transactionId,
'order.id': orderId,
'payment.amount': amount,
'payment.method': paymentMethod,
'service.variant': 'hybrid'
});
throw err;
} finally {
span.end();
}If you ever migrate from New Relic to a pure OTel SDK, this exact error-reporting code remains completely unchanged.
Errors captured with OTel APIs
Best Practices for Hybrid Instrumentation
When implementing a hybrid instrumentation strategy, follow these developer-centric guidelines to ensure clean telemetry architectures:
- Default to
@opentelemetry/apifor new instrumentation: Ensure all new custom spans, attributes, and metrics are written using standard OTel API calls. - Enforce semantic conventions: Use OTel’s standard semantic naming guidelines (e.g., namespace prefixes such as
payment.*, db.,orhttp.*) to maintain clean, searchable data. - Keep core business logic vendor-free: Avoid importing vendor-specific SDK modules within your application's routes or services. Keep the vendor code isolated to the application initialization entry point.
- Decouple exporters from code: Let the APM agent configuration (
newrelic.js) handle how telemetry is sent. Don’t configure tracing endpoints or headers within your application logic.
Conclusion
OTel has redefined the future of instrumentation, but transitioning to open standards does not require discarding your existing tools. The hybrid approach enables a pragmatic, low-risk path to modernization.
By instrumenting your applications with the OpenTelemetry API while keeping the New Relic APM agent in place, you secure the best of both worlds. You gain vendor-neutral code that is prepared for future requirements, while retaining the reliable, production-tested pipeline of New Relic. This strategy delivers immediate value, protects your developer hours, and ensures your observability infrastructure is future-proof.
Die in diesem Blog geäußerten Ansichten sind die des Autors und spiegeln nicht unbedingt die Ansichten von New Relic wider. Alle vom Autor angebotenen Lösungen sind umgebungsspezifisch und nicht Teil der kommerziellen Lösungen oder des Supports von New Relic. Bitte besuchen Sie uns exklusiv im Explorers Hub (discuss.newrelic.com) für Fragen und Unterstützung zu diesem Blogbeitrag. Dieser Blog kann Links zu Inhalten auf Websites Dritter enthalten. Durch die Bereitstellung solcher Links übernimmt, garantiert, genehmigt oder billigt New Relic die auf diesen Websites verfügbaren Informationen, Ansichten oder Produkte nicht.
