Go agent code-level metrics configuration

Code-level metrics allow developers using the New Relic CodeStream extension to see data displayed contextually in their IDE, alongside individual methods in the code. This allows developers to be more proactive about addressing performance issues as they write and review code.

When you enable code-level metrics, the Go agent will attach attributes to trace data. These attributes show the location in your application source code responsible for the actions instrumented by those traces. The data you can see includes:

Source file name
Source file line number
Function name
Namespace

Take a look at the Go agent configuration settings to help you control the collection of code-level metrics. After you complete the configuration, if you need help finding the data, see View your metrics. If you want more control over how the metrics are collected, see Go agent code-level metrics instrumentation.

Important

Code-level metrics are available for Go agent version 3.18.0 or higher, and enabled by default for version 3.24.0 and higher. To enable it, you must add newrelic.ConfigCodeLevelMetricsEnabled(true) to your application's configuration as explained below.

Configuration methods

When calling newrelic.NewApplication to configure the Go agent in your application, you can enable code-level metrics by including the newrelic.ConfigCodeLevelMetricsEnabled option, like so:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
)

With that simple step, the Go agent will add the source code context information in the following agent attributes on transactions:

Name	Description
`code.function`	The name of the function which started the transaction. Note that this may be automatically generated by the Go compiler in some cases.
`code.namespace`	The package/namespace where the function is located. The combination of `code.namespace` and `code.function`, joined with a delimiter such as a dot (`.`), is expected to uniquely identify the function.
`code.filepath`	The pathname of the source file containing the function being reported. Normally this is the full, absolute pathname; see below for a configuration option which allows you to change this to a relative path.
`code.lineno`	The line number within `code.filepath` where the transaction was started. See the instrumentation guide for ways to control this.

There are additional configuration options you may wish to use to further refine the collection of code-level metrics in your application.

Setting one of the following tags will help you identify which versions of your software are producing the errors.

NEW_RELIC_METADATA_SERVICE_VERSION creates tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always.
NEW_RELIC_METADATA_RELEASE_TAG creates tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
NEW_RELIC_METADATA_COMMIT creates tags.commit on event data containing the commit SHA. The entire SHA can be used or just the first seven characters (e.g., 734713b).
An upcoming release of errors inbox will automatically track which versions of your software are producing errors. Any version data will also be displayed in CodeStream.

By default, with code-level metrics enabled, the agent will ignore functions in the call stack which it believes to be internal to the agent itself, to ensure that the function reported is the one intended, even though functions inside the agent will have been called to get into the code-level metrics instrumentation code. By default, it does this by ignoring any functions whose package name begins with github.com/newrelic/go-agent/. You can change this to any arbitrary list of names by setting your own IgnoredPrefixes value.

To accomplish this, do one of the following:

If configuring via the NewApplication function, add a ConfigCodeLevelMetricsIgnoredPrefixes option, passing any number of prefix strings as separate string arguments:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigCodeLevelMetricsIgnoredPrefixes("github.com/some/other/name/"),
)

If configuring via environment variables, set NEW_RELIC_CODE_LEVEL_METRICS_IGNORED_PREFIXES to the desired prefix (or a comma-separated list of prefixes):

NEW_RELIC_CODE_LEVEL_METRICS_IGNORED_PREFIXES="github.com/some/other/name/"

Don't forget to also include the newrelic.ConfigFromEnvironment() option when setting up the application:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigFromEnvironment(),
)

It is also possible to directly set the CodeLevelMetrics.IgnoredPrefixes member of the Config struct (which is a []string value), but we recommend using one of the above-mentioned methods instead of directly manipulating the Config structure.

Important

In Go Agent versions prior to 3.20.0, this option was named with in the singular form rather than plural (i.e., ConfigCodeLevelMetricsIgnoredPrefix). These names are deprecated and the ones documented here should be used. The older names are also still supported for backward compatibility.

If, for reasons such as confidentiality, you choose to ignore some modules via ConfigCodeLevelMetricsIgnoredPrefixes option, you may also wish to redact the list of such prefixes from the agent's reported configuration data as well.

This is accomplished by setting the ConfigCodeLevelMetricsRedactIgnoredPrefixes option. If given a true value, your list of ignored prefixes will not be shown in the configuration data that are reported by the agent. Otherwise, they will be reported.

Do one of the following:

