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.
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:
Typically you configure your Python agent from a local configuration file on the agent's host system. Supply the path to the config file at startup using one of these methods:
Set the NEW_RELIC_CONFIG_FILE environment variable. If you use the newrelic-admin wrapper script, you must use the environment variable because the wrapper script calls the agent automatically.
The agent supports two types of configuration files, agents v10.2.0 and older must use the .ini syntax while agent versions v10.3.0 and above running on Python versions 3.11 and above support .toml files as well.
The configuration file uses a structure similar to Microsoft Windows .ini files. For more information, see the Python ConfigParser module's file format documentation.
The basic structure should look like the following:
[newrelic]
license_key=<license key>
app_name=Python Application
Tip
Starting with Python 3.11 the newer .toml syntax for configuration was added to the standard library. Agent version 10.3.0 added support for using this newer format.
The configuration file uses Tom's Obvious Minimal Language .toml files. For more information, see the official file format documentation.
To use the .toml syntax, the configuration file's name must end with .toml to indicate the syntax type. The standard pyproject.toml may be used alongside configuration for other libraries, or you may use a more specific file like newrelic.toml.
The basic structure should look like the following:
[tool.newrelic]
license_key=<license key>
app_name=Python Application
Tip
A sample configuration file is included with the Python agent as newrelic/newrelic.ini. You can also generate one from the newrelic-admin script using the generate-config command, or download a copy from our download repo.
Server-side configuration 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.
Important
If server-side config is enabled, the agent ignores any value in the config file that could be set in the UI. Even if the UI value is empty, the agent treats this as an empty string and does not use the agent config file.
Environment variables allow you to override the defaults for certain core settings. If the equivalent setting is explicitly listed in the agent config file, the config file settings take precedence over the environment variable. Where available, environment variables are documented below under individual config options as the Environ variable.
For simple configurations, you can use the environment variables in conjunction with server-side configuration and avoid the agent config file altogether. This is the default setup with Heroku, where installing the New Relic add-on automatically populates the necessary environment variables.
For certain WSGI servers, you can override the app name and capture attributes settings on a per-request basis. This is possible with WSGI servers where you can define additional key/value pairs that are passed into the per-request WSGI environ dictionary.
Set these values with the strings on, off, true, false, 1 and 0. If set from a configuration mechanism implemented using Python code, Python objects evaluating to True or False will also be accepted.
In the Apache/mod_wsgi server, you can use the SetEnv directive to override config settings (optionally inside a Location or Directory block). For example, you could override the app name for a complete virtual host, or for a subset of URLs handled by the WSGI application for that virtual host.
In addition to being able to override certain agent configuration settings, you can set other per-request configuration settings with their WSGI environment key:
If set to true, this web transaction will instead be reported as a non-web transaction.
If set to true, this web transaction will not be reported.
If set to true, no Apdex metric will be generated for this web transaction.
If set to true, this web transaction cannot be recorded in a transaction trace.
If set to true, this disables automatic insertion of the JavaScript header/footer for page load timing (sometimes referred to as real user monitoring or RUM). Only applicable if auto-insertion is available for your web framework.
Important
Using a WSGI middleware to set these values will not work where the Python agent's own WSGI application wrapper was applied at an outer scope. In these cases you must make calls to the agent API to achieve the same outcome.
Multiple environment configuration
The agent reads its primary configuration from an agent config section called [newrelic] for ini files, or [tool.newrelic] for .toml files. You can provide overrides for specific deployment environments (for example, Development, Staging, Production) in additional sections. Preface these sections with [newrelic:environment] for .ini files, or [tool.newrelic.env.environment] for .toml files (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:
The application name used to aggregate data in the New Relic UI. 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, which causes the Python config parser to interpret the name as an embedded comment.
When true, the agent will instrument your web app, but will not send any actual data. In this offline mode, you will not be billed for an active agent.
Use developer mode to test new versions of the agent, or test the agent against third-party packages in a developer environment. Offline mode is not a way of running the APM locally, because the metrics the agent collects are not reported anywhere.
Sets the name of a log file, which is useful for debugging issues with the agent. This is not set by default, since the agent does not know your web app process's parent user or what directories that process has permission to write to. For detailed information, see Python agent logging.
Whatever you set this to, ensure the permissions for the containing directory and the file itself are correct, and that the user that your web application runs as can write to the file.
Tip
Use an absolute path unless you are sure what the working directory of your application will be at startup. If you can't write out a log file, you can also use stderr and output to standard error output. This would normally result in output appearing in your web server log.
Sets the level of detail of log messages, if you've set the log file location. This log_level will not affect the Python logging module log level. Possible values, in increasing order of detail, are critical, error, warning, info, and debug.
To report agent issues, the most useful setting is debug. However, debug generates a lot of information very quickly, so do not keep the agent at this level for longer than it takes to reproduce your problem.
High-security mode enforces certain security settings and prevents them from being overridden, so that no sensitive data is sent to us. Enabling high-security mode means that request parameters are not collected, and you cannot send raw SQL.
To activate high-security mode, set it to true in the local .ini configuration file and activate it from the Account settings page. For more information, see High security.
By default, the Python agent attempts to directly connect to our servers. If there is a firewall between your host and the our collector that requires you to use an HTTP proxy, set proxy_host and proxy_port to the required values for your HTTP proxy. If proxy authentication is implemented by the HTTP proxy, also set proxy_user and proxy_pass.
The proxy_scheme setting dictates what protocol scheme is used to talk to the HTTP proxy. When set to http, the agent uses a SSL tunnel through the HTTP proxy for end-to-end encryption.
Instead of setting the proxy_scheme, proxy_host and proxy_port settings, you can also set the proxy_host setting to a valid URI for the proxy. Include the scheme, host, and port; for example, http://proxy-host:8000. This also works if you set the details of the HTTP proxy with the NEW_RELIC_PROXY_HOST environment variable.
Sets the name of the audit log file. If set, the agent logs details of messages passed back and forth between the monitored process and the collector. This allows you to evaluate the security of the Python agent.
Use an absolute path unless you are sure what your app's working directory will be at startup. Whatever you set this to, ensure the permissions for the containing directory and the file itself are correct. Also ensure your web app's parent user can write to the file.
Caution
Do not use audit logging on an ongoing basis, especially in a production environment. Because the agent does not truncate or rotate the log file, the log file can grow very quickly.
Manual override for the path to your local CA bundle. This CA bundle will be used to validate the SSL certificate presented by our data collection service.
Tip
This configuration option is only available in Python agent versions 4.2.0 and newer.
This is only set in the config file or the environment variable if serverless_mode is set, which is enabled for AWS Lambda. Otherwise, the local apdex_t value is overridden by the value in UI application settings which is then used to set the apdex_f value.
Attributes
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.
If set to false, the agent will omit input and output content (like text strings from prompts and responses) captured in LLM events. This is an optional security setting if you don’t want to record sensitive data sent to and received from your LLMs.
Transaction tracer configuration
Important
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.
Threshold in seconds for when to collect a transaction trace. When the response time of a controller action exceeds this threshold, the agent records a transaction trace. Valid values are any positive float, or apdex_f (four times apdex_t).
When the transaction tracer is enabled, the agent can record SQL statements. The recorder has three modes: off (sends no SQL), raw (sends the SQL statement in its original form), and obfuscated (strips out numeric and string literals).
Most web frameworks (including Django) parameterize SQL queries so they do not actually contain the values used to fill out the query. If you use raw mode with one of these frameworks, the Python agent will only see the SQL prior to insertion of values. The parametrized SQL will look much like obfuscated mode.
Threshold in seconds for when to collect stack traces from SQL calls. When SQL statements exceed this threshold, the agent captures the current stack trace. This is helpful for pinpointing where long SQL calls originate in an application.
Queries in transaction traces that exceed this threshold will report slow query data and any available explain plans. Explain plan collection will not happen if transaction_tracer.explain_enabled is false.
This setting can be used to turn on or off all attributes for transaction traces. If attributes.enabled at the root level is false, no attributes will be sent to transaction traces regardless on how this configuration setting (transaction_tracer.attributes.enabled) is set.
If attributes are enabled for transaction traces, all attribute keys found in this list will be sent to us in transaction traces. For more information, see the agent attribute rules.
For the specified functions or methods, the agent will capture additional function timing instrumentation. Specify these names in the form module:function or module:class.function.
Wildcarding (globbing) for function and class names is possible using patterns supported by the fnmatch module. Module paths are not supported by wildcards. Specify the patterns in the form module:function* or module:class.*.
For example, if you want to add function tracing to all validation functions in the below file:
my-app/common/utils.py
defvalidate_credentials():
…
defvalidate_status():
…
defformat_message():
…
Add the following line to the agent config file to include function tracing to all validation functions in my-app/common/utils.py by using wildcarding.
This setting can be used to turn on or off all attributes for segments of transaction traces. If attributes.enabled at the root level is false, no attributes will be sent to segments of transaction traces regardless on how this configuration setting (transaction_segments.attributes.enabled) is set.
If attributes are enabled for segments of transaction traces, all attribute keys found in this list will be sent in segments of transaction traces. For more information, see the agent attribute rules.
To stop collecting specific errors, set this to a space-separated list of the Python exception type names to ignore. Use the form module:class for the exception name.
Tip
Before version 6.4.0 of the agent, this setting was named error_collector.ignore_errors. If your configuration file still uses ignore_errors, update your agent to use ignore_classes.
Lists HTTP status codes which the agent should ignore rather than record as errors. List additional status codes as integers separated by spaces, and specify ranges with a hyphen - separator between the start and end values. To add one of the default codes to your allow list, preface the code with an exclamation point !.
This setting is only compatible with some web frameworks, as some frameworks do not use exceptions to return HTTP responses.
Tip
This configuration option can only be set in server-side configuration in Python agent versions 6.4.0 and newer.
Prevents specified exception classes from affecting error rate or Apdex score while still reporting the errors to APM. Set this to a space-separated list of the Python exception type names to be expected. Use the form module:class for the exception name.
Tip
This configuration option is only available in Python agent versions 6.4.0 and newer.
Prevents specified HTTP status codes from affecting error rate or Apdex score while still reporting the errors to APM. List status codes as integers separated by spaces and specify ranges with a hyphen - separator between the start and end values. To negate one of the codes in your list, preface the code with an exclamation point !.
This setting is only compatible with some web frameworks, as some frameworks do not use exceptions to return HTTP responses.
Tip
This configuration option is only available in Python agent versions 6.4.0 and newer.
This setting can be used to turn on or off all attributes for traced errors. If attributes.enabled is false at the root level, then no attributes will be sent to traced errors regardless on how this configuration setting (error_collector.attributes.enabled) is set.
If attributes are enabled for traced errors, all attribute keys found in this list will be sent to in traced errors. For more information, see the agent attribute rules.
Specify the HTML Content-Type(s) that our browser monitoring agent should auto-instrument. Add additional entries in a space-separated list.
If you are generating HTML page responses and using the Content-Type of application/xhtml+xml, you can override the allowed content types to list both this content type and the default text/html by using:
The browser monitoring JavaScript snippet prevents the page from validating as application/xhtml+xml, although the page should load and render in end-user browsers.
This setting can be used to turn on or off all attributes for browser monitoring. This is the data which gets sent to page view events. If attributes.enabled is false at the root level, no attributes will be sent up in browser monitoring regardless on how the configuration setting (browser_monitoring.attributes.enabled) is set.
If attributes are enabled for browser_monitoring, all attribute keys found in this list will be sent in page views. For more information, see the agent attribute rules.
All attribute keys found in this list will not be sent in page views. For more information, see the agent attribute rules.
Transaction events settings
Here are Transaction events settings available via the agent configuration file.
Tip
These configuration settings used to be called analytic_events. If your configuration file still uses analytic_events, update your agent to use transaction_events.
This setting can be used to turn on or off all attributes for transaction events. If attributes.enabled is false at the root level, then no attributes will be sent to transaction events regardless on how this configuration setting (transaction_events.attributes.enabled) is set.
If attributes are enabled for transaction events, all attribute keys found in this list will be sent in transaction events. For more information, see the agent attribute rules.
Type
List of Strings
Default
(none)
All attribute keys found in this list will not be sent to in transaction events. Note that excluding attributes from transaction events does not exclude from span events. For more information, see the agent attribute rules.
Custom events settings
Here are custom events settings available via the agent configuration file.
When enabled, the agent collects datastore instance metrics (such as host and port) for some database drivers. These are also reported on slow query traces and transaction traces.
When enabled, the agent collects database name for some database drivers. The database name is reported on slow query traces and transaction traces.
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 7.0.0.166 or higher, distributed tracing is enabled by default.
Important
Enabling distributed tracing disables cross application tracing and has other effects on APM features. If migrating from cross application tracing, read the transition guide.
This setting can be used to turn on or off for all attributes for span events. If attributes.enabled at the root level is false, no attributes will be sent to span events regardless on how this configuration setting (span_events.attributes.enabled) is set. For more information, see the agent attribute rules.
If attributes are enabled for span events, all attribute keys found in this list will be sent in span events. For more information, see the agent attribute rules.
All attribute keys found in this list will not be sent in span events. For more information, see the agent attribute rules.
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.
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:
The agent reports object count metrics for the most common object types being collected by the garbage collector. For each object type, this setting allows you to set the maximum number of individual metrics that will be sampled.
Code-level metrics settings
The following settings are available for configuration of code-level metrics in the agent.
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.
If true, enables log decoration and the collection of log events and logging metrics if these sub-feature configurations are also enabled. If false, no logging instrumentation features are enabled.
If true, the agent captures log records emitted by your application and forwards them to New Relic. application_logging.enabled must also be true for this setting to take effect.
If you are already sending your application's logs to New Relic using an existing log forwarding solution, be sure to disable that before enabling log forwarding in the agent, in order to prevent being billed for duplicate log data.
A hash with key/value pairs to add as custom attributes to all log events forwarded to New Relic. The value must be formatted like: "key1:value1;key2:value2"
A case-insensitive list of label names to exclude when you enable including labels in logs. This attribute does not support wildcards or regex.
Important
When adding labels as attributes, the agent prefixes the keys with tags.. This prefix is NOT included when matching against the exclude filtering rules.
If true, the agent will capture available context data (extras, dictionary message attributes, attributes provided by logging frameworks) and add its contents as attributes on the logs forwarded to New Relic. You can control this behavior through the settings under the application_logging.forwarding.context_data section.
If attributes are enabled for context_data, all attribute keys found in this list will be sent to us in transaction traces. For more information, see the agent attribute rules.
Important
When adding context attributes, the agent prefixes the keys with context. for attributes from the logging framework context, and message. for attributes from a dictionary message context.
These prefixes are NOT included when matching against include/exclude filtering rules.
All attribute keys found in this list will not be sent in context_data. For more information, see the agent attribute rules.
Important
When adding context attributes, the agent prefixes the keys with context. for attributes from the logging framework context, and message. for attributes from a dictionary message context.
These prefixes are NOT included when matching against include/exclude filtering rules.
Number of log records to send per minute to New Relic. This setting controls overall memory consumption when using the log forwarding feature.
Set this to a lower value to reduce the amount of log lines sent (may cause log sampling). Set this to a higher value to send more log lines.
Each log receives the same priority as its associated transaction. Logs that occur outside of a transaction will receive a random priority. Some logs may not be included because they are limited by max_samples_stored. For example, if logging max_samples_stored is set to 10,000 and transaction 1 has 10,000 log entries, only log entries for transaction 1 will be recorded. If transaction 1 has less than 10,000 logs you receive all logs for transaction 1. If there is still space, you receive all the logs for transaction 2, and so on.
If after all the logs for sampled transactions are recorded, and they haven't reached the limit in max_samples_stored, then log messages for transactions that were not in our sampling are sent. If there are any left, log messages outside of transactions are recorded.
If true, the agent captures metrics related to the log lines being sent up by your application. application_logging.enabled must also be true for this setting to take effect.
If true, the agent decorates logs with metadata to link to entities, hosts, traces, and spans. application_logging.enabled must also be true for this setting to take effect.
Here are assorted other settings available via the agent configuration file.
Type
Boolean
Default
true
If true, the agent automatically detects that it is running in an AWS environment.
Type
String
Default
None
If set, the agent uses this AWS account_id to link AWS entities when an account ID cannot be automatically determined by the instrumentation. Refer AWS Manage Account Identifiers documentation for an example of a valid AWS account ID and how to find it.
Type
Boolean
Default
true
If true, the agent automatically detects that it is running in an Azure environment.
Type
Boolean
Default
true
If true, the agent automatically detects that it is running in a Google Cloud Platform environment.
Type
Boolean
Default
true
If true, the agent automatically detects that it is running in a Pivotal Cloud Foundry environment.
Type
Boolean
Default
true
If true, the agent automatically detects that it is running in Docker.
Enables you to schedule thread profiling sessions. The thread profiler will periodically capture a snapshot of the call stack for each active thread in the application to construct a statistically representative call tree.
If enabled, exception messages will be stripped from error traces before they are sent to the collector, in order to prevent the inadvertent capture of sensitive information. This option is automatically enabled in high-security mode.
Exceptions listed in your allow list will not have their messages stripped, even if strip_exception_messages.enabled is true. The allow list is a space-separated string of exception types, each in the form of module:exception_name. List built-in exceptions as exception_name; you do not need to prepend module: to them.
Example: Built-in exception and user-defined exception
By default, the agent starts when it receives the first transaction (either web or non-web). The agent then starts in parallel, ensuring that this initial request isn't delayed. However, the agent doesn't record the details of this initial request because the agent cannot collect data until registration is complete. This is the recommended configuration for the majority of web applications in order to not delay the first couple transactions while New Relic starts up.
To override this, you can set a startup timeout in seconds. The agent will then pause the initial transaction and wait for registration to complete. This might be useful when instrumenting a single program run or task, where the process runs once and immediately terminates.
Important
Since startup_timeout delays your app start, we recommend only setting a startup timeout for background task queuing systems, not web applications.
On process shutdown, the agent attempts one final upload to the collector. To prevent the agent running indefinitely in case of an issue, the process shuts down normally if the shutdown_timeout threshold is reached. This shutdown can result in data loss, but the agent prioritizes key metric data during the upload process.
For background task queuing systems, especially those which run a small number of tasks per process, you may want to increase the shutdown timeout to ensure the agent can upload all data on process shutdown.
Tip
The agent defaults to a 2.5 second timeout because Apache and many other web servers have a 3.0 second process termination timeout. The agent exits at 2.5 seconds to allow atexit cleanup code registered for the process to run.
If the data compression threshold is reached in the payload, the agent compresses data, using gzip compression by default. The config option compression_content_encoding can be set to deflate to use deflate compression.
If this setting is enabled, it will capture package and version information on startup of the agent that is displayed in the APM environment tab.
Tip
In applications that have a large number of packages, having this setting enabled may cause a CPU spike as it captures all the package and version information. It is recommended in those cases to disable this setting.
Caution
Disabling this setting will disable the ability to detect vulnerabilities in outdated packages.
If this setting is enabled, the agent will send detailed troubleshooting messages from its startup scripts directly to your console (STDOUT). This can be helpful for debugging crashes in the newrelic-admin startup script, the alternative bootstrap/sitecustomize.py startup script, or the startup sequence of the Kubernetes APM auto-attach.
Caution
This environment variable setting has no corresponding config file setting, as the code related to it runs before the config file is read. For comprehensive debug logging after the agent has started, set log level to debug.
This is an informational setting used to report when the agent is injected into a Microsoft Azure Container App.
Caution
This setting does not enable or disable this function of the agent.
Heroku
Type
Boolean
Default
true
Environ variable
NEW_RELIC_HEROKU_USE_DYNO_NAMES
If true, the agent uses Heroku dyno names as the hostname.
Type
Array
Default
["scheduler", "run"]
Environ variable
NEW_RELIC_HEROKU_DYNO_NAME_PREFIXES_TO_SHORTEN
Ordinarily the agent reports dyno names with a trailing dot and process ID (for example, worker.3). You can remove this trailing data by specifying the prefixes you want to report without trailing data (for example, worker).
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.
Add the following to the .ini configuration file:
[import-hook:MySQLdb]
enabled=false
Or for .toml configuration files add the following:
