❗Notice: This project has been archived as is and is no longer actively maintained.

Rather than developing a Java specific OpenTelemetry exporter New Relic has adopted a language agnostic approach that facilitates data collection from all OpenTelemetry data sources.

The current recommended approaches for sending OpenTelemetry data to the New Relic platform are as follows:

• Configure your OpenTelemetry data source to send data to the OpenTelemetry Collector using the OpenTelemetry Protocol (OTLP) and configure the collector to forward the data using the New Relic collector exporter.
• Configure your OpenTelemetry data source to send data to the native OpenTelemetry Protocol (OTLP) data ingestion endpoint. OTLP is an open source gRPC based protocol for sending telemetry data. The protocol is vendor agnostic and open source.

For more details please see:

• OpenTelemetry quick start
• Introduction to OpenTelemetry with New Relic
• Native OpenTelemetry Protocol (OTLP) support

This is a custom distribution of the OpenTelemetry Java agent that uses the New Relic OpenTelemetry exporter to send telemetry data to the New Relic platform.

First things first:

• If we don’t already know you, sign up for a New Relic account.
• Make sure you have an Insights insert key to send spans and metrics to New Relic.

You can either grab the published artifacts or you can build it yourself.

To build the integration, make sure you have JDK 8+, and then run the following command:

./gradlew assemble

The New Relic OpenTelemetry Integration is a standard Java agent. To use it, you just need the -javaagent startup flag and these minimum system properties:

-javaagent:/path/to/newrelic-opentelemetry-javaagent-*-all.jar
-Dnewrelic.api.key=YOUR_INSIGHTS_INSERT_KEY
-Dnewrelic.service.name=INSERT_A_DESCRIPTIVE_NAME

Since the New Relic OpenTelemetry Integration is built using the New Relic OpenTelemetry exporter, it uses the same system properties. For a list and description of all configurable properties, see New Relic OpenTelemetry exporter.

Here's an example of common startup properties:

-javaagent:/path/to/newrelic-opentelemetry-javaagent-*-all.jar
-Dnewrelic.api.key=YOUR_INSIGHTS_INSERT_KEY
-Dnewrelic.service.name=INSERT_A_DESCRIPTIVE_NAME
-Dio.opentelemetry.javaagent.slf4j.simpleLogger.log.com.newrelic.telemetry=debug
-Dnewrelic.enable.audit.logging=true
-Dnewrelic.trace.uri.override=SEE_THE_SECTION_BELOW_ABOUT_CHANGING_ENDPOINTS
-Dnewrelic.metric.uri.override=SEE_THE_SECTION_BELOW_ABOUT_CHANGING_ENDPOINTS

If you don't supply endpoints, the integration defaults to the following:

• Traces: https://trace-api.newrelic.com/trace/v1
• Metrics: https://metric-api.newrelic.com/metric/v1

You can override the default endpoints for this integration, for example, when switching to the EU region or setting up Infinite Tracing.

For details about using EU or Infinite Tracing URLs, see OpenTelemetry: Advanced configuration.

Go to one.newrelic.com, search for your service name. If you don't see your service, try running with debug and audit logging to confirm telemetry batches are being successfully sent. Here is an example of what you might see:

[Thread-6] DEBUG com.newrelic.telemetry.spans.SpanBatchSender - Sending a span batch (number of spans: 4) to the New Relic span ingest endpoint)
[Thread-6] DEBUG com.newrelic.telemetry.spans.json.SpanBatchMarshaller - Generating json for span batch.
[Thread-6] DEBUG com.newrelic.telemetry.transport.BatchDataSender - Response from New Relic ingest API: code: 202, body: {"requestId":"28fa2622-0001-b000-0000-01761fc2a899"}
[Thread-6] DEBUG com.newrelic.telemetry.TelemetryClient - Telemetry batch sent

For tips on how to find and query your data in New Relic, see Find trace/span data.

For general querying information, see:

• Query New Relic data
• Intro to NRQL

Here are the testing requirements:

• JDK 8+
• Docker

smoke-tests contains simple tests to verify that the resulting agent builds and applies correctly.

To run the smoke tests run the following command:

./gradlew test

To see the New Relic OpenTelemetry Integration in action, check out the Spring Pet Clinic sample application.

To set up the Pet Clinic with OpenTelemetry:

1. Build the New Relic OpenTelemetry Integration, as described in the Building section, or download the jar file from here.
2. Follow the steps in the Running petclinic locally section, but when executing the jar, add the Java agent, service name, and Insights insert key as follows:

java -javaagent:/path/to/newrelic-opentelemetry-javaagent-*-all.jar -Dnewrelic.api.key=YOUR_INSIGHTS_INSERT_KEY -Dnewrelic.service.name=pet-clinic -jar target/*.jar

3. Once it is running, click around a bit in the app at http://localhost:8080.
4. Go to one.newrelic.com.
5. In the upper right, click on the magnifying glass, and search for pet-clinic.
6. Click on the pet-clinic link to see data coming in!

New Relic hosts and moderates an online forum where you can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:

Support Channels

• New Relic Documentation: Comprehensive guidance for using our platform
• New Relic Community: The best place to engage in troubleshooting questions
• New Relic Developer: Resources for building a custom observability applications
• New Relic University: A range of online training for New Relic users of every level
• New Relic Technical Support 24/7/365 ticketed support. Read more about our Technical Support Offerings.

We encourage contributions to improve the New Relic OpenTelemetry Integration (Java Agent)! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].

The New Relic OpenTelemetry Integration (Java Agent) is licensed under the Apache 2.0 License.

The New Relic OpenTelemetry Integration (Java Agent) also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.