Go agent configuration

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 Insights events.

Configuration methods and precedence

The primary way to configure the Go agent is by using the newrelic.Config struct, 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.

If server-side configuration is enabled with the Go agent, it 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)

Owner or Admins

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 create the newrelic.Config struct in your application process following the steps described in the in-process configuration. Configuration options set server-side will overwrite those set locally.

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 the newrelic.Config value.

In process newrelic.Config struct

Typically you configure your Go agent from the local in process newrelic.Config struct.

1. Add the following in the main function or in an init block:

   config := newrelic.NewConfig("YOUR_APP_NAME", "_YOUR_NEW_RELIC_LICENSE_KEY_")
   

2. Update values on the newrelic.Config struct to configure your application. For example, to disable custom events:

   config.CustomInsightsEvents.Enabled = false

3. Use this newrelic.Config to create a newrelic.Application:

   app, err := newrelic.NewApplication(config)

Change configuration settings

To make Go agent configuration changes, set the values in the newrelic.Config struct, which is returned by the newrelic.NewConfig function. For example, to turn New Relic monitoring off temporarily for testing purposes, change the Enabled value to false:

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 struct

Specifies 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 struct

This 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:

config := newrelic.NewConfig("YOUR_APP_NAME;APP_GROUP_1;ALL_APPS", "YOUR_NEW_RELIC_LICENSE_KEY")

Enabled

Type	Boolean
Default	true
Set in	newrelic.Config struct

When 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:

config.Enabled = false

This can be useful for installing New Relic in a development environment or for troubleshooting purposes. When Enabled is set to false:

• 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 struct

This 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:

config.Labels := map[string]string{
    "Env": "Dev",
    "Label2": "label2",
    "Label3": "label3",
    "Label4": "label4",
}

Logger

Type	Interface
Default	(none)
Set in	newrelic.Config struct

You 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 struct

High security mode enforces certain security settings and prevents them from being overridden, so that the agent sends no sensitive data to New Relic. High security mode does the following:

• Turns SSL on
• Turns off collection of error message strings
• Turns off collection of custom Insights events

This setting must match the corresponding account setting in the New Relic UI. For example:

config.HighSecurity = true

The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to New Relic APM and the New Relic REST API.

UseTLS (DEPRECATED)

Type	Boolean
Default	true
Set in	newrelic.Config struct

This 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 New Relic APM and the New Relic REST API.

HostDisplayName

Type	String
Default	(none)
Set in	newrelic.Config struct

This sets the hostname displayed in the APM UI. This is an optional configuration.

Transport

Type	http.RoundTripper
Default	(none)
Set in	newrelic.Config struct

This customizes http.Client communication with New Relic collectors. This can be used to configure a proxy.

RuntimeSampler

Type	Boolean
Default	true
Set in	newrelic.Config struct

When true, the agent captures runtime statistics.

Custom Insights events configuration

You can create custom events and make them available for querying and analysis in New Relic Insights.

CustomInsightsEvents.Enabled

Type	Boolean
Default	true
Set in	newrelic.Config struct

When true, the agent sends custom events to New Relic Insights. This setting is overridden by HighSecurity, which disables custom Insights events.

To disable custom Insights events, place the following in your Go app after the New Relic config is initiated:

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 struct

When true, the agent collects transaction events.

TransactionEvents.Attributes

Type	Struct
Default	Enabled, no exclusions
Set in	newrelic.Config struct

TransactionEvents.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. Use Include and Exclude to include or exclude specific attributes.

An example of excluding an attribute slice named allAgentAttributeNames from transaction events:

cfg.TransactionEvents.Attributes.Exclude = allAgentAttributeNames

Error collector configuration

The following settings are used to configure the error collector:

ErrorCollector.Enabled

Type	Boolean
Default	true
Set in	newrelic.Config struct, Server-side config
Server-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 struct

When 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 config
Server-side label	Error Collection: Ignore from error collection

This controls which HTTP response codes are ignored as errors.

Response codes 399 and below are ignored by default and never have to be specified when calling this function. Response code 404 is 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{
        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 404:

config.ErrorCollector.IgnoreStatusCodes = [404,418]

ErrorCollector.Attributes

Type	Struct
Default	Enabled, no exclusions
Set in	newrelic.Config struct

ErrorCollector.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. Use Include and Exclude to include or exclude specific attributes.

An example of excluding an attribute slice named allAgentAttributeNames from errors:

cfg.ErrorCollector.Attributes.Exclude = allAgentAttributeNames

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 config
Server-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

This setting enables/disables distributed tracing:

DistributedTracer.Enabled

Type	Boolean
Default	false
Set in	newrelic.Config struct

When true, the agent will add distributed tracing headers in outbound requests, and scan incoming requests for distributed tracing headers.

Distributed tracing and cross application tracing cannot be used simultaneously; the required configuration for enabling distributed tracing is:

config.CrossApplicationTracer.Enabled = false
config.DistributedTracer.Enabled = true

Span events configuration

These settings control the collection of span events:

SpanEvents.Enabled

Type	Boolean
Default	true
Set in	newrelic.Config struct

When true, the agent will add 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 struct

SpanEvents.Attributes is a struct with three fields:

Enabled bool
Include []string
Exclude []string

Use SpanEvents.Attributes.Enabled to turn attribute collection on or off for span events. Use Include and Exclude to include or exclude specific attributes.

An example of excluding an attribute slice named allSpanAttributeNames from traces:

cfg.TransactionTracer.Segments.Attributes.Exclude = allSpanAttributeNames

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 config
Server-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 config
Server-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 uses Threshold.Duration as the transaction trace threshold.

TransactionTracer.Threshold.Duration

Type	time.Millisecond
Default	500
Set in	newrelic.Config struct, Server-side config
Server-side label	Transaction Tracing: Threshold

If Threshold.IsApdexFailing is set to false, the agent uses this duration as the transaction trace threshold.

TransactionTracer.SegmentThreshold

Type	time.Millisecond
Default	2
Set in	newrelic.Config struct

This 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 struct

TransactionTracer.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. Use Include and Exclude to include or exclude specific attributes.

An example of excluding an attribute slice named allSegmentAttributeNames from traces:

cfg.TransactionTracer.Segments.Attributes.Exclude = allSegmentAttributeNames

TransactionTracer.StackTraceThreshold

Type	time.Millisecond
Default	500
Set in	newrelic.Config struct, Server-side config
Server-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 struct

TransactionTracer.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. Use Include and Exclude to include or exclude specific attributes.

An example of excluding an attribute slice named allAgentAttributeNames from traces:

cfg.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 struct

This 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 struct

Use 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 struct

When true, the agent collects datastore call query parameters.

DatastoreTracer.SlowQuery.Enabled

Type	Boolean
Default	true
Set in	newrelic.Config struct

Controls whether slow queries are captured.

DatastoreTracer.SlowQuery.Threshold

Type	time.Millisecond
Default	10
Set in	newrelic.Config struct

The agent captures slow query data for queries slower than this.

For more help