Golang SDK for New Relic integrations
If our on-host integrations don't meet your needs, we provide two options for creating your own:
- Our Flex integration tool: a simple way to report custom metrics by creating a configuration file that defines what data will be reported. This is recommended for most use cases.
- Our Integrations SDK: a more robust solution. We give you access to the complete set of tools we use to build our integrations and report all infrastructure integrations data types.
The Integrations SDK helps take the complexity out of building an integration by providing a set of useful Go language functions and data structures. For instance, some common use cases like reading values from command-line arguments or environment variables, initializing a structure with all the necessary fields for an integration defined by our SDK, or generating and printing a JSON to stdout, are covered and simplified by this package.
If you want to know more or you need specific documentation about the structures and functions provided by this package, you can take a look at the official package documentation in godoc.org (see below).
Before starting to write Go code, we suggest taking a look at golang's documentation to set up the environment and familiarize yourself with the golang language.
You can download the SDK code to your
GOPATH with the following command:
$ go get github.com/newrelic/infra-integrations-sdk/...
You can find the latest API documentation generated from the source code in godoc.
Infrastructure on-host integrations are executed periodically by the infrastructure agent. The integration
stdout is consumed by the agent.
stdout data is formatted as JSON.
The agent supports different JSON data-structures called integration protocols:
- v1: Legacy data structure to monitor local entity.
- v2: This version allows to monitor remote entities and keep support for previous local entity. Official doc
- v3: Improves remote entities support. See protocol v3 documentation.
Local vs remote entities
Entity is a specific thing we collect data about. We used this vague term because we want to support hosts, pods, load balancers, DBs, etc. in a generic way. In the previous SDK versions (v1 & v2) the entity was local and just one: the host.
In later versions the reporting host is called local entity, and it's optional to add metrics to it. You could just use remote entities to attach metrics.
For more information on the definition of a remote entity, please see the following document on local vs remote entites.
Upgrading from SDK v2 to v3
SDK and agent-protocol compatibility
SDK v1 and v2 use protocol-v1.
SDK v3 could use either protocol-v2 or protocol-v3.
This section shows the documentation of all the core components of the GoSDK v3, that is, all the packages that are required to set up and manage the integration data, as well as some other libraries that, despite not being part of the core SDK, implement common operations that may be reused in different integrations.
Command-line tool to scaffold new New Relic custom integrations
Integration data model
Legacy protocol v1 builder
In case you want to use the previous builder, you still can do it via
You can fetch it using:
go get gopkg.in/newrelic/nr-integrations-builder.v1
The Integrations Golang SDK supports getting metrics through JMX by calling the
jmx.Close() functions. This JMX support relies
on the nrjmx tool. Follow the steps in the nrjmx repository to build it and set the
NR_JMX_TOOL environment variable to point to the location of the nrjmx
executable. If the
NR_JMX_TOOL variable is not set, the SDK uses
/usr/bin/nrjmx by default.
GoSDK v3 provides a helper HTTP package to create secure HTTPS clients that require loading credentials from a Certificate Authority Bundle (stored in a file or in a directory).You can read more here.
Should you need assistance with New Relic products, you are in good hands with several support diagnostic tools and support channels.
If the issue has been confirmed as a bug or is a feature request, file a GitHub issue.
- 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.
At New Relic we take your privacy and the security of your information seriously, and are committed to protecting your information. We must emphasize the importance of not sharing personal data in public forums, and ask all users to scrub logs and diagnostic information for sensitive information, whether personal, proprietary, or otherwise.
We define “Personal Data” as any information relating to an identified or identifiable individual, including, for example, your name, phone number, post code or zip code, Device ID, IP address, and email address.
For more information, review New Relic’s General Data Privacy Notice.
We encourage your contributions to improve this project! Keep in mind that 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 (which is required if your contribution is on behalf of a company), drop us an email at firstname.lastname@example.org.
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
If you would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today.
infra-integrations-sdk is licensed under the Apache 2.0 License.
Package http provides an easy way to construct an http client with custom certificates and customizable timeout.
|Package http provides an easy way to construct an http client with custom certificates and customizable timeout.|
Package jmx is a library to get metrics through JMX.
|Package jmx is a library to get metrics through JMX.|