infra-integrations-sdk

Golang SDK for New Relic integrations

Infrastructure monitoring provided by New Relic offers flexible, dynamic server monitoring, including integrations for many popular services.

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

Installation

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

Read the SDK documentation to learn about all the packages and functions it provides. If you need ideas or inspiration to start writing integrations, follow the tutorial.

API specification

You can find the latest API documentation generated from the source code in godoc.

Agent API

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

https://github.com/newrelic/infra-integrations-sdk/blob/master/docs/v2tov3.md

SDK and agent-protocol compatibility

SDK v1 and v2 use protocol-v1.

SDK v3 could use either protocol-v2 or protocol-v3.

Tools

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

https://github.com/newrelic/nr-integrations-builder

Integration data model

https://github.com/newrelic/infra-integrations-sdk/blob/master/docs/toolset/integration.md

Configuration arguments

https://github.com/newrelic/infra-integrations-sdk/blob/master/docs/toolset/args.md

Internal logging

https://github.com/newrelic/infra-integrations-sdk/blob/master/docs/toolset/log.md

Persistence/Key-Value storage

https://github.com/newrelic/infra-integrations-sdk/blob/master/docs/toolset/persist.md

Legacy protocol v1 builder

In case you want to use the previous builder, you still can do it via gopkg.in/newrelic/nr-integrations-builder.v1.

You can fetch it using:

go get gopkg.in/newrelic/nr-integrations-builder.v1

Libraries

JMX support

The Integrations Golang SDK supports getting metrics through JMX by calling the jmx.Open(), jmx.OpenWithSSL, jmx.Query(), and 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.

HTTP support

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.

Support

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.

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.

Privacy

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.

Contribute

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 opensource@newrelic.com.

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.

License

infra-integrations-sdk is licensed under the Apache 2.0 License.