OpenTelemetry API support in New Relic agents

Prerequisites

Add the required OpenTelemetry dependencies to your application:

implementation(platform("io.opentelemetry:opentelemetry-bom:1.44.1"))
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
implementation("io.opentelemetry:opentelemetry-exporter-otlp")

Enable OpenTelemetry API support

1. Enable OpenTelemetry SDK autoconfiguration

Use one of the following methods:

System property:

$
-Dotel.java.global-autoconfigure.enabled=true

Environment variable:

$
export OTEL_JAVA_GLOBAL_AUTOCONFIGURE_ENABLED=true

2. Enable New Relic OpenTelemetry support

System property:

$
-Dnewrelic.config.opentelemetry.enabled=true

Environment variable:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

YAML configuration (newrelic.yml):

opentelemetry:
  enabled: true

Supported instrumentation types

Manual instrumentation

Custom instrumentation using the OpenTelemetry trace, metrics, or logs APIs will be automatically captured by the agent.

Library and native instrumentation

OpenTelemetry standalone library instrumentations and native instrumentation built directly into libraries will work with the New Relic agent. However, OpenTelemetry bytecode-based auto-instrumentation will not be detected by the New Relic agent.

Enable OpenTelemetry API support

Enable OpenTelemetry API support in your newrelic.js configuration file:

exports.config = {
  // ... other config
  opentelemetry: {
    enabled: true,
    traces: {
      enabled: true
    }
  }
  // ... other config
}

Supported OpenTelemetry APIs

When OpenTelemetry support is enabled, the Node.js agent fully supports:

Traces API

Create custom spans and add attributes using the OpenTelemetry Tracing API. See the OpenTelemetry Node.js tracing example.

Metrics API

The Metrics API is the most useful feature for Node.js customers. It expands the metrics collection capability to include dimensional metrics, a frequently requested feature.

Record custom metrics using the OpenTelemetry Metrics API. See the OpenTelemetry Node.js metrics example.

Logs API

The JavaScript OpenTelemetry Logs API is still in development, but the Node.js agent supports it. You can use the API to emit logs that will be shipped to New Relic.

See the OpenTelemetry Node.js logs example.

Supported instrumentation types

Manual instrumentation (recommended)

Customers who instrument their applications with the OpenTelemetry API will find that the agent processes and ships that data correctly.

Native and library instrumentation (limited)

The list of OpenTelemetry instrumentations has significant overlap with the Node.js agent's supported modules. Instrumentations that are not already covered by the New Relic agent may:

• Conflict with agent internals
• Not have sufficient customer demand

Known limitations

• No automatic instrumentations: The agent does not automatically enable OpenTelemetry instrumentations. Customers must manually instrument their code using OpenTelemetry APIs.

Enable OpenTelemetry API support

Enable OpenTelemetry API support using either environment variables or the newrelic.config XML configuration file.

Using environment variables:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Using newrelic.config:

<configuration>
  <openTelemetry enabled="true" />
</configuration>

Supported native instrumentations

When you enable OpenTelemetry API support, the .NET agent can capture telemetry from OpenTelemetry-instrumented libraries.

Traces instrumentations

The agent supports libraries with native OpenTelemetry tracing instrumentation. Custom instrumentation written using the OpenTelemetry Tracing API is also supported.

Metrics instrumentations

When metrics are enabled, the agent supports OpenTelemetry metric instrumentations from libraries and frameworks. Custom instrumentation written using the OpenTelemetry Metrics API is also supported.

Logs instrumentations

The .NET agent already instruments the logging library that became the OpenTelemetry API for log data. No changes are required for logs when enabling OpenTelemetry API support. For backwards compatibility, log instrumentation continues to work as before.

Enable OpenTelemetry API support

Enable OpenTelemetry API support in your newrelic.ini configuration file or using environment variables:

Using newrelic.ini:

[newrelic]
opentelemetry.enabled = true

Using environment variable:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

How it works

When OpenTelemetry support is enabled and the agent detects opentelemetry-api is installed:

