You can edit configuration settings for the Go agent to control some aspects of how New Relic monitors your app; for example:
- Turn high-security mode on.
- Add custom labels for filtering and sorting in the UI.
- Turn off the collection of errors, transaction events, transaction traces, and custom events.
Configuration methods and precedence
The primary way to configure the Go agent is by modifying the newrelic.Config
struct as part of calling newrelic.NewApplication()
, which is part of the standard installation process. With Go agent versions 2.7.0 or higher, you can also set a limited number of configuration options using server-side configuration in the UI.
The Go agent follows this order of precedence for configuration. If enabled, server-side configuration overrides all corresponding values in the newrelic.Config
struct, even if the server-side values are left blank.

Here are detailed descriptions of each configuration method:
- Server-side configuration (2.7.0 or higher)
-
Server-side configuration is available with Go agent versions 2.7.0 or higher. This allows you to configure certain settings in the New Relic UI. This applies your changes automatically to all agents even if they run across multiple hosts. Where available, this document includes the UI labels for server-side config under individual config options as the Server-side label.
You must still call
newrelic.NewApplication()
in your application process following the steps described in the in-process configuration. Configuration options set server-side will overwrite those set locally. Since not all configuration options are available server side, you may want to still update yournewrelic.Config
struct.If server-side config is enabled, the agent ignores any value in the
newrelic.Config
struct that could be set in the UI. Even if the UI value is empty, the agent treats this as an empty value and does not use thenewrelic.Config
value. - In process
newrelic.Config
struct -
You configure your Go agent from the local in process
newrelic.Config
struct. This struct is can be accessed when callingnewrelic.NewApplication()
.- Add the following in the
main
function or in aninit
block:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), )
- Update values on the
newrelic.Config
struct to configure your application usingnewrelic.ConfigOption
s. These are functions that accept a pointer to thenewrelic.Config
struct. Add additionalnewrelic.ConfigOption
s to further configure your application. For example, you can use one of the predefined options to do common configurations:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), // add debug level logging to stdout newrelic.ConfigDebugLogger(os.Stdout), )
- Or, you can create your own
newrelic.ConfigOption
to do more complex configurations:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), newrelic.ConfigDebugLogger(os.Stdout), func(config *newrelic.Config) { // add more specific configuration of the agent within a custom ConfigOption config.HighSecurity = true config.CrossApplicationTracer.Enabled = false }, )
- Add the following in the
Change configuration settings
To make Go agent configuration changes, set the values in the newrelic.Config
struct from within a custom newrelic.ConfigOption
. For example, to turn New Relic monitoring off temporarily for testing purposes, change the Enabled
value to false
:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.Enabled = false }, )
In this and the following examples, config
represents your New Relic config struct, although you may have given it a different variable name when you installed the Go agent and initiated the configuration in your app.
General configuration settings
- License (REQUIRED)
-
Type String Default (none)
Set in newrelic.Config
structSpecifies your New Relic license key, used to associate your app's metrics with your New Relic account. The license and the app name are both set as part of the New Relic installation process.
- AppName (REQUIRED)
-
Type String Default (none)
Set in newrelic.Config
structThis is the application name used to aggregate data in the New Relic UI. You set both the license and the app name as part of the New Relic installation process.
To report data to multiple apps at the same time, specify a list of names separated with a semicolon. Do not put a space before the semicolon itself. For example:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("YOUR_APP_NAME;APP_GROUP_1;ALL_APPS"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), )
- Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent sends data from your app to the New Relic collector.To turn off New Relic monitoring, set this to
false
.For example:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.Enabled = false }, )
This can be useful for installing New Relic in a development environment or for troubleshooting purposes. When
Enabled
is set tofalse
:- The New Relic Go agent will not communicate with the New Relic collector.
- The agent will not spawn goroutines.
- The license key is not required during installation.
- Labels
-
Type map[string]string Default (none) Set in newrelic.Config
structThis is used to attach labels to your app. You can use labels to filter and sort your apps in the New Relic UI. You can also set labels in the UI.
- Creating four label pairs
-
Here's an example of setting four labels:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.Labels := map[string]string{ "Env": "Dev", "Label2": "label2", "Label3": "label3", "Label4": "label4", } }, )
- Logger
-
Type Interface Default (none) Set in newrelic.Config
structYou can use the
Logger
interface to write Go log files to a specific location or logging system. - HighSecurity
-
Type Boolean Default false
Set in newrelic.Config
structThis feature requires Enterprise tier.
High security mode enforces certain security settings and prevents them from being overridden, so that the agent sends no sensitive data. High security mode does the following:
- Turns SSL on
- Turns off reporting of error message strings
- Turns off reporting of custom events
This setting must match the corresponding account setting in the UI. For example:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.HighSecurity = true }, )
The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to APM and our REST API.
- UseTLS (DEPRECATED)
-
Type Boolean Default true
Set in newrelic.Config
structThis option was removed in agent version 2.0.
Controls whether HTTPS or HTTP is used to send data to New Relic. The agent communicates with New Relic via HTTPS by default (which uses TLS protocol), and New Relic requires HTTPS for all traffic to APM and the New Relic REST API.
- HostDisplayName
-
Type String Default (none) Set in newrelic.Config
structThis sets the hostname displayed in the APM UI. This is an optional configuration.
- Transport
-
Type Default (none) Set in newrelic.Config
structThis customizes http.Client communication with New Relic collectors. This can be used to configure a proxy.
- RuntimeSampler.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent captures runtime statistics.
Custom events configuration
You can create custom events and make them available for querying and analysis.
- CustomInsightsEvents.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent sends custom events to New Relic. This setting is overridden byHighSecurity
, which disables custom Insights events.To disable custom events, place the following in your Go app after the New Relic config is initiated:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.CustomInsightsEvents.Enabled = false }, )
Transaction events configuration
Transaction events are used in collecting events corresponding to web requests and background tasks. Event data allows the New Relic UI to show additional information such as histograms and percentiles.
- TransactionEvents.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent collects transaction events. - TransactionEvents.Attributes
-
Type Struct Default Enabled, no exclusions Set in newrelic.Config
structTransactionEvents.Attributes
is a struct with three fields:Enabled bool Include []string Exclude []string
Use
TransactionEvents.Attributes.Enabled
to turn attribute collection on or off for transaction events. UseInclude
andExclude
to include or exclude specific attributes.An example of excluding an attribute slice named
allAgentAttributeNames
from transaction events:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.TransactionEvents.Attributes.Exclude = allAgentAttributeNames }, )
- TransactionEvents.MaxSamplesStored
-
Type Integer Default 10000
Set in newrelic.Config
structDefines the maximum number of transaction events per minute to be sent to New Relic, up to the default maximum of 10,000 transaction events.
Error collector configuration
The following settings are used to configure the error collector:
For an overview of error configuration in New Relic, see Manage errors in APM.
- ErrorCollector.Enabled
-
Type Boolean Default true
Set in newrelic.Config
struct, Server-side configServer-side label Error Collection on/off
When
false
, the agent collects no errors or error traces. - ErrorCollector.CaptureEvents
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent collects error analytic events. - ErrorCollector.IgnoreStatusCodes
-
Type Integer Default Error codes 399 and below, and 404, are ignored. Set in newrelic.Config
struct, Server-side configServer-side label Error Collection: Ignore from error collection
This controls which HTTP response codes are ignored as errors.
Response codes that are greater than or equal to 100 and strictly less than 400 are ignored by default and never have to be specified when calling this function. Response codes 0, 5, and 404 are included on the list by default, but must be specified when adding to the ignore list.
This function's default form is:
config.ErrorCollector.IgnoreStatusCodes = []int{ 0, // gRPC OK 5, // gRPC NOT_FOUND http.StatusNotFound, // 404 }
You can also add response codes as HTTPs, as
http.StatusNotFound
above.If used, server-side configuration will override any values set on the
newrelic.Config
struct. Therefore to ignore 404 when server-side configuration is enabled, you must include 404 in the configuration set in the UI.- Example of ignoring error code
-
To add HTTP response code 418 to the default ignore list, which includes 0, 5, and 404:
app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.ErrorCollector.IgnoreStatusCodes = []int{0, 5, 404, 418} }, )
- ErrorCollector.Attributes
-
Type Struct Default Enabled, no exclusions Set in newrelic.Config
structErrorCollector.Attributes
is a struct with three fields:Enabled bool Include []string Exclude []string
Use
ErrorCollector.Attributes.Enabled
to turn attribute collection on or off for errors. UseInclude
andExclude
to include or exclude specific attributes.An example of excluding an attribute slice named
allAgentAttributeNames
from errors:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.ErrorCollector.Attributes.Exclude = allAgentAttributeNames }, )
Transaction tracer configuration
Here are settings for changing transaction tracer configuration. For more information about transaction traces, see Transaction traces.
- TransactionTracer.Enabled
-
Type Boolean Default true
Set in newrelic.Config
struct, Server-side configServer-side label Transaction Tracing on/off
When
true
, the agent collects transaction traces (detailed information about slow transactions). - TransactionTracer.Threshold.IsApdexFailing
-
Type Boolean Default true
Set in newrelic.Config
struct, Server-side configServer-side label Transaction Tracing: Threshold
Controls whether the transaction trace threshold is based on Apdex.
- If
true
, then the trace threshold is four times the Apdex threshold. - If
false
, the agent usesThreshold.Duration
as the transaction trace threshold.
- If
- TransactionTracer.Threshold.Duration
-
Type time.Millisecond Default 500
Set in newrelic.Config
struct, Server-side configServer-side label Transaction Tracing: Threshold
If
Threshold.IsApdexFailing
is set tofalse
, the agent uses this duration as the transaction trace threshold. - TransactionTracer.Segments.Threshold
-
Type time.Millisecond Default 2
Set in newrelic.Config
structThis is the threshold at which segments will be added to the trace.
- TransactionTracer.Segments.Attributes
-
Available for Go agent version 2.6.0 or higher.
Type Struct Default Enabled, no exclusions Set in newrelic.Config
structTransactionTracer.Segments.Attributes
is a struct with three fields:Enabled bool Include []string Exclude []string
Use
TransactionTracer.Segments.Attributes.Enabled
to turn attribute collection on or off for transaction trace segments. UseInclude
andExclude
to include or exclude specific attributes.An example of excluding an attribute slice named
allSegmentAttributeNames
from traces:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.TransactionTracer.Segments.Attributes.Exclude = allSegmentAttributeNames }, )
- TransactionTracer.Segments.StackTraceThreshold
-
Type time.Millisecond Default 500
Set in newrelic.Config
struct, Server-side configServer-side label Transaction Tracing: Stack trace threshold
This is the threshold at which segments will be given a stack trace in the transaction trace.
Lowering this setting may drastically increase agent overhead.
- TransactionTracer.Attributes
-
Type Struct Default Enabled, no exclusions Set in newrelic.Config
structTransactionTracer.Attributes
is a struct with three fields:Enabled bool Include []string Exclude []string
Use
TransactionTracer.Attributes.Enabled
to turn attribute collection on or off for transaction traces. UseInclude
andExclude
to include or exclude specific attributes.An example of excluding an attribute slice named
allAgentAttributeNames
from traces:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.TransactionTracer.Attributes.Exclude = allAgentAttributeNames }, )
Datastore tracer configuration
Here are datastore settings, including slow query enabling and settings.
- DatastoreTracer.InstanceReporting.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structThis enables collection of datastore instance metrics (such as the host and port) for some database drivers. These are reported on transaction traces and as part of slow query data.
- DatastoreTracer.NameReporting.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structUse this to enable collection of the database name on slow query traces and transaction traces. The default value of attribute enabled is
true
. - DatastoreTracer.QueryParameters.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent collects datastore call query parameters. - DatastoreTracer.SlowQuery.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structControls whether slow queries are captured.
- DatastoreTracer.SlowQuery.Threshold
-
Type time.Millisecond Default 10
Set in newrelic.Config
structThe agent captures slow query data for queries slower than this.
Cross application tracing configuration
Here are settings for changing the cross application tracing feature.
- CrossApplicationTracer.Enabled
-
Type Boolean Default true
Set in newrelic.Config
struct, Server-side configServer-side label Cross-application tracing on/off
When
true
, the agent will add cross application tracing headers in outbound requests, and scan incoming requests for cross application tracing headers.Distributed tracing and cross application tracing cannot be used simultaneously. The default configuration for the Go agent disables distributed tracing and enables cross application tracing.
Distributed tracing configuration
Enabling distributed tracing requires Go agent version 2.1.0 or higher, and it disables cross application tracing. It also has effects on other features. Before enabling, read the transition guide.
Distributed tracing lets you see the path that a request takes as it travels through a distributed system.
When distributed tracing is enabled, you can collect span events.
- DistributedTracer.Enabled
-
Type Boolean Default false
Set in newrelic.Config
structWhen
true
, the agent will add distributed tracing headers in outbound requests, and scan incoming requests for distributed tracing headers.Enabling distributed tracing disables cross application tracing.
- DistributedTracer.ExcludeNewRelicHeader
-
Type Boolean Default false
Set in newrelic.Config
structSet this to
true
to exclude the New Relic header that is attached to outbound requests, and instead only rely on W3C Trace Context Headers for distributed tracing. If this isfalse
then both types of headers are used.
Span events configuration
Span events are reported for distributed tracing. Distributed tracing must be enabled to report span events. These settings control the collection of span events:
- SpanEvents.Enabled
-
Type Boolean Default true
Set in newrelic.Config
structWhen
true
, the agent will collect span events. - SpanEvents.Attributes
-
Available for Go agent version 2.6.0 or higher.
Type Struct Default Enabled, no exclusions Set in newrelic.Config
structSpanEvents.Attributes
is a struct with three fields:Enabled bool Include []string Exclude []string
Use
SpanEvents.Attributes.Enabled
to enable or disable attribute collection for span events. UseInclude
andExclude
to include or exclude specific attributes.An example of excluding an attribute slice named
allSpanAttributeNames
from traces:app, err := newrelic.NewApplication( newrelic.ConfigAppName("Your Application Name"), newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"), func(config *newrelic.Config) { config.TransactionTracer.Segments.Attributes.Exclude = allSpanAttributeNames }, )
Infinite Tracing configuration
To enable Infinite Tracing, enable distributed tracing (set config.DistributedTracer.Enabled = true
on the newrelic.Config
struct) and add the additional settings below. For an example, see Language agents: Configure distributed tracing.
- InfiniteTracing.TraceObserver.Host
-
Type string Default (none) Set in newrelic.Config
struct -
For help getting a valid Infinite Tracing trace observer host entry, see Find or create a trace observer endpoint.