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. 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.
go install github.com/newrelic/go-easy-instrumentation@latestMake sure $GOPATH/bin (or $HOME/go/bin by default) is in your PATH.
From your application directory:
cd /path/to/your/app
go-easy-instrumentation instrument .
git apply new-relic-instrumentation.diffOr specify a path from anywhere:
go-easy-instrumentation instrument /path/to/your/app
git apply /path/to/your/app/new-relic-instrumentation.diffAlternative: Build from source
git clone https://github.com/newrelic/go-easy-instrumentation.git
cd go-easy-instrumentation
go build -o go-easy-instrumentation .
sudo mv go-easy-instrumentation /usr/local/bin/ # or anywhere on your PATH| Flag | Short | Description |
|---|---|---|
--debug |
-d |
Enable debug logging with text-mode output (no TUI) |
--exclude |
-e |
Comma-separated list of folders to exclude |
--output |
-o |
Custom diff output file path (must be .diff) |
go-easy-instrumentation instrument --debug /path/to/your/app
go-easy-instrumentation instrument --exclude "vendor,testdata" /path/to/your/app
go-easy-instrumentation instrument --output /tmp/changes.diff /path/to/your/appNote: In non-TTY environments (CI/CD, Docker, piped output), the tool automatically uses text-mode output.
Run without a subcommand to scan the current directory and choose which files to instrument:
go-easy-instrumentation
go-easy-instrumentation --exclude "vendor,end-to-end-tests"go run . instrument /path/to/your/appThis 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.
- It captures any existing transactions in your application and doesn't add additional transactions.
- 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.
The scope of what this tool can instrument in your application is limited to these actions:
- A best effort to capture errors at the root cause
- Tracing locally defined synchronous functions that are invoked in the application's
main()method with a transaction. Note that we will not attempt to trace async code in the main method due to issues of complexity, and will instead prompt you to manually instrument this code at your own discretion. - Starting tracing from entrypoints into your application with instrumentation from one of the supported libraries
- Injecting distributed tracing into external traffic with one of the supported libraries
The following libraries are supported for automatic instrumentation. Listed below are the minimum version of this tool needed to support each library, however it is always recommended that you upgrade to the latest version of this tool since there are a number of improvements in instrumentation coverage and quality that you would otherwise miss out on.
| Library Name | Minimum Version |
|---|---|
| net/http | v1.0.0 |
| gRPC | v1.0.0 |
| Gin | v1.0.0 |
| Go-chi | v1.0.0 |
| mysql | v1.0.0 |
| slog | v1.0.0 |
Updating or Downgrading Go Easy Instrumentation is a straightforward process.
- Check for new tagged releases OR run the following command within the project folder:
git tag - Change the tag version:
git checkout <tag_name>
Unit tests can be run from the root of this repository with this command:
go test ./...The end to end suite is designed to run easily on a developer's local machine. To run this suite, run this command from the root directory of this repository:
./end-to-end-tests/testrunnerTo modify which tests get run, modify the end-to-end-tests/testcases.json file in your local development environment.
For detailed instructions on how to generate instrumentation suggestions, see our documentation at docs.newrelic.com.
Should you need assistance with New Relic products, you are in good hands with several support channels.
If the issue has been confirmed as a bug or is a Feature request, please file a Github issue.
- New Relic Documentation: Comprehensive guidance for using our platform
- Troubleshooting framework: Steps you through common troubleshooting questions
- 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
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 opensource@newrelic.com.
To learn more about how to contribute features to this project, read the parser readme. The godoc for this project is also kept up to date, and can be a great resource.
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.