1. Native instrumentation: For libraries with native OpenTelemetry instrumentation built in, the agent automatically disables New Relic's hooks and uses the native OpenTelemetry instrumentation instead.

2. Library instrumentation: If an OpenTelemetry instrumentation library is detected, the agent automatically uses the OpenTelemetry instrumentation instead of New Relic's instrumentation hooks.

For the current list of available Python instrumentations, see the official OpenTelemetry Python instrumentation list.

Manual instrumentation

Any custom instrumentation written using the OpenTelemetry Tracing API will be captured by the agent.

Example:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-custom-span") as span:
    span.set_attribute("custom.attribute", "value")
    # Your code here

Supported features

Traces API

✅ Fully supported: Create custom spans and add attributes using the OpenTelemetry Tracing API

Metrics API

❌ Not yet supported: OpenTelemetry Metrics API is not enabled in the Python agent

Logs API

✅ Already works: The agent already supports the logging module. There is no OpenTelemetry API for logging in Python (only an SDK exists). What OpenTelemetry configures for logging is whether it's enabled and which endpoints to send data to.

How it works

When OpenTelemetry support is enabled:

1. Agent searches the system to determine if OpenTelemetry instrumentation libraries are installed
2. Automatic switching: If found, the agent uses the OpenTelemetry library's instrumentation instead of New Relic's hooks
3. Seamless integration: OpenTelemetry spans are integrated into New Relic traces

Known limitations

• Metrics not supported: OpenTelemetry Metrics API is not yet enabled
• Some AWS and gRPC libraries excluded: Will continue to use New Relic instrumentation
• AI libraries disabled: Native OpenTelemetry instrumentation for AI libraries is disabled for now
• Include/exclude settings: Fine-tuning options are planned for future releases but only enable/disable is currently functional

Enable OpenTelemetry API support

To enable OpenTelemetry API support in the Ruby agent, add the following to your newrelic.yml configuration file:

opentelemetry:
  enabled: true

Or set the environment variable:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Supported features

Traces API

✅ Supported: Create custom spans and add attributes using the OpenTelemetry Tracing API

Metrics API

❌ Not supported: OpenTelemetry Metrics API

Logs API

❌ Not supported: OpenTelemetry Logs API

Span Links

❌ Not supported: Span Links

Events on Spans

❌ Not supported: Events on Spans

How it works

The Ruby agent detects the presence of the OpenTelemetry API installation and instruments OpenTelemetry APIs for Tracing to generate telemetry. When a library or your application code calls OpenTelemetry APIs, the New Relic Ruby agent translates those calls into New Relic data if OpenTelemetry support is enabled.

• Requirement: The OpenTelemetry API must be present in your application for the hybrid agent functionality to work.

Supported instrumentations

The Ruby agent works with three types of OpenTelemetry instrumentation:

1. Native instrumentation

Libraries with built-in OpenTelemetry instrumentation calls are supported. When these libraries make calls to the OpenTelemetry API, the Ruby agent captures and translates them into New Relic telemetry.

2. Third-party instrumentation (opentelemetry-ruby-contrib)

If you install gems from the opentelemetry-ruby-contrib repository, their calls to OpenTelemetry APIs will be processed and transformed into New Relic data.

For a comprehensive list of available Ruby instrumentation, consult the OpenTelemetry registry.

3. Custom/manual instrumentation

When OpenTelemetry support is enabled, calling OpenTelemetry APIs in your application code will generate New Relic telemetry automatically.

Known limitations

• Limited API support: Only Traces API is supported in this release
• Metrics and Logs: Not available
• Exclude list: Work is ongoing to automate the prevention of duplicate telemetry when both OpenTelemetry and New Relic have instrumented the same methods. For now, you may need to manually disable one instrumentation to prevent duplicates.
• Span Links and Events: Not currently supported

Check your agent configuration to confirm OpenTelemetry support is enabled:

• Review environment variables or configuration files
• Check agent logs for confirmation that OpenTelemetry support is active
• Ensure you've restarted your application after changing configuration

Confirm you're running the minimum required agent version that supports OpenTelemetry APIs. See the supported languages table above.