resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
terraform/vendor/github.com/newrelic/go-agent/GUIDE.md

9.2 KiB
Raw Blame History

New Relic Go Agent Guide

Installation

Installing the Go Agent is the same as installing 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.

Config and Application

In your main function or in an init block:

config := newrelic.NewConfig("Your Application Name", "__YOUR_NEW_RELIC_LICENSE_KEY__")
app, err := newrelic.NewApplication(config)

Find your application in the New Relic UI. Click on it to see the Go runtime tab that shows information about goroutine counts, garbage collection, memory, and CPU usage.

If you are working in a development environment or running unit tests, you may not want the Go Agent to spawn goroutines or report to New Relic. You're in luck! Set the config's Enabled field to false. This makes the license key optional.

config := newrelic.NewConfig("Your Application Name", "")
config.Enabled = false
app, err := newrelic.NewApplication(config)

Logging

The agent's logging system is designed to be easily extensible. By default, no logging will occur. To enable logging, assign the Config.Logger field to something implementing the Logger interface. A basic logging implementation is included.

To log at debug level to standard out, set:

config.Logger = newrelic.NewDebugLogger(os.Stdout)

To log at info level to a file, set:

w, err := os.OpenFile("my_log_file", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
if nil == err {
  config.Logger = newrelic.NewLogger(w)
}

logrus

If you are using logrus and would like to send the agent's log messages to its standard logger, import the github.com/newrelic/go-agent/_integrations/nrlogrus package, then set:

config.Logger = nrlogrus.StandardLogger()

Transactions

Transactions time requests and background tasks. Each transaction should only be used in a single goroutine. Start a new transaction when you spawn a new goroutine.

The simplest way to create transactions is to use Application.StartTransaction and Transaction.End.

txn := app.StartTransaction("transactionName", responseWriter, request)
defer txn.End()

The response writer and request parameters are optional. Leave them nil to instrument a background task.

txn := app.StartTransaction("backgroundTask", nil, nil)
defer txn.End()

The transaction has helpful methods like NoticeError and SetName. See more in transaction.go.

If you are using the http standard library package, use WrapHandle and WrapHandleFunc. These wrappers automatically start and end transactions with the request and response writer. See instrumentation.go.

http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))

To access the transaction in your handler, use type assertion on the response writer passed to the handler.

func myHandler(w http.ResponseWriter, r *http.Request) {
	if txn, ok := w.(newrelic.Transaction); ok {
		txn.NoticeError(errors.New("my error message"))
	}
}

Segments

Find out where the time in your transactions is being spent! Each transaction should only track segments in a single goroutine.

Segment is used to instrument functions, methods, and blocks of code. A segment begins when its StartTime field is populated, and finishes when its End method is called.

segment := newrelic.Segment{}
segment.Name = "mySegmentName"
segment.StartTime = newrelic.StartSegmentNow(txn)
// ... code you want to time here ...
segment.End()

StartSegment is a convenient helper. It creates a segment and starts it:

segment := newrelic.StartSegment(txn, "mySegmentName")
// ... code you want to time here ...
segment.End()

Timing a function is easy using StartSegment and defer. Just add the following line to the beginning of that function:

defer newrelic.StartSegment(txn, "mySegmentName").End()

Segments may be nested. The segment being ended must be the most recently started segment.

s1 := newrelic.StartSegment(txn, "outerSegment")
s2 := newrelic.StartSegment(txn, "innerSegment")
// s2 must be ended before s1
s2.End()
s1.End()

A zero value segment may safely be ended. Therefore, the following code is safe even if the conditional fails:

var s newrelic.Segment
if txn, ok := w.(newrelic.Transaction); ok {
	s.StartTime = newrelic.StartSegmentNow(txn),
}
// ... code you wish to time here ...
s.End()

Datastore Segments

Datastore segments appear in the transaction "Breakdown table" and in the "Databases" tab.

Datastore segments are instrumented using DatastoreSegment. Just like basic segments, datastore segments begin when the StartTime field is populated and finish when the End method is called. Here is an example:

s := newrelic.DatastoreSegment{
	// Product is the datastore type.  See the constants in datastore.go.
	Product: newrelic.DatastoreMySQL,
	// Collection is the table or group.
	Collection: "my_table",
	// Operation is the relevant action, e.g. "SELECT" or "GET".
	Operation: "SELECT",
}
s.StartTime = newrelic.StartSegmentNow(txn)
// ... make the datastore call
s.End()

This may be combined into a single line when instrumenting a datastore call that spans an entire function call:

defer newrelic.DatastoreSegment{
	StartTime:  newrelic.StartSegmentNow(txn),
	Product:    newrelic.DatastoreMySQL,
	Collection: "my_table",
	Operation:  "SELECT",
}.End()

External Segments

External segments appear in the transaction "Breakdown table" and in the "External services" tab.

External segments are instrumented using ExternalSegment. Populate either the URL or Request field to indicate the endpoint. Here is an example:

func external(txn newrelic.Transaction, url string) (*http.Response, error) {
	defer newrelic.ExternalSegment{
		StartTime: newrelic.StartSegmentNow(txn),
		URL:   url,
	}.End()

	return http.Get(url)
}

We recommend using the Request and Response fields since they provide more information about the external call. The StartExternalSegment helper is useful when the request is available. This function may be modified in the future to add headers that will trace activity between applications that are instrumented by New Relic.

func external(txn newrelic.Transaction, req *http.Request) (*http.Response, error) {
	s := newrelic.StartExternalSegment(txn, req)
	response, err := http.DefaultClient.Do(req)
	s.Response = response
	s.End()
	return response, err
}

NewRoundTripper is another useful helper. As with all segments, the round tripper returned must only be used in the same goroutine as the transaction.

client := &http.Client{}
client.Transport = newrelic.NewRoundTripper(txn, nil)
resp, err := client.Get("http://example.com/")

Attributes

Attributes add context to errors and allow you to filter performance data in Insights.

You may add them using the Transaction.AddAttribute method.

txn.AddAttribute("key", "value")
txn.AddAttribute("product", "widget")
txn.AddAttribute("price", 19.99)
txn.AddAttribute("importantCustomer", true)

Some attributes are recorded automatically. These are called agent attributes. They are listed here:

To disable one of these agents attributes, AttributeResponseCode for example, modify the config like this:

config.Attributes.Exclude = append(config.Attributes.Exclude, newrelic.AttributeResponseCode)

Custom Events

You may track arbitrary events using custom Insights events.

app.RecordCustomEvent("MyEventType", map[string]interface{}{
	"myString": "hello",
	"myFloat":  0.603,
	"myInt":    123,
	"myBool":   true,
})

Request Queuing

If you are running a load balancer or reverse web proxy then you may configure it to add a X-Queue-Start header with a Unix timestamp. This will create a band on the application overview chart showing queue time.