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

Python agent configuration

Our Python agent lets you change the default agent behavior agent using configuration options.

The only required Python agent configuration setting is the . The license key identifies the account where the agent reports application data. Depending on how you are hosting your application, the license key can be provided via a configuration file or an environment variable.

Configuration methods and precedence

The primary way to configure the Python agent is via the configuration file, which is generated as part of the standard install process. It is also possible to set a limited number of configuration options using server-side configuration in the UI or by using environment variables. You can also specify some settings on a per-request basis by passing settings with the WSGI request environ dictionary.

The Python agent follows this order of precedence for configuration:

With the Python agent, per-request options override server-side config. If enabled, server-side config overrides all corresponding values in the agent config file, even if the server-side values are left blank. The agent config file overrides environment variables. Environment variables override the agent defaults.

Here are detailed descriptions of each configuration method:

Multiple environment configuration

The agent reads its primary configuration from an agent config section called newrelic. You can provide overrides for specific deployment environments (for example, Development, Staging, Production) in additional sections. Preface these sections with [newrelic:environment], where environment is replaced with the name of your environment.

To specify that the agent should use an environment-based configuration, use one of these methods:

  • When you call newrelic.agent.initialize(), provide the environment name as the second argument.


  • Set the NEW_RELIC_ENVIRONMENT environment variable to the environment name.

If no environment is specified, the agent will use the default settings as specified in the newrelic agent config section.

The basic structure of the configuration file is:

... default settings
... override settings
... override settings
... override settings

General configuration settings

These settings are available in the agent configuration file.


Attributes are key-value pairs that provide information for transaction traces, traced errors, , and transaction events. In addition to configuring attributes for all four destinations with the general attribute settings below, they can also be configured on a per-destination basis.

For more information, see Python agent attributes, Enabling and disabling attributes, and Attribute examples.

AI monitoring

This section includes Python agent configurations for setting up AI monitoring.


You must enable distributed tracing to capture AI data. It's turned on by default in Python agent versions and higher.

Transaction tracer configuration


Do not use brackets [suffix] at the end of your transaction name. The agent automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

For more information about transaction traces, see Transaction traces.

Transaction segment configuration

Here are Transaction segment settings available via the agent configuration file.

Error collector configuration

Here are error collector settings available via the agent configuration file.


For an overview of error configuration in APM, see Manage errors in APM.

Browser monitoring settings

Here are browser monitoring settings available via the agent configuration file.

Transaction events settings

Here are Transaction events settings available via the agent configuration file.


These configuration settings used to be called analytic_events. If your configuration file still uses analytic_events, update your agent to use transaction_events.

Custom events settings

Here are custom events settings available via the agent configuration file.

Datastore tracer settings

These datastore tracer settings are available via the agent configuration file:

Distributed tracing settings

Distributed tracing lets you see the path that a request takes as it travels through a distributed system. Starting in Python agent version or higher, distributed tracing is enabled by default.


Enabling distributed tracing disables cross application tracing and has other effects on APM features. If migrating from cross application tracing, read the transition guide.

For more information, see Distributed tracing for your Python services.

Settings include:

Span event configuration

Span events are collected for distributed tracing. Distributed tracing must be enabled to report span events. Configuration options include:

Event harvest configuration

Event harvest settings limit the amount of event type data sent to New Relic. When you use these settings, consider these important points:

  • Event harvest settings affect the limits for a single instance of the agent, and not across the entire application. See the usage example below for how to set limits across an entire application.
  • Real time streaming sends data every five seconds (12 times per minute), but the event harvest settings still affect the rate in events per minute. Enabling or disabling real time streaming does not require changing these settings.
  • With real time streaming (enabled by default), New Relic will display the event harvest limits for entities in five second intervals. This means, for example, when you set a limit value of 1200 in the config file, you'll see it as 100 in New Relic.

Usage example

Let's say an application is deployed across 10 hosts, each running four processes per host. To limit the number of span events to 10,000 events per minute for the entire application, divide that number by 10 hosts. Then divide again by four processes per host.

10000 / (10 * 4) = 250

Based on that calculation, the final setting is:

event_harvest_config.harvest_limits.span_event_data = 250


Because of the way New Relic harvests data (12 times per minute), if the event data count is less than 12, it will show up as 0 in New Relic.

Event harvest configuration settings include:

Event loop visibility settings

Event loop visibility surfaces information about transactions that block the event loop. The agent will generate information about transactions that have waited a significant amount of time to acquire control of the event loop. Settings include:

Runtime metrics for physical memory

These runtime metrics settings are available via the agent configuration file:

Garbage collection runtime metrics settings

These garbage collection runtime metrics settings are available via the agent configuration file:

Code-level metrics settings

The following settings are available for configuration of code-level metrics in the agent.

Errors inbox configuration

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

  • NEW_RELIC_METADATA_SERVICE_VERSION will create 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 will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
  • NEW_RELIC_METADATA_COMMIT will create 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.

Application logging settings

The following settings are available for configuration of application logging in the agent.

For some tips on configuring logs for the Python agent, see Configure Python logs in context.

Instrumentation settings

These instrumentation package specific settings are available via the agent configuration file:

Machine Learning settings

The following settings are available for configuration of machine learning data in the agent.

Other configuration settings

Here are assorted other settings available via the agent configuration file.


Built-in instrumentation

The Python agent instruments a range of Python packages/modules. This instrumentation only occurs when the target Python package/module is imported by an application.

To disable default instrumentation, provide a special import-hook section corresponding to the name of the module that triggered instrumentation. Then set the enabled setting to false to disable instrumentation of that module.

Copyright © 2024 New Relic Inc.

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