⚠️ The infrastructure integrations builder is no longer actively maintained. New Relic will keep this cli-tool for internal use only. Please consider using New Relic Flex and/or open source instrumentation depending on your use cases.
You can use this command-line tool to create and scaffold a new integration in Golang for the New Relic infrastructure agent.
The generated code uses the New Relic infrastructure integrations go SDK. Visit the go SDK documentation for more information about its API and structure.
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.
- Vendor Tool for Go, which is used for managing dependencies. The project that you create must be within a
$GOPATH/src
, otherwise the Vendor Tool won't work properly.
You need a Bash environment (for example, Git Bash for Windows), with make
and awk
commands installed.
To install the command-line tool, use go get
:
$ go get github.com/newrelic/nr-integrations-builder
After this step, the nr-integrations-builder
binary should be installed in $GOPATH/bin
or $GOBIN
(if this last one is set). In a common Golang workspace,
it's recommended having $GOPATH/bin
or $GOBIN
included in your $PATH
; that way, you would have nr-integrations-builder
available globally.
Currently, there is only one command available: init
. You can check out the available options for this command using the --help
option:
$ nr-integrations-builder init --help
Available options are:
-n
or--company-name
(string): company name (required)-c
or--company-prefix
(string): company prefix identifier (required)-p
or--destination-path
(string): the destination path where your integration will be generated as a subfolder (default: current directory)-e
or--entity-type
(string): type of entity to generate (remote
(default) orlocal
). To know the differences betweenremote
orlocal
entities, refer to the Entity definition section in the GoSDK v3 documents.
company-name
and company-prefix
flags must be specified. Otherwise, the nr-integrations-builder
will not initialize the integration.
Here's an example of how to use the tool:
$ nr-integrations-builder init \
--company-name myorganization \
--company-prefix myorg \
--destination-path $GOPATH/src/myorg-integrations/ \
mysql
It is also possible to specify the flags in short form:
nr-integrations-builder init mysql -n myorganization -c myorg -p $GOPATH/src/myorg-integrations/
The above command would generate the following file structure in the $GOPATH/src/myorg-integrations/
folder:
myorg-integrations
└── mysql
├── CHANGELOG.md
├── Makefile
├── README.md
├── myorg-mysql-config.yml
├── myorg-mysql-config.yml.template
├── myorg-mysql-definition.yml
├── src
│ ├── mysql.go
│ └── mysql_test.go
└── vendor
├── (...)
├── (vendored third-party dependencies)
├── (...)
└── vendor.json
The generated project will contain:
- A
Makefile
with the basic commands to verify, build and test the integration code. Runmake all
to generate an integration binary in thebin/
subfolder. - An
src/
folder with the basic integration main and test file. The generated main file creates a dummy integration with fake data. - Basic config and definition
.yml
files. For more information about configuration and description files, refer to the Integrations SDK documentation. vendor
folder andvendor/vendor.json
file with all the vendorized third-party libraries. For more information about how to install and use Go Vendor, refer to the Vendor Tool for Go docs.- Project description files:
README.md
andCHANGELOG.md
Continuing with the previously generated mysql
example, you must:
- Compile and build your integration binary file:
make all
- In the Infrastructure Agent's host:
- Copy the
myorg-mysql-config.yml
into one of the following folders:- Linux:
/etc/newrelic-infra/integrations.d
- Windows:
C:\Program Files\New Relic\newrelic-infra\integrations.d
- Linux:
- Copy the
myorg-mysql-definition.yml
file and the generatedbin/
folder (which contains the compiledmyorg-mysql
integration binary) into one of the following folders:- Linux:
/var/db/newrelic-infra/custom-integrations
- Windows:
C:\Program Files\New Relic\newrelic-infra\custom-integrations
- Linux:
- Copy the
- Restart the New Relic Infrastructure Agent service in the host where you installed the integration.
The command-line tool includes a suite of unit tests with each package which should be used to verify your changes don't break existing functionality.
To run the tests, invoke:
$ make test
For most contributions it is strongly recommended to add additional tests which exercise your changes. This helps us efficiently incorporate your changes into our mainline codebase and provides a safeguard that your change won't be broken by future development.
There are some rare cases where code changes do not result in changed functionality (for example, a performance optimization) and new tests are not required. In general, including tests with your pull request dramatically increases the chances that it will be accepted.
New Relic hosts and moderates an online forum where customers 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:
https://discuss.newrelic.com/c/support-products-agents/new-relic-infrastructure
We encourage your contributions to improve [project name]! 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 opensource@newrelic.com.
IMPORTANT: Never edit manually the scaffold/bindata.go file
. This must be generated using make generate
New Relic infrastructure integrations builder is licensed under the Apache 2.0 License.