OpenTelemetry quick start | New Relic Documentation

OpenTelemetry is a flexible toolkit that you can implement in a variety of ways. We recommend a basic four-step approach for setting up OpenTelemetry with New Relic. Here's an overview of the process, followed by details for each step.

Prerequisites
Instrument your service with OpenTelemetry
Export your telemetry data to New Relic
View your data in the New Relic UI

Step 1. Prerequisites

First things first:

If we don't already know you, sign up for a free New Relic account.
Copy your account license key.

Step 2. Instrument your service with OpenTelemetry

To get started, you instrument your service with OpenTelemetry. OpenTelemetry has language-specific products and SDKs to help you. Many languages offer out-the-box instrumentation for common libraries and frameworks. Each language also provides an API for further instrumenting your service manually.

Go to the repository for your language and follow the instructions to instrument your service. When you're done, return here to complete Step 3. Export your telemetry data to New Relic.

Step 3. Export your telemetry data to New Relic

The OpenTelemetry Protocol, or OTLP for short, is a general purpose telemetry data delivery protocol designed for the OpenTelemetry project. This protocol describes how to encode and transmit telemetry data, which makes it a natural choice for data transport. Each language SDK provides an OTLP exporter you can configure to export data over OTLP.

In this step, we focus on how to configure an OTLP exporter in your service to export data directly to New Relic. If you prefer to export your data first to an OpenTelemetry collector, we have separate instructions.

Diagram showing OpenTelemetry using New Relic's OTLP endpoint.

Here's an example of sending data from your service directly to New Relic.

To complete this third step, first familiarize yourself with some required New Relic settings, and then complete the steps in the OTLP exporter documentation for your language.

Review New Relic settings for exports

Before you go to the external OTLP exporter documentation, consult the table below so you're ready to do the following:

Configure the OTLP exporter to add a header (api-key) whose value is the license key for the New Relic account you want to send data to.
Based on your integration, configure the endpoint where the exporter sends data to New Relic. The endpoints are region-specific, so use the one according to where your account is based. For example, use the EU endpoint if your account is based in Europe.

Integration	gRPC	HTTP	Endpoint	Supported Ports	API header name	API header value	TLS encryption required
US OTLP	✅	✅	https://otlp.nr-data.net	`443`, `4317`, `4318`	`api-key`	License key	✅
EU OTLP	✅	✅	https://otlp.eu01.nr-data.net	`443`, `4317`, `4318`	`api-key`	License key	✅
US FedRamp OTLP (See see FedRAMP compliance for more information)	✅	✅	https://gov-otlp.nr-data.net	`443`, `4317`, `4318`	`api-key`	License key	✅
Infinite Tracing (See best practices for endpoint details	✅	❌	`https://{trace-observer}`	`443`	`api-key`	License key	✅

Important

In Node.js, the opentelemetry-collector-exporter-grpc library requires additional options to enable TLS.

A note about ports

OTLP standards designate gRPC traffic to port 4317, and HTTP traffic to port 4318. The New Relic US FedRamp Native OTLP endpoint adheres to those specifications, as well as allowing gRPC traffic on port 443.

However, non-FedRamp New Relic endpoints will accept both gRPC and HTTP traffic on any of the ports listed in the above chart.

A note about endpoints

Per the OpenTelemetry spec on endpoint URLs for OTLP/HTTP: If you are sending HTTP traffic and using the non-per-signal environment variable (OTEL_EXPORTER_OTLP_ENDPOINT), you can simply set OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:{port} and the exporter should append the appropriate path for the signal type (i.e., v1/traces or v1/metrics).

If you are using a per-signal environment variable (i.e., OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and/or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT), you are required to set it with the appropriate path. For example, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.nr-data.net:4318/v1/traces. Not doing so will result in a 404. Note that this environment variable takes precedence over the non-per-signal one.

Complete the export configuration steps

Click on the link below for your language and complete the configuration steps. When you're done, return here to complete Step 4. View your data in the New Relic UI.

The OpenTelemetry Collector is a configurable and extensible software component to receive, process, and export telemetry data. When you set up a collector, it can operate as a gateway or as an agent:

Gateway: The collector receives data from a variety of sources and applies standard processing before exporting to some backend.
Agent: The collector is deployed on each host in an environment and can collect telemetry data about the host and processes running on it.

When you use a collector, you start by following the same routine as above for setting up OTLP in your service. In this case, instead of exporting data directly to New Relic, you export through a collector that you set up. In the collector, you configure the OTLP exporter to export data to New Relic.

When your data goes through a collector, the transport looks like this:

Diagram showing OpenTelemetry using the OpenTelemetry Collector and New Relic's OTLP endpoint.

Here's a Docker example of how to set up and run an OpenTelemetry collector with the collector YAML:

Save the following as otel-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlp:
    endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      api-key: ${NEW_RELIC_LICENSE_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

Run the OpenTelemetry collector after you make the following changes:
- Replace OTLP_ENDPOINT_HERE with the appropriate [endpoint](#review-settings.
- Replace YOUR_KEY_HERE with your account's license key.

export OTEL_EXPORTER_OTLP_ENDPOINT=OTLP_ENDPOINT_HERE
export NEW_RELIC_LICENSE_KEY=YOUR_KEY_HERE

docker run --rm \
  -e OTEL_EXPORTER_OTLP_ENDPOINT \
  -e NEW_RELIC_LICENSE_KEY \
  -p 4317:4317 \
  -v "${PWD}/otel-config.yaml":/otel-config.yaml \
  --name otelcol \
  otel/opentelemetry-collector \
  --config otel-config.yaml

Step 4. View your data in the New Relic UI

Once you’ve instrumented your service and configured it to export its data to New Relic, watch the New Relic One user interface for your traces, metrics, and logs!

The UI for OpenTelemetry has some similarities to the APM agent UI, so if you are familiar with that, you can go right to the UI. If you need help understanding your OpenTelemetry UI options or how to make sure your data appears in the UI, see View your OpenTelemetry data in New Relic.

View our OpenTelemetry examples

View some of our examples for using OpenTelemetry with New Relic.

Unsupported specifications

New Relic currently supports opentelemetry-specification v1.8.0 with a few exceptions:

Successful responses from New Relic have no response body, instead of a Protobuf-encoded response based on the data type. New Relic also responds with success after authenticating, before decoding and validation.
Failure responses from New Relic do not include Status.message or Status.details, since OTLP clients don't use the Status object.
JSON-encoded Protobuf messages are not yet supported.

What's next?

After you do your initial setup, check out our best-practices guide for tips about various configurations to improve your use of OpenTelemetry and New Relic.