• EnglishEspañol日本語한국어Português
  • Log inStart now

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.

Important

Because Go applications run from a compiled, native binary file, you need to manually instrument your code to monitor transactions for your Go applications by adding New Relic methods to it.

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.

If you want to...

Use this method...

Start timing a transaction

StartTransaction()

Stop timing a transaction

txn.End()

Prevent a transaction from reporting to New Relic

Ignore()

Use the standard HTTP library package to monitor transactions

HTTP request wrapping

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:

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.

If you want to...

Use this...

Change the name of a transaction

SetName()

Add metadata (such as your customer’s account name or subscription level) to your transactions

AddAttribute()

Instrument calls to external services

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

If you want to...

Use this...

Time a call to an external resource (such as an external service, database server, or message queue)

StartExternalSegment()

Connect activity to another app instrumented by a New Relic agent

Cross application tracing

Important

Cross application tracing has been deprecated in favor of Distributed tracing and will be removed in a future agent version.

See the path that a request takes as it travels through a distributed system.

Distributed tracing

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.

If you want to...

Use this...

Report an error the agent does not report automatically

NoticeError()

Report an expected error the agent does not report automatically and not trigger alerts

NoticeExpectedError()

Prevent the agent from reporting an error at all

ErrorCollector.IgnoreStatusCodes()

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:

Key

Value

Error

The noticed Go error object. This will be nil for HTTP errors and Panics.

TimeOccured

The time.Time when the error was noticed by the agent.

Message

The error message.

Class

The New Relic error class. If an error implements errorClasser, its value will be derived from that. Otherwise, it will be derived from the way the error was collected by the agent. For HTTP errors, this will be the error number. Panics will be the public constant value newrelic.PanicErrorClass. Otherwise, the error class will be extracted from the root error object by calling reflect.TypeOf(). The most common root error class is *errors.errorString.

Expected

A bool that is true when the error was expected.

TransactionName

The formatted name of a transaction as it would appear in the New Relic UI.

GetTransactionUserAttributes(attribute string)

A method that takes an attribute name as an imput, then looks up and returns a transaction user attribute as an interface{}, and a bool that is true if the key was found in the attribute map.

GetErrorAttribute(attribute string)

A method that takes an attribute name as an input, then looks up and returns an error user attribute as an interface{}, and a bool that is true if the key was found in the error attributes map.

GetStackTraceFrames()

A method that returns a slice of StackTraceFrame objects containing a maximum of 100 relevant stack trace lines for an error. Note that calling this method may be expensive because the slice needs to be allocated and populated. It's recommended that this method is only called when needed to optimize performance.

GetRequestURI()

A method that returns the URI of the HTTP request made during the parent transaction of the current error. If no web request occured, an empty string will be returned.

GetRequestMethod()

A method that returns the HTTP method of the web request that occurred during the parent transaction of this error. If no web request occured, an empty string will be returned.

GetHttpResponseCode()

A method that returns the HTTP response code that was returned during the web request that occured during the parent transaction of this error. If no web request occured, an empty string will be returned.

GetUserID()

A method that returns the UserID that was applied to this error and transaction. If no UserID was defined, an empty string will be returned.

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:

If you want to...

Use this...

Send data about an event so you can analyze it in New Relic

RecordCustomEvent()

Tag your events with metadata to filter and facet them

AddAttribute()

Report custom performance data for a specified period of time

RecordCustomMetric()

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:

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 and the Go agent, you can use any of the following methods:

If you want to...

Use this...

Install the browser agent

Use the browser copy/paste method

Add the browser monitoring JavaScript code directly to HTML pages

BrowserTimingHeader()

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
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.