Follow these steps to instrument your application. More information is available in the GUIDE.md.
The New Relic Go agent is a Go library with no dependencies. Install it the same way you would install any other Go library. The simplest way is to run:
go get github.com/newrelic/go-agent
Then import the github.com/newrelic/go-agent package in your application.
In your main function, or an init block, create an
Application using
a Config.
Application is the
starting point for all instrumentation.
func main() {
// Create a Config:
config := newrelic.NewConfig("Your Application Name", "__YOUR_NEW_RELIC_LICENSE_KEY__")
// Modify the Config to add logging or alter agent behavior:
config.Logger = NewLogger(os.Stdout)
// Then create an Application:
app, err := newrelic.NewApplication(config)
// If an application could not be created then err will reveal why.
if err != nil {
fmt.Println("unable to create New Relic Application", err)
}
// Now use the app to instrument everything!
}Now start your application, and within minutes it will appear in the New Relic UI. Your application in New Relic won't contain much data (until we complete the steps below!), but you will already be able to see a Go runtime page that shows goroutine counts, garbage collection, memory, and CPU usage.
Transactions are used to time inbound requests and background tasks. Use them to see your application's throughput and response time. The instrumentation strategy depends on the framework you're using:
If you are using the standard library http package, use
WrapHandle and
WrapHandleFunc.
As an example, the following code:
http.HandleFunc("/users", usersHandler)Can be instrumented like this:
http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))If you are using a popular framework, then there may be an integration package designed to instrument it. List of New Relic Go agent integration packages.
If you aren't using the http standard library package or an
integration package supported framework, you can create transactions
directly using the application's StartTransaction method:
func myHandler(rw http.ResponseWriter, req *http.Request) {
// The response writer and request parameters are optional. If your
// request is not an *http.Request, try using Transaction.SetWebRequest
// with a custom newrelic.WebRequest. If the request parameter is nil
// then the transaction is considered a background task.
txn := app.StartTransaction("myHandler", rw, req)
defer txn.End()
}Be sure to use a limited set of unique names to ensure that transactions are grouped usefully. Don't use dynamic URLs!
More information about transactions
Segments show you where the time in your transactions is being spent. There are four types of segments: Segment, ExternalSegment, DatastoreSegment, and MessageProducerSegment.
Creating a segment requires access to the transaction. You can pass the transaction around your functions as an explicit transaction parameter or inside a context.Context. Functions FromContext and NewContext make it easy to store and retrieve the transaction from a context.
You may not even need to add the transaction to the context: WrapHandle and WrapHandleFunc add the transaction to the request's context automatically.
func instrumentMe(ctx context.Context) {
txn := newrelic.FromContext(ctx)
segment := newrelic.StartSegment(txn, "instrumentMe")
time.Sleep(1 * time.Second)
segment.End()
}
func myHandler(w http.ResponseWriter, r *http.Request) {
instrumentMe(r.Context())
}
func main() {
cfg := newrelic.NewConfig("My App", "__YOUR_NEW_RELIC_LICENSE_KEY__")
app, _ := newrelic.NewApplication(cfg)
http.HandleFunc(newrelic.WrapHandleFunc(app, "/handler", myHandler))
}More information about segments
Read our GUIDE.md and the godocs to learn more about what else you can do with the Go Agent.