Our Python agent lets you change the default agent behavior 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.
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:

Here are detailed descriptions of each configuration method:
- Agent configuration file
-
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 thenewrelic-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 thenewrelic-admin
script using thegenerate-config
command, or download a copy from our download repo. -
- Server-side configuration
-
Server-side configuration allows you to configure certain settings in the New Relic One 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.
Environment variable Configuration setting NEW_RELIC_LICENSE_KEY
license_key
NEW_RELIC_APP_NAME
app_name
NEW_RELIC_MONITOR_MODE
monitor_mode
NEW_RELIC_DEVELOPER_MODE
developer_mode
NEW_RELIC_LOG
log_file
NEW_RELIC_LOG_LEVEL
log_level
NEW_RELIC_HIGH_SECURITY
high_security
NEW_RELIC_PROXY_SCHEME
proxy_scheme
NEW_RELIC_PROXY_HOST
proxy_host
NEW_RELIC_PROXY_PORT
proxy_port
NEW_RELIC_PROXY_USER
proxy_user
NEW_RELIC_PROXY_PASS
proxy_pass
NEW_RELIC_AUDIT_LOG
audit_log_file
NEW_RELIC_STARTUP_TIMEOUT
startup_timeout
NEW_RELIC_SHUTDOWN_TIMEOUT
shutdown_timeout
NEW_RELIC_LABELS
labels
NEW_RELIC_PROCESS_HOST_DISPLAY_NAME
process_host.display_name
NEW_RELIC_API_KEY
api_key
NEW_RELIC_CA_BUNDLE_PATH
ca_bundle_path
NEW_RELIC_DISTRIBUTED_TRACING_ENABLED
distributed_tracing.enabled
NEW_RELIC_FEATURE_FLAG
feature_flag
- Per-request configuration
-
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
and0
. 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 aLocation
orDirectory
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:
- newrelic.set_background_task
-
If set to
true
, this web transaction will instead be reported as a non-web transaction. - newrelic.ignore_transaction
-
If set to
true
, this web transaction will not be reported. - newrelic.suppress_apdex_metric
-
If set to
true
, no Apdex metric will be generated for this web transaction. - newrelic.suppress_transaction_trace
-
If set to
true
, this web transaction cannot be recorded in a transaction trace. - newrelic.disable_browser_autorum
-
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:
-
When you call
newrelic.agent.initialize()
, provide the environment name as the second argument.OR
- 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:
[newrelic] ... default settings [newrelic:development] ... override settings [newrelic:staging] ... override settings [newrelic:production] ... override settings
General configuration settings
These settings are available in the agent configuration file.
- license_key (REQUIRED)
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_LICENSE_KEY
Specifies the license key of your New Relic account. This key associates your app's metrics with your New Relic account.
- app_name (HIGHLY RECOMMENDED)
-
Type String Default Python Application
Set in Per-request option, config file, environment variable Per-request option newrelic.app_name
Environ variable NEW_RELIC_APP_NAME
The application name used to aggregate data in the New Relic One 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. - monitor_mode
-
Type Boolean Default true
Set in Config file, environment variable Environ variable NEW_RELIC_MONITOR_MODE
When
true
, the agent collects performance data about your app and reports this data to our data collector. - developer_mode
-
Type Boolean Default false
Set in Config file, environment variable Environ variable NEW_RELIC_DEVELOPER_MODE
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.
- log_file
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_LOG
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. - log_level
-
Type String Default info
Set in Config file, environment variable Environ variable NEW_RELIC_LOG_LEVEL
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, arecritical
,error
,warning
,info
, anddebug
.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
-
Type Boolean Default false
Set in Config file, environment variable Environ variable NEW_RELIC_HIGH_SECURITY
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 in the Account Settings in the UI. For more information, see High security. - proxy_scheme, proxy_host, proxy_port, proxy_user, proxy_pass
-
Type Strings Default (none) Set in Config file, environment variable Environ variables NEW_RELIC_PROXY_SCHEME
NEW_RELIC_PROXY_HOST
NEW_RELIC_PROXY_PORT
NEW_RELIC_PROXY_USER
NEW_RELIC_PROXY_PASS
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
andproxy_port
to the required values for your HTTP proxy. If proxy authentication is implemented by the HTTP proxy, also setproxy_user
andproxy_pass
.The
proxy_scheme
setting dictates what protocol scheme is used to talk to the HTTP proxy. When set tohttp
, the agent uses a SSL tunnel through the HTTP proxy for end-to-end encryption.Instead of setting the
proxy_scheme
,proxy_host
andproxy_port
settings, you can also set theproxy_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 theNEW_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 tohttp
orhttps
depending whetherssl
is disabled or enabled. If you are upgrading from an older agent version and your config file doesn't includeproxy_scheme
, ensure you add the setting and set it appropriately. If you don't, the agent will continue to base the protocol scheme on thessl
setting for backwards compatibility. As proxies are usually only configured to accept proxy requests via thehttp
protocol scheme, not settingproxy_scheme
may result in a failure. - audit_log_file
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_AUDIT_LOG
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.
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.
- labels (tags)
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_LABELS
Adds tags. Specify name:value separated by a colon
:
, and separate additional tags with semicolons;
.- Two tags
-
Server:One;Data Center:Primary
- process_host.display_name
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_PROCESS_HOST_DISPLAY_NAME
Sets the hostname to be displayed in the APM UI. If set, this overrides the default hostname that the agent captures automatically.
- api_key
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_API_KEY
Sets the api_key to be used with newrelic-admin record-deploy.
- ca_bundle_path
-
Type String Default (none) Set in Config file, environment variable Environ variable NEW_RELIC_CA_BUNDLE_PATH
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.
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.
For more information, see Python agent attributes, Enabling and disabling attributes, and Attribute examples.
- attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off all attributes.
- attributes.include
-
Type List of Strings Default (none) Set in Config file 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.
- attributes.exclude
-
Type List of Strings Default (none) Set in Config file 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.
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_tracer.enabled
-
Type Boolean Default true
Set in Server-side config, config file Server-side label Enable transaction tracing?
If enabled, the transaction tracer captures deep information about slow transactions.
- transaction_tracer.transaction_threshold
-
Type Positive float or string ( apdex_f
)Default apdex_f
Set in Server-side config, config file Server-side label Threshold
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). - transaction_tracer.record_sql
-
Type String Default obfuscated
Set in Server-side config, config file Server-side label Record SQL?
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), andobfuscated
(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 likeobfuscated
mode. - transaction_tracer.stack_trace_threshold
-
Type Float Default 0.5
Set in Server-side config, config file Server-side label Stack trace threshold
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.
- transaction_tracer.explain_enabled
-
Type Boolean Default true
Set in Server-side config, config file Server-side label Enable SQL query plans?
Determines whether the Python agent will capture query plans for slow SQL queries. Only supported in MySQL and PostgreSQL.
- transaction_tracer.explain_threshold
-
Type Float Default 0.5
Set in Server-side config, config file Server-side label Query plan threshold
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
isfalse
. - transaction_tracer.attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off all attributes for transaction traces. If
attributes.enabled
at the root level isfalse
, no attributes will be sent to transaction traces regardless on how this configuration setting (transaction_tracer.attributes.enabled
) is set. - transaction_tracer.attributes.include
-
Type List of strings Default (none) Set in Config file 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.
- transaction_tracer.attributes.exclude
-
Type List of Strings Default (none) Set in Config file All attribute keys found in this list will not be sent in transaction traces. For more information, see the agent attribute rules.
- transaction_tracer.function_trace
-
Type String Default (none) Set in Config file For the specified functions or methods, the agent will capture additional function timing instrumentation. Specify these names in the form
module:function
ormodule:class.function
.
Transaction segment configuration
Here are Transaction segment settings available via the agent configuration file.
- transaction_segments.attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off all attributes for segments of transaction traces. If
attributes.enabled
at the root level isfalse
, no attributes will be sent to segments of transaction traces regardless on how this configuration setting (transaction_segments.attributes.enabled
) is set. - transaction_segments.attributes.include
-
Type List of strings Default (none) Set in Config file 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.
- transaction_segments.attributes.exclude
-
Type List of Strings Default (none) Set in Config file All attribute keys found in this list will not be sent in segments of transaction traces. For more information, see the agent attribute rules.
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.
- error_collector.enabled
-
Type Boolean Default true
Set in Server-side config, config file Server-side label Enable error collection?
If enabled, the error collector captures information about uncaught exceptions.
- error_collector.ignore_errors
-
Type String Default (none) Set in Server-side config, config file Server-side label Ignore these errors
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. - error_collector.ignore_status_codes
-
Type String Default 100-102 200-208 226 300-308 404
Set in Config file 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.
- error_collector.attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off all attributes for traced errors. If
attributes.enabled
isfalse
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. - error_collector.attributes.include
-
Type List of strings Default (none) Set in Config file 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.
- error_collector.attributes.exclude
-
Type List of strings Default (none) Set in Config file Attribute keys found in this list will not be sent to in traced errors. For more information, see the agent attribute rules.
- error_collector.capture_events
-
Type Boolean Default true
Set in Config file If enabled, the error collector captures event data for advanced analytics. For more information, see APM Errors.
Browser monitoring settings
Here are browser monitoring settings available via the agent configuration file.
- browser_monitoring.enabled
-
Type Boolean Default true
Set in Config file Enables browser monitoring. For more information, see Page load timing in Python.
Before enabling browser monitoring in the config file, enable it in the application settings in the browser monitoring UI.
- browser_monitoring.auto_instrument
-
Type Boolean Default true
Set in Config file For supported Python web frameworks, this setting enables auto-insertion of the browser monitoring JavaScript fragments.
- browser_monitoring.content_type
-
Type String Default text/html
Set in Config file Specify the HTML
Content-Type
(s) that our browser monitoring agent 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
ofapplication/xhtml+xml
, you can override the allowed content types to list both this content type and the defaulttext/html
by using:browser_monitoring.content_type = text/html application/xhtml+xml
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.
- browser_monitoring.attributes.enabled
-
Type Boolean Default false
Set in Config file 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. - browser_monitoring.attributes.include
-
Type List of Strings Default (none) Set in Config file 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. - browser_monitoring.attributes.exclude
-
Type List of Strings Default (none) Set in Config file 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.
These configuration settings used to be called analytic_events
. If your configuration file still uses analytic_events
, update your agent to use transaction_events
.
- transaction_events.enabled
-
Type Boolean Default true
Set in Config file Transaction event data allows the use of additional information such as histograms and percentiles.
- transaction_events.attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off all attributes for transaction events. If
attributes.enabled
isfalse
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. - transaction_events.attributes.include
-
Type List of Strings Default (none) Set in Config file 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.
- transaction_events.attributes.exclude
-
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 Insights events settings
Here are Custom Insights events settings available via the agent configuration file.
- custom_insights_events.enabled
-
Type Boolean Default true
Set in Config file Allow recording of events to the Insights custom events API via
record_custom_event()
.
Datastore tracer settings
These datastore tracer settings are available via the agent configuration file:
- datastore_tracer.instance_reporting.enabled
-
Type Boolean Default true
Set in Config 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.
- datastore_tracer.database_name_reporting.enabled
-
Type Boolean Default true
Set in Config file 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
Enabling distributed tracing disables cross application tracing and has other effects on APM features. Before enabling, read the transition guide.
Requires Python agent version 4.2.0.100 or higher.
Distributed tracing lets you see the path that a request takes as it travels through a distributed system. Settings include:
- distributed_tracing.enabled
-
Type Boolean Default false
Set in Config file, environment variable Environ variable NEW_RELIC_DISTRIBUTED_TRACING_ENABLED
Set this to
true
to enable distributed tracing.
Span event configuration
Span events are collected for distributed tracing. Distributed tracing must be enabled to report span events. Configuration options include:
- span_events.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off whether the Python agent sends spans.
- span_events.attributes.enabled
-
Type Boolean Default true
Set in Config file This setting can be used to turn on or off for all attributes for span events. If
attributes.enabled
at the root level isfalse
, 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. - span_events.attributes.include
-
Type List of strings Default (none) Set in Config file 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.
- span_events.attributes.exclude
-
Type List of Strings Default (none) Set in Config file All attribute keys found in this list will not be sent in span events. For more information, see the agent attribute rules.
Event loop visibility settings
Requires Python agent version 5.0.0.124 or higher.
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:
- event_loop_visibility.enabled
-
Type Boolean Default true
Set in Config file Set this to
false
to disable event loop information. - event_loop_visibility.blocking_threshold
-
Type Float Default 0.1
Set in Config file Threshold in seconds for how long a transaction must block the event loop before generating event loop information.
Other configuration settings
Here are assorted other settings available via the agent configuration file.
- utilization.detect_aws
-
Type Boolean Default true
If
true
, the agent automatically detects that it is running in an AWS environment. - utilization.detect_azure
-
Type Boolean Default true
If
true
, the agent automatically detects that it is running in an Azure environment. - utilization.detect_gcp
-
Type Boolean Default true
If
true
, the agent automatically detects that it is running in a Google Cloud Platform environment. - utilization.detect_pcf
-
Type Boolean Default true
If
true
, the agent automatically detects that it is running in a Pivotal Cloud Foundry environment. - utilization.detect_docker
-
Type Boolean Default true
If
true
, the agent automatically detects that it is running in Docker. - slow_sql.enabled
-
Type Boolean Default true
Set in Server-side config, config file Server-side label Enable Slow SQL?
If enabled, the agent captures details from long-running SQL database queries.
- thread_profiler.enabled
-
Type Boolean Default true
Set in Server-side config, config file Server-side label Enable thread profiler?
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
-
Type Boolean Default true
Set in Config file Enables cross application tracing, which connect your apps and services within your service-oriented architecture.
- strip_exception_messages.enabled
-
Type Boolean Default false
Set in Config file 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.
- strip_exception_messages.whitelist
-
Type String Default (none) Set in Config file Exceptions listed in your allow list will not have their messages stripped, even if
strip_exception_messages.enabled
istrue
. The allow list is a space-separated string of exception types, each in the form ofmodule:exception_name
. List built-in exceptions asexception_name
; you do not need to prependmodule:
to them.Example: Built-in exception and user-defined exception
KeyError my_module:MyException
- startup_timeout
-
Type Float Default 0.0
Set in Config file, environment variable Environ variable NEW_RELIC_STARTUP_TIMEOUT
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.
Since
startup_timeout
delays your app start, we recommend only setting a startup timeout for background task queuing systems, not web applications. - shutdown_timeout
-
Type Float Default 2.5
Set in Config file, environment variable Environ variable NEW_RELIC_SHUTDOWN_TIMEOUT
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.
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. - compressed_content_encoding
-
Type String Default gzip
Set in Config file 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 todeflate
to use deflate compression.
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.
- Example: Disabling MySQLdb database query instrumentation
-
Add the following to the configuration file:
[import-hook:MySQLdb] enabled = false