Python agent configuration

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:

• When you call newrelic.agent.initialize(), provide the path to the config file as the first argument.

  OR

• 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 configuration file uses a structure similar to Microsoft Windows .ini files. For more information, see the Python ConfigParser module's file format documentation.

  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.

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.

If you're using New Relic CodeStream to monitor performance from your IDE you may also want to associate repositories with your services and associate build SHAs or release tags with errors.

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 addition to being able to override certain agent configuration settings, you can set other per-request configuration settings with their WSGI environment key:

Specifies the license key of your New Relic account. This key associates your app's metrics with your New Relic account.

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 collects performance data about your app and reports this data to our data collector.

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.

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.

Adds tags. Specify name:value separated by a colon :, and separate additional tags with semicolons ;.

labels = Server:One;Data Center:Primary

Sets the hostname to be displayed in the APM UI. If set, this overrides the default hostname that the agent captures automatically.

Sets the api_key to be used with newrelic-admin record-deploy.

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.

We'll record transaction traces when they exceed this threshold. The format is a number of seconds (decimal points allowed).

See our glossary entry for apdex_t

This setting can be used to turn on or off all attributes.

If attributes are enabled, attribute keys found in this list will be sent to us. Keys in the list should be space-separated as shown below:

key1 key2 key3

Rules for attributes can be found on the agent attributes page.

All attribute keys found in this list will not be sent to us. Keys in the list should be space-separated as shown below:

key1 key2 key3

Rules for attributes can be found on the agent attributes page.

When set to true, enables AI monitoring.

When set to false, disables instrumentation that records summary and message events for streamed Large Language Model data.

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.

If enabled, the transaction tracer captures deep information about slow transactions.

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.

Determines whether the Python agent will capture query plans for slow SQL queries. Only supported in MySQL and PostgreSQL.

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.

All attribute keys found in this list will not be sent 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:

def validate_credentials():
…
def validate_status():
…
def format_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.

[newrelic]
...
transaction_tracer.function_trace = common.utils:validate*

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.

All attribute keys found in this list will not be sent in segments of transaction traces. For more information, see the agent attribute rules.

If enabled, the error collector captures information about uncaught exceptions.

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.

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.

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.

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.

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.

Attribute keys found in this list will not be sent to in traced errors. For more information, see the agent attribute rules.

If enabled, the error collector captures event data for advanced analytics. For more information, see APM Errors.

Enables browser monitoring. For more information, see Page load timing in Python.

For supported Python web frameworks, this setting enables auto-insertion of the browser monitoring JavaScript fragments.

Specify the HTML Content-Type(s) that our browser monitoring agent should auto-instrument. Add additional entries in a space-separated list.

browser_monitoring.content_type = text/html application/xhtml+xml

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 event data allows the use of additional information such as histograms and percentiles.

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.

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.

Allow recording of events to the Event API via record_custom_event().

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.

Enables Distributed Tracing

This setting can be used to turn on or off whether the Python agent sends spans.

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.

Limit for analytic events per minute sent by an instance of the Python agent to New Relic.

• Limits how many custom events per minute that an instance of the Python agent can send to New Relic.
• When configuring the agent for AI monitoring, set to max value 100000 to ensure the agent captures the maximum amount of LLM events.

• Limit for span events per minute sent by an instance of the Python agent to New Relic.
• When configuring the agent for AI monitoring, set to max value 10000 to ensure that the agent captures the maximum amount of distributed traces.

Limit for error events per minute sent by an instance of the Python agent to New Relic.

Set this to false to disable event loop information.

Threshold in seconds for how long a transaction must block the event loop before generating event loop information.

When enabled, the agent will generate and send runtime metrics per process ID.

When enabled, the agent will generate and send garbage collection metrics.

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.

Set this to false to disable agent attribute collection for code-level metrics.

The commit sha. The entire sha can be used or just the first seven characters (for example 734713b).

A release tag (such as v0.1.209 or release-209).

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

All attribute keys found in this list will not be sent in context_data. For more information, see the agent attribute 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.

When enabled, the agent will capture transactions for introspection queries in GraphQL.

Set to true to enable agent attribute collection for machine learning metrics.

Set to true to enable capturing of the raw inference value.

Allow recording of machine learning events to the Event API via record_ml_event().

If true, the agent automatically detects that it is running in an AWS environment.

If true, the agent automatically detects that it is running in an Azure environment.

If true, the agent automatically detects that it is running in a Google Cloud Platform environment.

If true, the agent automatically detects that it is running in a Pivotal Cloud Foundry environment.

If true, the agent automatically detects that it is running in Docker.

If enabled, the agent captures details from long-running SQL database queries.

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.

Enables cross application tracing, which connect your apps and services within your service-oriented architecture.

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

KeyError my_module:MyException

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.

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.

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.

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.

This is an informational setting used to report when the agent is injected into a Kubernetes cluster.

This is an informational setting used to report when the agent is injected into a Microsoft Azure Container App.

If true, the agent uses Heroku dyno names as the hostname.

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).

Add the following to the configuration file:

[import-hook:MySQLdb]
enabled = false