If configuring via the NewApplication function, add a ConfigCodeLevelMetricsRedactIgnoredPrefixes option:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigCodeLevelMetricsRedactIgnoredPrefixes(true),
)

If configuring via environment variables, set NEW_RELIC_CODE_LEVEL_METRICS_REDACT_IGNORED_PREFIXES:

NEW_RELIC_CODE_LEVEL_METRICS_REDACT_IGNORED_PREFIXES=true

Don't forget to also include the newrelic.ConfigFromEnvironment option when setting up the application:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigFromEnvironment(),
)

Important

This redaction option is available in Go Agent versions 3.20.0 and later.

By default, with code-level metrics enabled, the agent will report the full pathname of each source file. However, this may not be desired. For example, you may wish to only report application paths relative to the root of the project source tree, allowing data to be correlated between instances regardless of where they are installed in the filesystem.

To accomplish this, specify a string that indicates the start of your local project source path. If that prefix is found in a source file pathname, everything that appears before it will be removed. For example, if the path prefix string is set to myproject/src then /usr/local/projects/myproject/src/widget/main.go would be reported in the code-level metrics as myproject/src/widget/main.go.

If you have multiple path prefixes you wish to use, simply list all of their names as separate parameters.

If PathPrefixes is empty, or a source file path doesn't contain any of your prefix strings at all, the full pathname will be reported.

Do one of the following:

If configuring via the NewApplication function, add a ConfigCodeLevelMetricsPathPrefixes option:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigCodeLevelMetricsPathPrefixes("myprojects/src/", "otherproject/src/"),
)

If configuring via environment variables, set NEW_RELIC_CODE_LEVEL_METRICS_PATH_PREFIXES to the desired prefix(es):

NEW_RELIC_CODE_LEVEL_METRICS_PATH_PREFIXES="myprojects/src/,otherproject/src/"

Don't forget to also include the newrelic.ConfigFromEnvironment option when setting up the application:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigFromEnvironment(),
)

Important

In Go Agent versions prior to 3.20.0, this option was named with in the singular form rather than plural (i.e., ConfigCodeLevelMetricsPathPrefix). These names are deprecated and the ones documented here should be used. The older names are also still supported for backward compatibility.

If, for reasons such as confidentiality, you choose to shorten reported source pathnames via the ConfigCodeLevelMetricsPathPrefixes option, you may also wish to redact the list of path prefixes from the agent's reported configuration data as well.

This is accomplished by setting the ConfigCodeLevelMetricsRedactPathPrefixes option. If given a true value, your list of path prefixes will not be shown in the configuration data that are reported by the agent. Otherwise, they will be reported.

Do one of the following:

If configuring via the NewApplication function, add a ConfigCodeLevelMetricsRedactPathPrefixes option:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigCodeLevelMetricsPathPrefixes("myprojects/src/", "otherproject/src/"),
   newrelic.ConfigCodeLevelMetricsRedactPathPrefixes(true),
)

If configuring via environment variables, set NEW_RELIC_CODE_LEVEL_METRICS_REDACT_PATH_PREFIXES:

NEW_RELIC_CODE_LEVEL_METRICS_REDACT_PATH_PREFIXES=true

Don't forget to also include the newrelic.ConfigFromEnvironment option when setting up the application:

app, err := newrelic.NewApplication(
   newrelic.ConfigAppName("Your Application Name"),
   newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY"),
   newrelic.ConfigCodeLevelMetricsEnabled(true),
   newrelic.ConfigFromEnvironment(),
)

Important

This redaction option is available in Go Agent versions 3.20.0 and later.

View your metrics

Once you've configured code-level metrics, you can see your data in the New Relic UI. Here's one way you can see traces for a particular service:

Go to one.newrelic.com > All capabilities > APM & services.
Click your entity (service).
In the left pane's Monitor section, click Transactions.
Under Transaction traces, click on an individual trace.
Look under Agent attributes for the four attributes beginning with code..

Go agent code-level metrics configuration

Important

Configuration methods

Errors inbox configuration

Identify instrumented packages

Important

Redact ignored module prefixes

Important

Truncate source path prefix

Important

Redact source path prefixes

Important

View your metrics

Go agent code-level metrics configuration

Important

Configuration methods .css-21sua1{background:none;border:none;width:0;padding:0;}

Identify instrumented packages

Redact ignored module prefixes

Truncate source path prefix

Redact source path prefixes

View your metrics

Configuration methods