Go easy instrumentation

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 the Go easy 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.

Preview notice

How it works

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:

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

What is instrumented?

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
• Adding middleware to supported libraries for tracing
• Injecting distributed tracing into external traffic

Supported Libraries

• standard library
• net/http
• gin
• gRPC

Installation

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.

Install Go easy instrumentation:

$
go install github.com/newrelic/go-easy-instrumentation@latest

$
export PATH=$PATH:$(go env GOPATH)/bin

$
go env -w GOPATH=c:\go-work

Generate instrumentation suggestions

This tool works best with Git. We recommend you verify your application is on a branch without any unstaged changes before applying any of the generated changes to it. After checking that, follow these steps to generate and apply the changes that install the New Relic Go agent in an application:

1. Run the following CLI command to create a file named new-relic-instrumentation.diff in your working directory:
   bash

   Copy

   $
   go-easy-instrumentation instrument ../my-application/

2. Open the .diff file and verify or correct the contents.
3. When you are satisfied with the instrumentation suggestions, save the file, and then apply the changes:
   bash

   Copy

   $
   mv new-relic-instrumentation.diff ../my-application/
   $
   cd ../my-application
   $
   git apply new-relic-instrumentation.diff

Once the changes are applied, the application should run with the New Relic Go agent installed. If the agent installation is not working the way you want it to, you can easily recover by using common Git commands. For example, you could try one of the following:

• Stash the changes with git stash
• Revert the code to a previous commit

What's next?

If you have any suggestions or find issues, please create a Github issue.