The New Relic Java Telemetry SDK for sending telemetry data to New Relic. The current SDK supports sending dimensional metrics and spans to the Metric and Trace API, respectively.
Why is this cool?
Dimensional Metrics and Spans in New Relic! No agent required.
The telemetry SDK tries to be helpful, so your job of sending telemetry data to New Relic can be done in the right way, easily. We've covered all of the basics for you so you can focus on writing feature code directly related to your business need or interest.
Why would you want to use the telemetry SDK?
We imagine you (or your customers) are interested in the telemetry data, generated by your tool, framework, or code, in New Relic. You can write an exporter to do so! Check out the telemetry_examples module to get started.
For the most recently published version, see Releases
In order to send metrics or spans to New Relic, you will need an Insights Insert API Key. Please see New Relic Api Keys for more information.
Maven dependencies:
<dependency>
<groupId>com.newrelic.telemetry</groupId>
<artifactId>telemetry</artifactId>
<version>0.3.4</version>
</dependency>
<dependency>
<groupId>com.newrelic.telemetry</groupId>
<artifactId>telemetry-http-okhttp</artifactId>
<version>0.3.4</version>
</dependency>
Gradle dependencies:
compile("com.newrelic.telemetry:telemetry:0.3.4")
compile("com.newrelic.telemetry:telemetry-http-okhttp:0.3.4")
Take a look at the example code in the telemetry_examples module. We recommend looking at the TelemetryClientExample first.
Note: If you do not want to include okhttp as a transitive depenedency, you will need to provide a custom implementation of the
com.newrelic.telemetry.http.HttpPoster interface, rather than using the com.newrelic.telemetry:telemetry-http-okhttp library.
The Telemetry SDK uses slf4j for all logging. Having a slf4j implementation in your application is required in order to see log information. See the slf4j documentation for details.
The various builders for the Telemetry SDK components include an option to enableAuditLogging. Enabling this option will cause the
SDK to product additional logging at DEBUG level. This logging includes the details of every payload sent to the New Relic APIs, and the responses from those APIs.
WARNING: If you enable audit logging, all the data in your spans and metrics will be sent to your logging system. It is recommended that you only enable audit logging when absolutely necessary.
- Java 8 or greater
- For IDEA:
- lombok plugin installed
- Annotation processing enabled for the project (Sample instructions can be found here for popular IDEs)
- Docker & docker-compose must be installed for integration testing
CI builds are run on Azure Pipelines:
The project uses gradle 5 for building, and the gradle wrapper is provided.
To compile, run the tests and build the jars:
$ ./gradlew build
End-to-end integration tests are included. They are implemented with the testcontainers library; mock-server provides the backend.
There are two modes to run the integration tests.
- Run with gradle:
$ ./gradlew integration_test:test - Run the integration test classes in IDEA directly. It should "just work".
This project uses the google-java-format code style, and it is easily applied via an included gradle plugin:
$ ./gradlew googleJavaFormat verifyGoogleJavaFormat
Please be sure to run the formatter before committing any changes. There is a pre-commit-hook.sh which can
be applied automatically before commits by moving it into .git/hooks/pre-commit.
This is the core module for sending dimensional metrics and spans to New Relic. The library is published under maven coordinates:
com.newrelic.telemetry:telemetry-core
In order to send metrics and spans to New Relic, you will also need an Insights Insert API Key. Please see New Relic Api Keys for more information.
This module contains code for using all New Relic telemetry modules, gathered in one place, as well as what we consider "best practice" implementations of how to interact with the lower-level modules.
The telemetry library is published under the maven coordinates:
com.newrelic.telemetry:telemetry
This is an implementation of the required http client interface using okhttp as the underlying library.
The telemetry-http-okhttp library is published under the maven coordinates:
com.newrelic.telemetry:telemetry-http-okhttp
Example code for using the metrics and telemetry APIs.
Integration test module. Uses docker-compose based tests to test the SDK end-to-end.
The New Relic Java Telemetry SDK is licensed under the Apache 2.0 License.
The New Relic Java Telemetry SDK also uses source code from third party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third party notices document.
Full details are available in our CONTRIBUTING.md file. We'd love to get your contributions to improve the Java Telemetry SDK! 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. To execute our corporate CLA, which is required if your contribution is on behalf of a company, or if you have any questions, please drop us an email at [email protected].
The New Relic Telemetry APIs are rate limited. Please reference the documentation for New Relic Metrics API and New Relic Trace API Requirements and Limits on the specifics of the rate limits.