--- title: Python agent configuration source: https://docs.newrelic.com/docs/apm/agents/python-agent/configuration/python-agent-configuration --- [Our Python agent](https://docs.newrelic.com/docs/agents/python-agent/getting-started/introduction-new-relic-python) 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 [#options] The primary way to configure the Python agent is via the [configuration file](#agent-configuration-file), which is generated as part of the standard [install process](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-installation). It is also possible to set a limited number of configuration options using [server-side configuration in the UI](#server-side-configuration) or by using [environment variables](#environment-variables). You can also specify some settings on a per-request basis by passing settings with the [WSGI request environ dictionary](#per-request-configuration). The Python agent follows this order of precedence for configuration: ![diagram-python-config-precedence.png](https://docs.newrelic.com/images/apm_diagram_config-settings.webp "diagram-python-config-precedence.png") 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: **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()`](https://docs.newrelic.com/docs/agents/python-agent/customization-extension/python-management-api#mgmt), 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 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. **\`.ini\` configuration file format** The configuration file uses a structure similar to Microsoft Windows `.ini` files. For more information, see the Python ConfigParser module's [file format documentation](https://docs.python.org/3/library/configparser.html). The basic structure should look like the following: ```ini [newrelic] license_key = app_name = Python Application ``` **\`.toml\` configuration file format** > #### 💡 TIP > > Starting with Python 3.11 the newer `.toml` syntax for configuration was added to the [standard library](https://docs.python.org/3/library/tomllib.html). 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](https://toml.io/en/). 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: ```ini [tool.newrelic] 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](https://download.newrelic.com/python_agent/release/). **Server-side configuration** [Server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/server-side-agent-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** 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](#server-side-configuration) and avoid the agent config file altogether. This is the default setup with [Heroku](https://docs.newrelic.com/docs/agents/python-agent/hosting-services/python-agent-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](https://docs.newrelic.com/docs/codestream/observability/repo-association) and [associate build SHAs or release tags with errors](https://docs.newrelic.com/docs/codestream/observability/error-investigation/#buildsha). | **Environment variable** | **Configuration setting** | | ------------------------------------------------------ | --------------------------------------------------- | | `NEW_RELIC_ENABLED` | `enabled` | | `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_HOST` | `host` | | `NEW_RELIC_OTLP_HOST` | `otlp_host` | | `NEW_RELIC_PORT` | `port` | | `NEW_RELIC_OTLP_PORT` | `otlp_port` | | `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_APDEX_T` | `apdex_t` | | `NEW_RELIC_GC_RUNTIME_METRICS_ENABLED` | `gc_runtime_metrics.enabled` | | `NEW_RELIC_MEMORY_RUNTIME_PID_METRICS_ENABLED` | `memory_runtime_pid_metrics.enabled` | | `NEW_RELIC_ANALYTICS_EVENTS_MAX_SAMPLES_STORED` | `transaction_events.max_samples_stored` | | `NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED` | `custom_insights_events.max_samples_stored` | | `NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_ATTRIBUTE_VALUE` | `custom_insights_events.max_attribute_value` | | `NEW_RELIC_ML_INSIGHTS_EVENTS_MAX_SAMPLES_STORED` | `event_harvest_config.harvest_limits.ml_event_data` | | `NEW_RELIC_SPAN_EVENTS_MAX_SAMPLES_STORED` | `span_events.max_samples_stored` | | `NEW_RELIC_ERROR_COLLECTOR_MAX_EVENT_SAMPLES_STORED` | `error_collector.max_event_samples_stored` | | `NEW_RELIC_FEATURE_FLAG` | `feature_flag` | **Per-request configuration** For certain WSGI servers, you can override the [app name](#app_name) and [capture attributes](#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](#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](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/monitor-background-processes-other-non-web-transactions). **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](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces). **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](https://docs.newrelic.com/docs/agents/python-agent/supported-features/page-load-timing-python#restrictions_on_instrumentation). > #### ⚠️ 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 [#config-file-deployment-environments] 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: - When you call [`newrelic.agent.initialize()`](https://docs.newrelic.com/docs/agents/python-agent/customization-extension/python-management-api#mgmt), 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: **\`.ini\` configuration file format** ```ini [newrelic] ... default settings [newrelic:development] ... override settings [newrelic:staging] ... override settings [newrelic:production] ... override settings ``` **\`.toml\` configuration file format** ```ini [tool.newrelic] ... default settings [tool.newrelic.env.development] ... override settings [tool.newrelic.env.staging] ... override settings [tool.newrelic.env.production] ... override settings ``` ## General configuration settings [#general-settings] These settings are available in the agent configuration file. **license_key (REQUIRED)** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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](#options) | Per-request option, config file, environment variable | | [Per-request option](#per-request-configuration) | `newrelic.app_name` | | [Environ variable](#environment-variables) | `NEW_RELIC_APP_NAME` | The [application name](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/name-your-application) used to aggregate data in the New Relic UI. To report data to [multiple apps at the same time](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/using-multiple-names-app), 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](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_MONITOR_MODE` | When `true`, the agent collects performance data about your app and reports this data to our [data collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector). **developer_mode** | Type | Boolean | | ------------------------------------------ | --------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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](https://docs.newrelic.com/docs/release-notes/agent-release-notes/python-release-notes), 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](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/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. **log_level** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | `info` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_LOG_LEVEL` | Sets the level of detail of log messages, if you've set the [log file location](#log_file). 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** | Type | Boolean | | ------------------------------------------ | --------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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 from the **Account settings** page. For more information, see [High security](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security). **proxy_scheme, proxy_host, proxy_port, proxy_user, proxy_pass** | Type | Strings | | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | Default | (none) | | [Set in](#options) | 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](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#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. **audit_log_file** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#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. **labels (tags)** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_LABELS` | Adds [tags](https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/labels-categories-organize-your-apps-servers). Specify _name:value_ separated by a colon `:`, and separate additional tags with semicolons `;`. **Two tags** ````ini labels = Server:One;Data Center:Primary ``` ```` **process_host.display_name** | Type | String | | ------------------------------------------ | ------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_PROCESS_HOST_DISPLAY_NAME` | Sets the hostname to be [displayed in the APM UI](https://docs.newrelic.com/docs/apm/new-relic-apm/maintenance/add-rename-remove-hosts#display_name). If set, this overrides the default hostname that the agent captures automatically. **api_key** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_API_KEY` | Sets the [api_key](https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-keys) to be used with [newrelic-admin record-deploy](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-admin-script#record-deploy). **ca_bundle_path** | Type | String | | ------------------------------------------ | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `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. > #### 💡 TIP > > This configuration option is only available in Python agent versions 4.2.0 and newer. **apdex_t** | Type | Float | | ------------------------------------------ | --------------------------------- | | Default | `0.5` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APDEX_T` | 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](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary/#apdex_t) > #### ⚠️ IMPORTANT > > 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, 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](https://docs.newrelic.com/docs/agents/python-agent/attributes/python-agent-attributes), [Enabling and disabling attributes](https://docs.newrelic.com/docs/agents/python-agent/attributes/enabling-disabling-attributes-python), and [Attribute examples](https://docs.newrelic.com/docs/agents/python-agent/attributes/python-attribute-examples). **attributes.enabled** | Type | Boolean | | -------------------------------- | --------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ATTRIBUTES_ENABLED` | This setting can be used to turn on or off all attributes. **attributes.include** | Type | List of Strings, space-separated | | -------------------------------- | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ATTRIBUTES_INCLUDE` | 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](/docs/subscriptions/agent-attributes). ```` **attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | --------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ATTRIBUTES_EXCLUDE` | 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](/docs/subscriptions/agent-attributes). ```` ## AI monitoring [#ai-monitoring] This section includes Python agent configurations for setting up AI monitoring. > #### ⚠️ IMPORTANT > > You must enable [distributed tracing](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/#dt-main) to capture AI data. It's turned on by default in Python agent versions 7.0.0.166 and higher. > #### ⚠️ IMPORTANT > > When enabled, AI monitoring records a streaming copy of inputs and outputs sent to and from the models you choose to monitor, including any personal information contained therein. > You're responsible for obtaining consent from your model users that their interactions may be recorded by a third party (New Relic) for the purpose of providing the AI monitoring feature. **ai_monitoring.enabled** | Type | Boolean | | -------------------------------- | --------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_AI_MONITORING_ENABLED` | When set to `true`, enables AI monitoring. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **ai_monitoring.streaming.enabled** | Type | Boolean | | -------------------------------- | ------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_AI_MONITORING_STREAMING_ENABLED` | When set to `false`, disables instrumentation that records summary and message events for streamed Large Language Model data. **ai_monitoring.record_content.enabled** | Type | Boolean | | -------------------------------- | ------------------------------------------------ | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_AI_MONITORING_RECORD_CONTENT_ENABLED` | 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 [#txn-tracer-settings] > #### ⚠️ 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. For more information about transaction traces, see [Transaction traces](https://docs.newrelic.com/docs/traces/transaction-traces). **transaction_tracer.enabled** | Type | Boolean | | ----------------------------------------------- | ------------------------------- | | Default | `true` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Enable transaction tracing?` | If enabled, the transaction tracer [captures deep information about slow transactions](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces). **transaction_tracer.transaction_threshold** | Type | Positive float or string (`apdex_f`) | | ----------------------------------------------- | ------------------------------------ | | Default | `apdex_f` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `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](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/glossary/#apdex_t)). **transaction_tracer.record_sql** | Type | String | | ----------------------------------------------- | ------------------------------- | | Default | `obfuscated` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Record SQL?` | When the transaction tracer is [enabled](#txn-tracer-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. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **transaction_tracer.stack_trace_threshold** | Type | Float | | ----------------------------------------------- | ------------------------------- | | Default | `0.5` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `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](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `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](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Query plan threshold` | Queries in transaction traces that exceed this threshold will report [slow query data](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/viewing-slow-query-details) and any available explain plans. Explain plan collection will not happen if [`transaction_tracer.explain_enabled`](#txn-tracer-explain-threshold) is `false`. **transaction_tracer.attributes.enabled** | Type | Boolean | | -------------------------------- | ------------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_ENABLED` | 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_tracer.attributes.include** | Type | List of strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **transaction_tracer.attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_EXCLUDE` | All attribute keys found in this list will not be sent in transaction traces. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **transaction_tracer.function_trace** | Type | String | | ------------------ | ----------- | | Default | (none) | | [Set in](#options) | Config file | 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](https://docs.python.org/3/library/fnmatch.html) 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 ````py 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. my-app/newrelic.ini ```ini [newrelic] ... transaction_tracer.function_trace = common.utils:validate* ``` Wilcarding requires [Python agent version 6.4.4.161 or higher](/docs/agents/python-agent/installation-configuration/upgrade-python-agent). ```` ## Transaction segment configuration [#txn-segment-settings] Here are Transaction segment settings available via the agent configuration file. **transaction_segments.attributes.enabled** | Type | Boolean | | -------------------------------- | --------------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_ENABLED` | 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. **transaction_segments.attributes.include** | Type | List of strings, space-separated | | -------------------------------- | --------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **transaction_segments.attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | --------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_SEGMENTS_ATTRIBUTES_EXCLUDE` | All attribute keys found in this list will not be sent in segments of transaction traces. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). ## Error collector configuration [#error-collector-settings] Here are error collector settings available via the agent configuration file. > #### 💡 TIP > > For an overview of error configuration in APM, see [Manage errors in APM](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-mark-expected). **error_collector.enabled** | Type | Boolean | | ----------------------------------------------- | ------------------------------- | | Default | `true` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Enable error collection?` | If enabled, the error collector captures information about uncaught exceptions. **error_collector.ignore_classes** | Type | String | | ----------------------------------------------- | ------------------------------- | | Default | (none) | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `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. > #### ⚠️ CAUTION > > `error_collector.ignore_errors` was removed in version 11.0.0. 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`. **error_collector.ignore_status_codes** | Type | String | | ----------------------------------------------- | --------------------------------- | | Default | `100-102 200-208 226 300-308 404` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Ignore these status codes` | 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. **error_collector.expected_classes** | Type | String | | ----------------------------------------------- | -------------------------------- | | Default | (none) | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Expect these error class names` | 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. **error_collector.expected_status_codes** | Type | String | | ----------------------------------------------- | ------------------------------- | | Default | (none) | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Expect these status codes` | 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. **error_collector.max_event_samples_stored** | Type | Integer | | ------------------------------------------ | ---------------------------------------------------- | | Default | 100 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ERROR_COLLECTOR_MAX_EVENT_SAMPLES_STORED` | Limit for error events per minute sent by an instance of the Python agent to New Relic. **error_collector.attributes.enabled** | Type | Boolean | | -------------------------------- | ---------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_ENABLED` | 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. **error_collector.attributes.include** | Type | List of strings, space-separated | | -------------------------------- | ---------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **error_collector.attributes.exclude** | Type | List of strings, space-separated | | -------------------------------- | ---------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_ERROR_COLLECTOR_ATTRIBUTES_EXCLUDE` | Attribute keys found in this list will not be sent to in traced errors. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **error_collector.capture_events** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | If enabled, the error collector captures event data for advanced analytics. For more information, see [APM Errors](https://docs.newrelic.com/docs/apm/applications-menu/events/view-apm-errors-error-traces). ## Browser monitoring settings [#browser-settings] Here are browser monitoring settings available via the agent configuration file. **browser_monitoring.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | Enables browser monitoring. For more information, see [Page load timing in Python](https://docs.newrelic.com/docs/python/page-load-timing-in-python). > #### ⚠️ IMPORTANT > > Before enabling browser monitoring in the config file, [enable it in the application settings in the browser monitoring UI](https://docs.newrelic.com/docs/browser/new-relic-browser/installation-configuration/adding-apps-new-relic-browser#select-apm-app). **browser_monitoring.auto_instrument** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | For [supported Python web frameworks](https://docs.newrelic.com/docs/agents/python-agent/supported-features/page-load-timing-python#restrictions_on_instrumentation), this setting enables auto-insertion of the browser monitoring JavaScript fragments. **browser_monitoring.content_type** | Type | String | | ------------------ | ----------- | | Default | `text/html` | | [Set in](#options) | 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` of `application/xhtml+xml`, you can override the allowed content types to list both this content type and the default `text/html` by using: ````ini 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](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_ENABLED` | 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. **browser_monitoring.attributes.include** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **browser_monitoring.attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_BROWSER_MONITORING_ATTRIBUTES_EXCLUDE` | All attribute keys found in this list will not be sent in page views. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). ## 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`. **transaction_events.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | Transaction event data allows the use of additional information such as [histograms](https://docs.newrelic.com/docs/applications-menu/histograms-viewing-data-distribution) and [percentiles](https://docs.newrelic.com/docs/applications-menu/percentiles-comparing-ranked-data). **transaction_events.max_samples_stored** | Type | Integer | | ------------------------------------------ | ----------------------------------------------- | | Default | `1200` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ANALYTICS_EVENTS_MAX_SAMPLES_STORED` | Limit for analytic events per minute sent by an instance of the Python agent to New Relic. **transaction_events.attributes.enabled** | Type | Boolean | | -------------------------------- | ------------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_ENABLED` | 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. **transaction_events.attributes.include** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **transaction_events.attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_EVENTS_ATTRIBUTES_EXCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). ## Custom events settings Here are custom events settings available via the agent configuration file. **custom_insights_events.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | Allow recording of events to the Event API via [`record_custom_event()`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/recordcustomevent-python-agent-api/). > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **custom_insights_events.max_samples_stored** | Type | Integer | | ------------------ | ----------- | | Default | `3600` | | [Set in](#options) | Config file | - 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](https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring), set to max value `100000` to ensure the agent captures the maximum amount of LLM events. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. ## 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](#options) | 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](#options) | 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 [#dt-main] 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](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent), distributed tracing is enabled by default. > #### ⚠️ IMPORTANT > > Enabling distributed tracing disables [cross application tracing](#cross-application-tracer) and has other effects on APM features. If migrating from cross application tracing, read the [transition guide](https://docs.newrelic.com/docs/transition-guide-distributed-tracing). For more information, see [Distributed tracing for your Python services](https://docs.newrelic.com/docs/apm/agents/python-agent/configuration/distributed-tracing-python-agent). Settings include: **distributed_tracing.enabled** | Type | Boolean | | ------------------------------------------ | --------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_ENABLED` | Enables [Distributed Tracing](https://docs.newrelic.com/docs/distributed-tracing/concepts/introduction-distributed-tracing) **distributed_tracing.sampler.remote_parent_sampled** | Type | String | | ---------------------------------------------- | ------------------------------------------------------------- | | Adaptive | `adaptive` | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_SAMPLED` | This is the sampler that is applied when the trace has a remote parent (that is, the trace originated in an upstream service) that has been sampled. Sampler options are: - `adaptive` is the default behavior and delegates the sampling decision to the adaptive sampling algorithm to determine whether a trace will be sampled. - `trace_id_ratio_based` delegates the sampling decision to the Trace ID Ratio Based sampling algorithm to determine whether a trace will be sampled. If you use this option, the ratio is required, so use [distributed_tracing.sampler.remote_parent_sampled.trace_id_ratio_based.ratio](#distributed-tracing-sampler-remote-parent-sampled-trace-id-ratio-based-ratio) instead. - `always_on`: Always samples traces that have a sampled remote parent. - `always_off`: Never samples traces that have a sampled remote parent. **distributed_tracing.sampler.remote_parent_sampled.trace_id_ratio_based.ratio** | Type | Float | | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | | Unset | | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_SAMPLED_TRACE_ID_RATIO_BASED_RATIO` | - A number between 0 (exclusive) and 1 inclusive. **distributed_tracing.sampler.remote_parent_not_sampled** | Type | String | | ---------------------------------------------- | ----------------------------------------------------------------- | | Adaptive | `adaptive` | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_NOT_SAMPLED` | This is the sampler that is applied when a trace has a remote parent (that is, the trace originated in an upstream service) that was not sampled. Sampler options are: - `adaptive` is the default behavior and delegates the sampling decision to the adaptive sampling algorithm to determine whether a trace will be sampled. - `trace_id_ratio_based` delegates the sampling decision to the Trace ID Ratio Based sampling algorithm to determine whether a trace will be sampled. If you use this option, the ratio is required, so use [distributed_tracing.sampler.remote_parent_not_sampled.trace_id_ratio_based.ratio](#distributed-tracing-sampler-remote-parent-not-sampled-trace-id-ratio-based-ratio) instead. - `always_on`: Always samples traces that have an unsampled remote parent. - `always_off`: Never samples traces that have an unsampled remote parent. **distributed_tracing.sampler.remote-parent-not-sampled.trace_id_ratio_based.ratio** | Type | Float | | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | | Unset | | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_NOT_SAMPLED_TRACE_ID_RATIO_BASED_RATIO` | - A number between 0 (exclusive) and 1 inclusive. **distributed_tracing.sampler.root** | Type | String | | ---------------------------------------------- | -------------------------------------------- | | Adaptive | `adaptive` | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT` | This is the sampler that is applied at the beginning of a trace. By default, the Adaptive Sampler is configured as the Root sampler. Sampler options are: - `adaptive` is the default behavior and delegates the sampling decision to the adaptive sampling algorithm to determine whether a trace will be sampled. - `trace_id_ratio_based` delegates the sampling decision to the Trace ID Ratio Based sampling algorithm to determine whether a trace will be sampled. If you use this option, the ratio is required, so use [distributed_tracing.sampler.root.trace_id_ratio_based.ratio](#distributed-tracing-sampler-root-trace-id-ratio-based-ratio) instead. - `always_on`: Always samples transactions that originate from the current service and do not have a distributed tracing header present for the entry call. - `always_off`: Never samples transactions that originate from the current service and do not have a distributed tracing header present for the entry call. **distributed_tracing.sampler.root.trace_id_ratio_based.ratio** | Type | Float | | ---------------------------------------------- | ----------------------------------------------------------------------- | | Unset | | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT_TRACE_ID_RATIO_BASED_RATIO` | - A number between 0 (exclusive) and 1 inclusive. ## Span event configuration [#txn-span-events-settings] [Span events](https://docs.newrelic.com/docs/apm/distributed-tracing/getting-started/how-new-relic-distributed-tracing-works#data-structure) are collected for [distributed tracing](#distributed-tracing-settings). Distributed tracing must be enabled to report span events. Configuration options include: **span_events.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | This setting can be used to turn on or off whether the Python agent sends spans. **span_events.max_samples_stored** | Type | Integer | | ------------------------------------------ | ------------------------------------------ | | Default | `2000` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_SPAN_EVENTS_MAX_SAMPLES_STORED` | - Limit for span events per minute sent by an instance of the Python agent to New Relic. - When configuring the agent for [AI monitoring](https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring), set to max value `10000` to ensure that the agent captures the maximum amount of distributed traces. **span_events.attributes.enabled** | Type | Boolean | | -------------------------------- | ------------------------------------------ | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_ENABLED` | This setting can be used to turn on or off for all [attributes](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/glossary#attribute) 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **span_events.attributes.include** | Type | List of strings, space-separated | | -------------------------------- | ------------------------------------------ | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). **span_events.attributes.exclude** | Type | List of Strings, space-separated | | -------------------------------- | ------------------------------------------ | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_EXCLUDE` | All attribute keys found in this list will not be sent in span events. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). ## Event harvest configuration [#event-harvest-config] 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](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/real-time-streaming) sends data every five seconds (12 times per minute), but the event harvest settings still affect the rate in events per **minute**. Enabling or disabling real time streaming does not require changing these settings. - With real time streaming (enabled by default), New Relic will display the event harvest limits for entities in five second intervals. This means, for example, when you set a limit value of 1200 in the config file, you'll see it as 100 in New Relic. ### Usage example Let's say an application is deployed across 10 hosts, each running four processes per host. To limit the number of span events to 10,000 events per minute for the entire application, divide that number by 10 hosts. Then divide again by four processes per host. 10000 / (10 \* 4) = 250 Based on that calculation, the final setting is: span_events.max_samples_stored = 250 > #### 💡 TIP > > Because of the way New Relic harvests data (12 times per minute), if the event data count is less than 12, it will show up as 0 in New Relic. Event harvest configuration settings include: **event_harvest_config.harvest_limits.analytic_event_data** | Type | Integer | | ------------------------------------------ | ----------------------------------------------- | | Default | `1200` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ANALYTICS_EVENTS_MAX_SAMPLES_STORED` | > #### ⚠️ WARNING > > This setting has been deprecated starting in version 11.0.0. Please use [`transaction_events.max_samples_stored`](#transaction-events-max-samples-stored) instead. Limit for analytic events per minute sent by an instance of the Python agent to New Relic. **event_harvest_config.harvest_limits.custom_event_data** | Type | Integer | | ------------------------------------------ | ----------------------------------------------------- | | Default | `3600` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED` | > #### ⚠️ WARNING > > This setting has been deprecated starting in version 11.0.0. Please use [`custom_insights_events.max_samples_stored`](#custom-insights-events-max-samples-stored) instead. Limit for how many custom events per minute that an instance of the Python agent can send to New Relic. **event_harvest_config.harvest_limits.span_event_data** | Type | Integer | | ------------------------------------------ | ------------------------------------------ | | Default | `2000` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_SPAN_EVENTS_MAX_SAMPLES_STORED` | > #### ⚠️ WARNING > > This setting has been deprecated starting in version 11.0.0. Please use [`span_events.max_samples_stored`](#cfg-tt-max-samples-stored) instead. - Limit for span events per minute sent by an instance of the Python agent to New Relic. - When configuring the agent for [AI monitoring](https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring), set to max value `10000` to ensure that the agent captures the maximum amount of distributed traces. **event_harvest_config.harvest_limits.error_event_data** | Type | Integer | | ------------------------------------------ | ---------------------------------------------------- | | Default | 100 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ERROR_COLLECTOR_MAX_EVENT_SAMPLES_STORED` | > #### ⚠️ WARNING > > This setting has been deprecated starting in version 11.0.0. Please use [`error_collector.max_event_samples_stored`](#error-max-event-samples-stored) instead. Limit for error events per minute sent by an instance of the Python agent to New Relic. **event_harvest_config.harvest_limits.ml_event_data** | Type | Integer | | ------------------------------------------ | ------------------------------------------------- | | Default | 100000 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ML_INSIGHTS_EVENTS_MAX_SAMPLES_STORED` | Limit for how many ML events per minute that an instance of the Python agent can send to New Relic. ## Event loop visibility settings [#event-loop] > #### ⚠️ IMPORTANT > > Requires [Python agent version 5.0.0.124 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). 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](#options) | Config file | Set this to `false` to disable event loop information. **event_loop_visibility.blocking_threshold** | Type | Float | | ------------------ | ----------- | | Default | `0.1` | | [Set in](#options) | Config file | Threshold in seconds for how long a transaction must block the event loop before generating event loop information. ## Runtime metrics for physical memory [#runtime-metrics] > #### ⚠️ IMPORTANT > > Requires [Python agent version 9.9.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). These runtime metrics settings are available via the agent configuration file: **memory_runtime_pid_metrics.enabled** | Type | Boolean | | ------------------------------------------ | ---------------------------------------------- | | Default | true | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_MEMORY_RUNTIME_PID_METRICS_ENABLED` | When enabled, the agent will generate and send runtime metrics per process ID. ## Garbage collection runtime metrics settings [#garbage-collection-runtime-metrics] > #### ⚠️ IMPORTANT > > Requires [Python agent version 6.2.0.156 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). These garbage collection runtime metrics settings are available via the agent configuration file: **gc_runtime_metrics.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | false | | [Set in](#options) | Config file | When enabled, the agent will generate and send garbage collection metrics. **gc_runtime_metrics.top_object_count_limit** | Type | Integer | | ------------------ | ----------- | | Default | 5 | | [Set in](#options) | Config file | 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 [#codestream-integration] The following settings are available for configuration of code-level metrics in the agent. **code_level_metrics.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `true` | | [Set in](#options) | Config file | Set this to `false` to disable agent attribute collection for code-level metrics. **NEW_RELIC_METADATA_COMMIT** > #### ⚠️ IMPORTANT > > This can only be set through an environment variable. | Type | Integer | | ------------------ | -------------------- | | Default | `None` | | [Set in](#options) | Environment variable | The commit sha. The entire sha can be used or just the first seven characters (for example 734713b). **NEW_RELIC_METADATA_RELEASE_TAG** > #### ⚠️ IMPORTANT > > This can only be set through an environment variable. | Type | String | | ------------------ | -------------------- | | Default | `None` | | [Set in](#options) | Environment variable | A release tag (such as v0.1.209 or release-209). ## Errors inbox configuration [#errors-inbox-configuration] Setting one of the following tags will help you identify which versions of your software are producing the errors. - `NEW_RELIC_METADATA_SERVICE_VERSION` will create tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always. - `NEW_RELIC_METADATA_RELEASE_TAG ` will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209). - `NEW_RELIC_METADATA_COMMIT` will create tags.commit on event data containing the commit sha. The entire sha can be used or just the first seven characters (e.g., 734713b). An upcoming release of errors inbox will automatically track which versions of your software are producing errors. Any version data will also be displayed in [CodeStream](https://docs.newrelic.com/docs/codestream/how-use-codestream/performance-monitoring/#buildsha). ## Application logging settings [#application-logging] The following settings are available for configuration of application logging in the agent. For some tips on configuring logs for the Python agent, see [Configure Python logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-python). > #### ⚠️ IMPORTANT > > Requires [Python agent version 7.12.0.176 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). **application_logging.enabled** | Type | Boolean | | ------------------------------------------ | --------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_ENABLED` | 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. **application_logging.forwarding.enabled** | Type | Boolean | | ------------------------------------------ | -------------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_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. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. > #### ⚠️ CAUTION > > 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. **application_logging.forwarding.custom_attributes** | Type | String | | ------------------------------------------ | ------------------------------------------------------------ | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_CUSTOM_ATTRIBUTES` | 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" **application_logging.forwarding.labels.enabled** | Type | Boolean | | ------------------------------------------ | --------------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_LABELS_ENABLED` | Toggles whether the agent will add labels to log records for sending to New Relic. **application_logging.forwarding.labels.exclude** | Type | List of strings | | ------------------------------------------ | --------------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_LABELS_EXCLUDE` | A case-insensitive list of label names to exclude when you enable including labels in logs. This attribute does not support wildcards or regex. When adding labels as attributes, the agent prefixes the keys with tags.. This prefix is NOT included when matching against the exclude filtering rules. **application_logging.forwarding.context_data.enabled** | Type | Boolean | | ------------------------------------------ | --------------------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_CONTEXT_DATA_ENABLED` | 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. **application_logging.forwarding.context_data.include** | Type | List of strings | | ------------------------------------------ | --------------------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_CONTEXT_DATA_INCLUDE` | 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](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). > #### ⚠️ 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. **application_logging.forwarding.context_data.exclude** | Type | List of Strings | | ------------------------------------------ | --------------------------------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_CONTEXT_DATA_EXCLUDE` | All attribute keys found in this list will not be sent in context_data. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes). > #### ⚠️ 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. **application_logging.forwarding.max_samples_stored** | Type | Integer | | ------------------------------------------ | ------------------------------------------------------------- | | Default | 10000 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED` | 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. **event_harvest_config.harvest_limits.log_event_data** | Type | Integer | | ------------------------------------------ | ------------------------------------------------------------- | | Default | 10000 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED` | > #### ⚠️ WARNING > > This setting has been deprecated starting in version 11.0.0. Please use [`application_logging.forwarding.max_samples_stored`](#application-logging-forwarding-max-samples-stored) instead. 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. **application_logging.metrics.enabled** | Type | Boolean | | ------------------------------------------ | ----------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_METRICS_ENABLED` | 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. **application_logging.local_decorating.enabled** | Type | Boolean | | ------------------------------------------ | -------------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED` | 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. ## Instrumentation settings [#instrumentation-settings] > #### ⚠️ IMPORTANT > > Requires [Python agent version 8.7.1 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). These instrumentation package specific settings are available via the agent configuration file: **instrumentation.graphql.capture_introspection_queries** | Type | Boolean | | ------------------------------------------ | ----------------------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_INSTRUMENTATION_GRAPHQL_CAPTURE_INTROSPECTION_QUERIES` | When enabled, the agent will capture transactions for introspection queries in GraphQL. **instrumentation.kombu.consumer.enabled** | Type | Boolean | | ------------------------------------------ | -------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_INSTRUMENTATION_KOMBU_CONSUMER_ENABLED` | When enabled, the agent will consumer MessageTransactions in Kombu. **instrumentation.kombu.ignored_exchanges** | Type | List of Strings | | ------------------------------------------ | --------------------------------------------------- | | Default | `celeryev` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_INSTRUMENTATION_KOMBU_IGNORED_EXCHANGES` | A space separated list of exchanges to ignore when capturing MessageTransactions in Kombu. ## Middleware Instrumentation Filters [#middleware-filters] > #### ⚠️ IMPORTANT > > Requires [Python agent version 10.17.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). These instrumentation package specific settings are available for toggling middleware instrumentation: **instrumentation.middleware.django.enabled** | Type | Boolean | | ---------------------------------------------- | ----------------------------------------------------- | | Default | `true` | | [Set in](#options) | Config file, environment variable | | [Environment variable](#environment-variables) | `NEW_RELIC_INSTRUMENTATION_DJANGO_MIDDLEWARE_ENABLED` | When enabled, the agent will monitor middleware in Django. **instrumentation.middleware.django.include** | Type | List of Strings | | ------------------ | --------------- | | Default | (none) | | [Set in](#options) | Config file | If middleware instrumentation is enabled, middleware names found in this list will be sent. Names in the list should be space-separated as shown below: ```` middleware1 middleware2 middleware3 ``` Rules for middleware instrumentation filtering can be found [on the middleware filtering page](/docs/apm/agents/python-agent/supported-features/django-middleware-filtering/#django-middleware-rules). ```` **instrumentation.middleware.django.exclude** | Type | List of Strings | | ------------------ | --------------- | | Default | (none) | | [Set in](#options) | Config file | Middleware names found in this list will NOT be sent. Names in the list should be space-separated as shown below: ```` middleware1 middleware2 middleware3 ``` Rules for middleware instrumentation filtering can be found [on the middleware filtering page](/docs/apm/agents/python-agent/supported-features/django-middleware-filtering/#django-middleware-rules). ```` ## Machine Learning settings [#ml-settings] > #### ⚠️ IMPORTANT > > Requires [Python agent version 9.1.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). The following settings are available for configuration of machine learning data in the agent. **machine_learning.enabled** | Type | Boolean | | ------------------------------------------ | ------------------------------------ | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_MACHINE_LEARNING_ENABLED` | Set to `true` to enable agent attribute collection for machine learning metrics. **machine_learning.inference_events_value.enabled** | Type | Boolean | | ------------------------------------------ | ---------------------------------------------------------- | | Default | `false` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_MACHINE_LEARNING_INFERENCE_EVENT_VALUE_ENABLED` | Set to `true` to enable capturing of the raw inference value. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **ml_insights_events.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `false` | | [Set in](#options) | Config file | Allow recording of machine learning events to the Event API via [`record_ml_event()`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/recordmlevent-python-agent-api/). > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **event_harvest_config.harvest_limits.ml_event_data** | Type | Integer | | ------------------------------------------ | ------------------------------------------------- | | Default | 100000 | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_ML_INSIGHTS_EVENTS_MAX_SAMPLES_STORED` | Limit for how many ML events per minute that an instance of the Python agent can send to New Relic. ## Hybrid agent settings [#otel-settings] > #### ⚠️ IMPORTANT > > Requires [Python agent version 11.5.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). For more information on hybrid agent functionalities, refer to [this page](https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/opentelemetry-api-support). The following settings are available for configuration of the hybrid agent: **opentelemetry.enabled** | Type | Boolean | | ------------------------------------------ | --------------------------------- | | Default | False | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_OPENTELEMETRY_ENABLED` | From v11.5.0 to v13.0.0: If enabled, any OpenTelemetry API and most [OpenTelemetry instrumented frameworks](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation#readme) that are installed will be used. From v13.0.0+: If enabled, any OpenTelemetry API and frameworks that are [supported by OpenTelemetry](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation#readme) but not New Relic will be used. > #### ⚠️ IMPORTANT > > While most libraries in [OpenTelemetry's instrumented frameworks](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation#readme) are supported, AWS and gRPC instrumentation libraries will continue to use New Relic's instrumentation. ML/AI libraries with native instrumentation are explicitly disabled for now and will be supported in a future release. **opentelemetry.traces.enabled** | Type | Boolean | | ------------------------------------------ | ---------------------------------------- | | Default | True | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_OPENTELEMETRY_TRACES_ENABLED` | From v11.5.0 to v13.0.0: If enabled, any OpenTelemetry span and trace APIs will be used, regardless of whether an existing New Relic instrumentation library exists. From v13.0.0+: If enabled, any manual call using the OpenTelemetry span API and spans from frameworks that are [supported by OpenTelemetry](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation#readme) but not New Relic will be used. **opentelemetry.traces.exclude** | Type | List of Strings, comma-separated | | ------------------------------------------ | ---------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_OPENTELEMETRY_TRACES_EXCLUDE` | Enables users to exclude tracer(s) from being reported to New Relic. See the [section below](#include-exclude-rules) for more details. > #### ⚠️ IMPORTANT > > Requires [Python agent version 13.0.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). **opentelemetry.traces.include** | Type | List of Strings, comma-separated | | ------------------------------------------ | ---------------------------------------- | | Default | (none) | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_OPENTELEMETRY_TRACES_INCLUDE` | Enables users to include tracer(s) to be reported to New Relic. See the [section below](#include-exclude-rules) for more details. > #### ⚠️ IMPORTANT > > Requires [Python agent version 13.0.0 or higher](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/upgrade-python-agent). Include and Exclude rules [#include-exclude-rules] New Relic follows these rules when determining which tracers to include or exclude for monitoring. **Enabled takes precedence over include and exclude.** `opentelemetry.traces.enabled` flag takes precedence over include and exclude settings. Example configuration: ````ini opentelemetry.traces.enabled = false opentelemetry.traces.include = one,two ``` Example output: ``` Tracers used: one, two, three, four Tracers included: Tracers excluded: one, two, three, four ``` ```` **Trace is included if tracing is enabled.** If tracing is enabled, any custom OpenTelemetry tracers and tracers from OpenTelemetry libraries not supported by New Relic are monitored by default. Example configuration: ````ini opentelemetry.traces.enabled = true opentelemetry.traces.exclude = myTrace ``` Example output: ``` Tracers used: foo, bar, myTrace Tracers included: foo, bar Tracers excluded: myTrace ``` ```` **Exclude always supersedes include.** If the same tracer is listed in the include and exclude lists, then the tracer will be excluded. Example configuration: ````ini opentelemetry.traces.enabled = true opentelemetry.traces.include = foo,myTrace opentelemetry.traces.exclude = bar,myTrace ``` Example output: ``` Tracers used: foo, myTrace, bar Tracers included: foo Tracers excluded: bar, myTrace ``` ```` **Tracers are case sensitive.** Tracers are case sensitive. Example configuration: ````ini opentelemetry.traces.enabled = true opentelemetry.traces.exclude = myTrace,mYtRaCe ``` Example output: ``` Tracers used: mytrace, Mytrace, MYTRACE, mYtRaCe, MyTRACE Tracers included: mytrace, Mytrace, MYTRACE, MyTRACE Tracers excluded: mYtRaCe ``` ```` ## Other configuration settings [#other-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. **cloud.aws.account_id** | 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](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html#awsaccountid) for an example of a valid AWS account ID and how to find it. **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](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Enable Slow SQL?` | If enabled, the agent captures details from long-running SQL database queries. **thread_profiler.enabled** | Type | Boolean | | ----------------------------------------------- | ------------------------------- | | Default | `true` | | [Set in](#options) | Server-side config, config file | | [Server-side label](#server-side-configuration) | `Enable thread profiler?` | Enables you to schedule [thread profiling sessions](https://docs.newrelic.com/docs/apm/applications-menu/events/thread-profiler-dashboard). 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 | `false` | | [Set in](#options) | Config file | Enables [cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/introduction-cross-application-traces), which connect your apps and services within your service-oriented architecture. > #### ⚠️ CAUTION > > [Cross application tracing (CAT)](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/introduction-cross-application-traces) has been completely removed in version 12.0.0. **strip_exception_messages.enabled** | Type | Boolean | | ------------------ | ----------- | | Default | `false` | | [Set in](#options) | Config file | If enabled, exception messages will be stripped from error traces before they are sent to the [collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector), in order to prevent the inadvertent capture of sensitive information. This option is automatically enabled in high-security mode. > #### ⚠️ IMPORTANT > > This setting is disabled when [high security mode](https://docs.newrelic.com/docs/apm/agents/python-agent/getting-started/apm-agent-security-python/#restricted) is enabled. **strip_exception_messages.allowlist** | Type | String | | ------------------ | ----------- | | Default | (none) | | [Set in](#options) | Config file | 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** ````py KeyError my_module:MyException ``` ```` **startup_timeout** | Type | Float | | ------------------------------------------ | --------------------------------- | | Default | `0.0` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_STARTUP_TIMEOUT` | By default, the agent starts when it receives the first transaction (either web or [non-web](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/monitor-background-processes-other-non-web-transactions)). 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. **shutdown_timeout** | Type | Float | | ------------------------------------------ | --------------------------------- | | Default | `2.5` | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_SHUTDOWN_TIMEOUT` | On process shutdown, the agent attempts one final upload to the [collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#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. **compressed_content_encoding** | Type | String | | ------------------ | ----------- | | Default | `gzip` | | [Set in](#options) | 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 to `deflate` to use deflate compression. **package_reporting.enabled** | Type | Boolean | | ------------------------------------------ | ------------------------------------- | | Default | true | | [Set in](#options) | Config file, environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_PACKAGE_REPORTING_ENABLED` | 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. **NEW_RELIC_STARTUP_DEBUG** | Type | Boolean | | ------------------------------------------ | ------------------------- | | Default | false | | [Set in](#options) | Environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_STARTUP_DEBUG` | 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](#log_level) to `debug`. **NEW_RELIC_K8S_OPERATOR_ENABLED** | Type | Boolean | | ------------------------------------------ | -------------------------------- | | Default | false | | [Set in](#options) | Environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_K8S_OPERATOR_ENABLED` | This is an informational setting used to report when the agent is injected into a Kubernetes cluster. This setting does not enable or disable this function of the agent. **NEW_RELIC_AZURE_OPERATOR_ENABLED** | Type | Boolean | | ------------------------------------------ | ---------------------------------- | | Default | false | | [Set in](#options) | Environment variable | | [Environ variable](#environment-variables) | `NEW_RELIC_AZURE_OPERATOR_ENABLED` | This is an informational setting used to report when the agent is injected into a Microsoft Azure Container App. This setting does not enable or disable this function of the agent. ## 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 [#builtin-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 `.ini` configuration file: ````ini [import-hook:MySQLdb] enabled = false ``` Or for `.toml` configuration files add the following: ```ini [tool.newrelic.import-hook.MySQLdb] enabled = false ``` ````