Python agent configuration

New Relic for Python lets you change the default behavior of the New Relic Python agent using configuration options.

The only required Python agent configuration setting is the license key. 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.

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.

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 New Relic's download repo.

Server-side configuration

Owner or Admins

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.

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

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.

Example: Apache/mod_wsgi app name

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

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

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 to New Relic. 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 New Relic 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.

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 to New Relic, 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 New Relic. Enabling high security mode means that request parameters are not collected, and you cannot send raw SQL to New Relic.

To activate high security mode, set it to true in the local .ini configuration file and activate it in the Account Settings in the New Relic user interface. For more information, see High security.

By default, the Python agent attempts to directly connect to the New Relic service. If there is a firewall between your host and the New Relic 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.

Python agent versions 2.0.0 or earlier do not provide the proxy_scheme setting, and the protocol scheme defaults to http or https depending whether ssl is disabled or enabled. If you are upgrading from an older agent version and your config file doesn't include proxy_scheme, ensure you add the setting and set it appropriately. If you don't, the agent will continue to base the protocol scheme on the ssl setting for backwards compatibility. As proxies are usually only configured to accept proxy requests via the http protocol scheme, not setting proxy_scheme may result in a failure.

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

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 New Relic's data collection service.

This configuration option is only available in Python Agent versions 4.2.0 and newer.

Attributes

Attributes are key-value pairs that provide information for transaction traces, traced errors, browser monitoring, 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.

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.

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.

Transaction segment configuration

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 to New Relic in segments of transaction traces. For more information, see the agent attribute rules.

This setting can be used to turn on or off 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.

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 whitelist one of the default codes, 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.

Specify the HTML Content-Type(s) that New Relic Browser should auto-instrument. Add additional entries in a space-separated list.

Instrument xhtml+xml page responses

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:

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

The New Relic Browser 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 views in Insights. 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.

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.

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.

cross_application_tracer.enabled

A distributed tracing feature is now available. Distributed tracing improves on cross application tracing and is recommended for monitoring activity in complex distributed systems.

If enabled, exception messages will be stripped from error traces before they are sent to the New Relic collector, in order to prevent the inadvertent capture of sensitive information. This option is automatically enabled in high security mode.

Exceptions listed in the whitelist will not have their messages stripped, even if strip_exception_messages.enabled is true. The whitelist 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.

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 is not delayed. However, the agent does not record the details of this initial request because the agent cannot collect data until registration is complete.

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.

On process shutdown, the agent attempts one final upload to the New Relic 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.

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.

Heroku

heroku.use_dyno_names

Type

Boolean

Default

true

Environ variable

NEW_RELIC_HEROKU_USE_DYNO_NAMES

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

heroku.dyno_name_prefixes_to_shorten

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.