Skip to content
This repository has been archived by the owner on Feb 16, 2023. It is now read-only.

newrelic/newrelic-opentelemetry-integration-java

Archived header

Archival Notice

❗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:


New Relic OpenTelemetry Integration (Java agent)

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.

Prerequisites

First things first:

Get the software

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

Published Artifacts

Group Name Link Description
com.newrelic.telemetry newrelic-opentelemetry-javaagent Maven The java agent

Build

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

./gradlew assemble

Startup

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

Change endpoints

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

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.

Find and use your data in New Relic

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:

Testing

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

Example

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

Support

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

Contributing

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].

License

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.