Guide to using the Go agent API

The New Relic Go agent monitors your Go language applications and microservices to help you identify and solve performance issues. The Go agent API is one of several available New Relic APIs.

Monitor transactions

Before you manually instrument your code to monitor transactions, make sure that you meet the compatibility and requirements and that you are using the latest version of the Go agent.

Time specific methods using segments

If a transaction is already visible in New Relic, but you do not have enough data about a particular method that was called during that transaction, you can create segments. For example, if you want to time a method that has complex logic, you can create a segment for each of the methods in the transaction.

To instrument a method within an existing transaction, create segments for the following:

• Blocks of code
• Functions
• Datastores
• External services

If the work is happening in a different goroutine from where the transaction started, you must use the NewGoroutine() API.

Enhance the metadata of a transaction

You can manage the metadata that New Relic reports for transactions. Here are some examples of when you might want a different level of detail for your transactions:

• If you are experiencing a metric grouping issue, change the default names for your transactions to make them more identifiable.
• If you want to create dashboards for your transactions, add custom attributes.

Instrument calls to external services

Use these methods to collect data about your app’s connections to other apps or databases:

Collect or ignore errors

The agent detects errors automatically. If you want to change the way the Go agent reports errors to New Relic, change the error collector configuration.

Error fingerprinting: dynamically apply an error group to each noticed error

A callback function can be supplied to the agent to dynamically apply a desired error group to each noticed error. Use the Go agent config option newrelic.ConfigSetErrorGroupCallbackFunction to provide the agent with a callback.

This API call takes a callback method (must be of type newrelic.ErrorGroupCallback) as its only argument. Here's an example:

myCallbackFunc := CallbackFunc(errorInfo newrelic.ErrorInfo) string {
   if errorInfo.Message == "example error message" {
       return "example group 1"
   }
   if errorInfo.GetHttpResponseCode() == "403" && errorInfo.GetUserID() == "user 2" {
       return "user 2 payment issue"
   }

   // use default error grouping behavior
   return ""
}

app, err := newrelic.NewApplication(
   newrelic.ConfigSetErrorGroupCallbackFunction(myCallbackFunc)
)

In the example shown, a callback proc is created that will accept an object of type newrelic.ErrorInfo and return a string representing the error group. Note that when your ErrorGroupCallback function returns a non-empty string, it will override the default grouping behavior of a noticed error and apply server-side grouping logic.

The callback function is expected to receive exactly one input argument, a newrelic.ErrorInfo object. The object contains the following:

User tracking: associating a user ID with each transaction and error

Transactions and errors can be associated with a user ID if one is known to the New Relic Go agent. Use the Go agent API txn.SetUserID("example user ID") to provide the agent with a user ID.

This API call requires a single argument of a string representing a unique identifier for an end user. This string can be a UUID, a database id, or similar. The API call should be made at least once per transaction to inform the New Relic Go agent of what user ID to associate the transaction with. Then in turn, when the agent notices errors during the lifespan of the transaction, the errors will bear an enduser.id agent attribute that holds the user ID value.

Because the API is intended to be called every time a new user ID has entered scope, it will ideally be called via middleware that is aware of user session creation. Once the New Relic Go agent has been made aware of the user ID, it will supply the enduser.id agent attribute on the current transaction as well as on any errors noticed during the current transaction's lifespan.

Send custom data from your app

To record custom data with the Go agent, you can use any of the following methods:

• Custom events
• Custom attributes
• Custom metrics

See related logs

To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs:

• GetTraceMetadata
• GetLinkingMetadata

For more information about correlating log data with other telemetry data, see our logs in context documentation.

Monitor browser performance with browser monitoring

To monitor browser performance for your app using browser monitoring and the Go agent, you can use any of the following methods:

Change the configuration settings for the Go agent

To manage some aspects of New Relic monitoring, you can change your Go agent configuration settings; for example:

• Turning on high-security mode
• Adding custom labels for filtering and sorting
• Managing what information is reported