Go is a compiled language with an opaque runtime, making it unable to support automatic instrumentation like other languages. For this reason, the New Relic Go agent is designed as an SDK. Since the Go agent is an SDK, it requires more manual work to set up than agents for languages that support automatic instrumentation.
In an effort to make instrumentation easier, the Go agent team created an instrumentation tool that is currently in preview. This tool does most of the work for you by suggesting changes to your source code that instrument your application with the New Relic Go agent.
To get started, check out this four-minute video, or skip down to How it works.
This feature is currently provided as part of a preview and is subject to our New Relic Experimental policies. Recommended code changes are suggestions only and should be subject to human review for accuracy, applicability, and appropriateness for your environment. This feature should only be used in non-critical, non-production environments that do not contain sensitive data.
This project, its code, and the UX are under heavy development, and should be expected to change. Please take this into consideration when participating in this preview. If you encounter any issues, please report them using Github issues and fill out as much of the issue template as you can so we can improve this tool.
This tool doesn't interfere with your application's operation, and it doesn't make any changes to your code directly. Here's what happens when you run the tool:
- It analyzes your code and suggests changes that allow the Go agent to capture telemetry data.
- You review the changes in the .diff file and decide which changes to add to your source code.
As part of the analysis, this tool may invoke go get or other Go language toolchain commands which may modify your go.mod file, but not your actual source code.
IMPORTANT: This tool can't detect if you already have New Relic instrumentation. Please only use this on applications without any instrumentation.
The scope of what this tool can instrument in your application is limited to these actions:
- Capturing errors in any function wrapped or traced by a transaction
- Tracing locally defined functions that are invoked in the application's
main()method with a transaction - Tracing async functions and function literals with an async segment
- Wrapping HTTP handlers
- Injecting distributed tracing into external traffic
ONLY the following Go packages and libraries are currently supported:
- standard library
- net/http
Before you start the installation steps below, make sure you have a version of Go installed that is within the support window for the current Go programming language lifecycle.
- Clone this repository to a directory on your system. For example:
git clone .../go-easy-instrumentation.git
- Go into that directory:
cd go-easy-instrumentation - Resolve any third-party dependencies:
go mod tidy
For detailed instructions on how to generate instrumentation suggestions, see our documentation at docs.newrelic.com.
This is an experimental product, and New Relic is not offering official support at the moment. Please create issues in Github if you are encountering a problem that you're unable to resolve. When creating issues, its vital that you include as much of the requested information as possible. This enables us to get to the root cause of the issue much more quickly. Please also make sure to search existing issues before creating a new one.
We encourage your contributions! 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].
Go easy instrumentation is licensed under the Apache 2.0 License.
This tool 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.