--- title: Guide to using the Go agent API source: https://docs.newrelic.com/docs/apm/agents/go-agent/api-guides/guide-using-go-agent-api --- The [New Relic Go agent](https://docs.newrelic.com/docs/agents/go-agent/get-started/introduction-new-relic-go) 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](https://docs.newrelic.com/docs/apis/getting-started/introduction-new-relic-apis). > #### ⚠️ IMPORTANT > > Because Go applications run from a compiled, native binary file, you need to [manually instrument your code](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-transactions) to monitor transactions for your Go applications by adding New Relic methods to it. ## Monitor transactions [#monitor] Before you manually instrument your code to monitor [transactions](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm), make sure that you meet the [compatibility and requirements](https://docs.newrelic.com/docs/agents/go-agent/get-started/go-agent-compatibility-requirements) and that you are using the [latest version of the Go agent](https://docs.newrelic.com/docs/release-notes/agent-release-notes/go-release-notes). | If you want to... | Use this method... | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Start timing a transaction | [`StartTransaction()`](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-transactions#go-txn) | | Stop timing a transaction | [`txn.End()`](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-transactions#go-txn) | | Prevent a transaction from reporting to New Relic | [`Ignore()`](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic#Transaction.Ignore) | | Prevent an active transaction from reporting Apdex to New Relic | [`IgnoreApdex()`](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic#Transaction.IgnoreApdex) | | Use the standard HTTP library package to monitor transactions | [HTTP request wrapping](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-transactions#http-handler-txns) | ## Time specific methods using segments [#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](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-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](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-segments#segment-code-block) - [Functions](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-segments#segment-function) - [Datastores](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-segments#go-datastore-segments) - [External services](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-segments#go-external-segments) If the work is happening in a different goroutine from where the transaction started, you must use the [`NewGoroutine()`](https://docs.newrelic.com/docs/agents/go-agent/features/tracing-asynchronous-applications) API. ## Enhance the metadata of a transaction [#metadata] 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](https://docs.newrelic.com/docs/agents/manage-apm-agents/troubleshooting/metric-grouping-issues#video), change the default names for your transactions to make them more identifiable. - If you want to create dashboards for your transactions, add [custom attributes](https://docs.newrelic.com/docs/agents/go-agent/instrumentation/go-agent-attributes#custom-attributes). | If you want to... | Use this... | | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | - | | Change the name of a transaction | [`SetName()`](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic#Transaction.SetName) | | | Add metadata (such as your customer’s account name or subscription level) to your transactions | [`AddAttribute()`](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic#Transaction.AddAttribute) | | ## Instrument calls to external services [#externals] 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()`](https://docs.newrelic.com/docs/agents/go-agent/get-started/instrument-go-segments#go-external-segments) | | Connect activity to another app instrumented by a New Relic agent | [Cross application tracing](https://docs.newrelic.com/docs/agents/go-agent/features/cross-application-tracing-go) > #### ⚠️ IMPORTANT > > Cross application tracing has been deprecated in favor of [Distributed tracing](https://docs.newrelic.com/docs/agents/go-agent/features/distributed-tracing-go) 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](https://docs.newrelic.com/docs/agents/go-agent/features/distributed-tracing-go) | ## Collect or ignore errors [#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](https://docs.newrelic.com/docs/agents/go-agent/configuration/go-agent-configuration#error-collector). | If you want to... | Use this... | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Report an error the agent does not report automatically | [`NoticeError()`](https://github.com/newrelic/go-agent/blob/master/GUIDE.md#error-reporting) | | Report an expected error the agent does not report automatically and not trigger alerts | [`NoticeExpectedError()`](https://github.com/newrelic/go-agent/blob/master/GUIDE.md#error-reporting) | | Prevent the agent from reporting an error at all | [`ErrorCollector.IgnoreStatusCodes()`](https://docs.newrelic.com/docs/agents/go-agent/configuration/go-agent-configuration#error-ignore-status) | ## Error fingerprinting: dynamically apply an error group to each noticed error [#error-fingerprinting] A callback function can be supplied to the agent to dynamically apply a desired [error group](https://docs.newrelic.com/docs/errors-inbox/errors-inbox) to each noticed error. Use the Go agent config option [`newrelic.ConfigSetErrorGroupCallbackFunction`](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration/go-agent-configuration/#error-group-callback) 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: ```go 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 [#user-tracking] 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 [#custom-data] To record [custom data](https://docs.newrelic.com/docs/data-analysis/metrics/analyze-your-metrics/data-collection-metric-timeslice-event-data) with the Go agent, you can use any of the following methods: - [Custom events](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/insert-custom-events-new-relic-apm-agents#go) - [Custom attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/add-custom-attributes-apm-data) - [Custom metrics](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-metrics) | If you want to... | Use this... | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Send data about an event so you can analyze it in [New Relic](https://docs.newrelic.com/docs/insights/use-insights-ui/getting-started/introduction-new-relic-insights) | [`RecordCustomEvent()`](https://docs.newrelic.com/docs/agents/go-agent/features/create-custom-events-insights-go) | | Tag your events with metadata to filter and facet them | [`AddAttribute()`](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic#Transaction.AddAttribute) | | Report custom performance data for a specified period of time | [`RecordCustomMetric()`](https://docs.newrelic.com/docs/agents/go-agent/instrumentation/create-custom-metrics-go) | ## See related logs [#logs] To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs: - [`GetTraceMetadata`](https://pkg.go.dev/github.com/newrelic/go-agent/v3/newrelic#Transaction.GetTraceMetadata) - [`GetLinkingMetadata`](https://pkg.go.dev/github.com/newrelic/go-agent/v3/newrelic#Transaction.GetLinkingMetadata) For more information about correlating log data with other telemetry data, see our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-go/) documentation. ## Monitor browser performance with browser monitoring [#browser] To monitor browser performance for your app using [browser monitoring and the Go agent](https://docs.newrelic.com/docs/agents/go-agent/features/install-new-relic-browser-go-apps), you can use any of the following methods: | If you want to... | Use this... | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Install the browser agent | Use the [browser copy/paste method](https://docs.newrelic.com/docs/browser/new-relic-browser/installation/install-new-relic-browser-agent#copy-paste-app) | | Add the browser monitoring JavaScript code directly to HTML pages | [`BrowserTimingHeader()`](https://docs.newrelic.com/docs/agents/go-agent/features/install-new-relic-browser-go-apps) | ## Change the configuration settings for the Go agent [#configuration] To manage some aspects of New Relic monitoring, you can [change your Go agent configuration settings](https://docs.newrelic.com/docs/agents/go-agent/configuration/go-agent-configuration); for example: - Turning on high-security mode - Adding custom labels for filtering and sorting - Managing what information is reported