Configuration (legacy agent)

The following content pertains to configuration for the legacy AppOptics Python Agent.

Our Python Agent provides various configuration options to allow finer grain control on our monitoring.

Service Key is the only required configuration, everything else is optional.

How to Set Configuration

Options to control agent behavior can be set in the following places:

Configuration File

The agent will read settings from an INI format configuration file located via the APPOPTICS_APM_CONFIG_PYTHON environment variable. The configuration file supports these sections:

• [main] section defines top level properties
• [inst] section defines instrument object properties
• [transaction] section defines transaction name properties

System Environment Variable

The following configurations of the agent can be set via environment variables:

• Service Key: APPOPTICS_SERVICE_KEY
• Hostname Alias: APPOPTICS_HOSTNAME_ALIAS
• Logging Level: APPOPTICS_DEBUG_LEVEL
• Prepend Domain to Transaction Name: APPOPTICS_APM_PREPEND_DOMAIN_NAME

Global Property in the Code

After the appoptics_apm module has been imported, the appoptics_apm.config object can be used in your application code to set the following configuration options:

• Tracing Mode: tracing_mode
• Suppress Reporting for Sensitive Data: enable_sanitize_sql
• Warn if Deprecated Functionalities are Used: warn_deprecated

Example: To change the tracing_mode configuration in your application code, you can do the following:

import appoptics_apm
# your application code
appoptics_apm.config['tracing_mode'] = 'always'

Precedence

If the same configuration option is defined in more than one of the above places, the order of precedence is:

In-code (certain options only, as described above) > System Environment Variable > Property in config file > Default

If an invalid configuration option was provided, the value provided at the remaining lower-precedence places will be adopted, according to the above preference scheme.

How to Set Boolean Values

If a configuration option expects a boolean value, the following inputs are accepted: true, false, as well as any number, where 0 corresponds to False and everything else to True. Boolean options are case-insensitive.

Complete List of Configuration Options

The following is the complete list of instrumentation configuration options:

• Service Key
• Configuration File
• Hostname Alias
• Suppress Reporting for Sensitive Data
• Logging Level
• Tracing Mode
• Warn if Deprecated Functionalities are Used
• EC2 Metadata Timeout
• Trace Context in Logs
• Custom Transaction Filtering (Tracing Mode per Transaction)
• Enabling/Disabling Individual Instrumentation Hooks
• Prepend Domain to Transaction Name
• Report Backtraces
• Disable Agent

Service Key

Service key used to identify your account and the service being instrumented. It should be in the form of <API token>:<service name>. You can find your an API token in Organization Settings/API Tokens.

• System Environment Variable: APPOPTICS_SERVICE_KEY

• Config File: section [main], key service_key

• Required: yes

• Examples:

  Environment variable: export APPOPTICS_SERVICE_KEY="0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service"

  Config file:

  [main]
  service_key = 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service

Configuration File

The absolute path to an INI format file containing agent configuration option settings.

• System Environment Variable: APPOPTICS_APM_CONFIG_PYTHON
• Required: no
• Default: none
• Example: export APPOPTICS_APM_CONFIG_PYTHON=/path/to/agent.ini

Hostname Alias

An optional logical/readable hostname that can be used to easily identify the host.

• System Environment Variable: APPOPTICS_HOSTNAME_ALIAS

• Config File: section [main], key hostname_alias

• Default: none

• Required: no

• Examples:

  Environment variable: export APPOPTICS_HOSTNAME_ALIAS=apm-host-east

  Config file:

  [main]
  hostname_alias = apm-host-east

Suppress Reporting for Sensitive Data

Python instrumentation has the ability to sanitize sql database queries in case you don't want query parameters displayed in your account. By default this functionality is enabled, but you can use the enable_sanitize_sql flag to configure the instrumentation to enable collecting and reporting query parameters.

• Config Object: appoptics_apm.config['enable_sanitize_sql']

• Config File: section [main], key enable_sanitize_sql

• Valid Values: This field expects a boolean value

• Default: true

• Required: no

• Examples:

  In-code: appoptics_apm.config['enable_sanitize_sql'] = False

  Config file:

  [main]
  enable_sanitize_sql = 0

Logging Level

By default, the Python agent and its underlying native extension library emit debug output on stderr, which for most environments is mixed into the web application's logs. To troubleshoot the agent you can enable debug level logging and check the messages. Agent logging can also be disabled by setting the log level to -1.

• System Environment Variable: APPOPTICS_DEBUG_LEVEL

• Config File: section [main], key debug_level

• Valid Values:

  • -1: disable
  • 0: fatal
  • 1: error
  • 2: warning
  • 3: info
  • 4: debug low
  • 5: debug medium
  • 6: debug high

• Default: 2 (warning)

• Required: no

• Examples:

  Environment variable: export APPOPTICS_DEBUG_LEVEL=-1

  Config file:

  [main]
  debug_level = -1

Tracing Mode

Specify if traces should be initiated for incoming requests.

• Config File: section [main], key tracing_mode

• Valid Values:

  • enabled Continue existing traces, otherwise attempt to start a new one.
  • disabled Do not continue existing traces or start new ones.

  This field is case-insensitive.

• Default: enabled

• Required: no

• Example:

  In-code: appoptics_apm.config['tracing_mode'] = enabled

  [main]
  tracing_mode = disabled

Custom Transaction Filtering (Tracing Mode per Transaction)

Custom transaction filtering provides a finer control over the instrumentation of particular web transactions by specifying individual tracing modes on a per URL basis in order to enable or disable tracing for specific request. This is done by filtering the transaction's request URL via either a regular expression or a URL extension defined in the transaction:filter sections in the INI configuration file.

The tracing mode of a matching filter rule specified via the tracing key will take precedence over the service-level tracing mode. This means, if a request URL matches a filter rule with tracing = disabled it will no longer be monitored to report any traces or metrics. In contrast to this, if it matches a rule with tracing = enabled a request will be traced even when tracing is disabled at the service level (white-listing of requests).

The configuration of this feature is performed via sections in the INI configuration file. Each filter rule needs to be defined in its own section, where the naming of the section follows the scheme [transaction:filter:<filter_name>] and <filter_name> is an arbitrary descriptor for the specified filter. A valid filter rule must have the following keys:

• Type of filter: type=url
• Valid values: Either a valid Python regular expression or a space-separated list of URL extensions:
  • Regular expression: regexp = <regular_expression>, where <regular_expression> is the valid regular expression in raw string notation
  • URL extensions: extensions = <extension1> <extension2> ... <extensionN>
• Tracing mode for the matching URL: tracing = <tracing_mode>, where <tracing_mode> is either enabled or disabled

Rules to follow when creating the filter:

• Incomplete or invalid filter rules will be ignored and a warning will be printed in the agent logs to indicate this. This also applies to filter rules with an invalid regular expression.
• If a request URL matches multiple filter rules, the tracing mode of the first matching rule will determine if the request is sampled or not.

Example:

The following configuration can be used to disable traces and metrics for the URL http://test.com/user123 and enable traces and metrics for http://test.com/logo.jpg and http://test.com/logo.png

[transaction:filter:0]
type = url
regexp = \S+user\d{3}
tracing = disabled

[transaction:filter:1]
type = url
extensions = .jpg .png
tracing = enabled

Warn if Deprecated Functionalities are Used

Specify if warning messages will be logged when deprecated functions or fields are used.

• Config File: section [main], key warn_deprecated

• Valid Values: This field expects a boolean value

• Default: True

• Required: no

• Example:

  In-code: appoptics_apm.config['warn_deprecated'] = False

  [main]
  warn_deprecated = true

EC2 Metadata Timeout

The agent is able to detect if it is running on an AWS EC2 or OpenStack instance by querying Instance Metadata. The timeout (in milli seconds) for retrieving the metadata can be set through this configuration. It is safe to set this value to 0 for apps that do not run on EC2/OpenStack.

• Config File: section [main], key ec2_metadata_timeout

• System Environment Variable: APPOPTICS_EC2_METADATA_TIMEOUT

• Valid Values: This field expects an integer in the range of 0 and 3000

• Default: 1000

• Required: no

• Example:

  [main]
  ec2_metadata_timeout = 500

Trace Context in Logs

The agent is able to automatically inject the Trace ID into logging messages. Refer to Trace Context in Logs for more details on this feature.

• System Environment Variable: APPOPTICS_LOG_TRACE_ID

• Valid Values:

  • never do not add the Trace ID to any log messages
  • sampled only include the Trace ID for sampled requests
  • traced include the Trace ID for all traced requests
  • always always add a Trace ID. It will be ‘0000000000000000000000000000000000000000-0’ when there is no tracing context.

  This field is case-insensitive.

• Config File: section [main], key log_trace_id

• Default: never

• Required: no

• Examples:

  In-code: appoptics_apm.config['log_trace_id'] = 'sampled'

  Environment variable: export APPOPTICS_LOG_TRACE_ID=sampled

  Config file:

  [main]
  log_trace_id = sampled

Use HTTP Proxy

The agent can connect to the AppOptics backend through a proxy. The config value should either be http://<proxyHost>:<proxyPort> for a proxy server that does not require authentication, or http://<username>:<password>@<proxyHost>:<proxyPort> for a proxy server that requires Basic authentication. Note that while HTTP is the only type of connection supported between the agent and proxy (hence only http:// is allowed in the schema of the config value), the agent traffic to AppOptics is still encrypted using SSL/TLS.

It is recommended to use the agent-specific configuration. However, the agent's underlying network library will use a system-wide proxy defined in the environment variables grpc_proxy, https_proxy or http_proxy if agent-specific configuration is not set. Refer to gRPC environment variables for more information.

• System Environment Variable: APPOPTICS_PROXY

• Valid Values:

  • any string starting with http://

  This field is case-sensitive.

• Config File: section [main], key proxy
• Default: none
• Required: no

• Examples:

  Environment variable: export APPOPTICS_PROXY="http://my-proxy:3306"

  Config file:

  [main]
  proxy = "http://my-proxy:3306"

Enabling/Disabling Individual Instrumentation Hooks

To disable an individual instrumentation module, set the relevant config object option before loading the middleware into your app.

• Config File: section [main], key inst_enabled.<module-name>

  Valid module names are django_orm, httplib, memcache, pymongo, redis, sqlalchemy.

• Valid Values: This field expects a boolean value

• Default: true

• Required: no

• Example:

  [main]
  inst_enabled.pymongo = 0

Prepend Domain to Transaction Name

An optional boolean parameter to prepend domain to transaction name.

• Config Object: appoptics_apm.config['transaction']['prepend_domain_name']

• System Environment Variable: APPOPTICS_APM_PREPEND_DOMAIN_NAME

• Config File: section [transaction], key prepend_domain_name

• Valid Values: This field expects a boolean value

• Default: false

• Required: no

• Examples:

  In-code: appoptics_apm.config['transaction']['prepend_domain_name'] = True

  Environment variable: export APPOPTICS_APM_PREPEND_DOMAIN_NAME=1

  Config file:

  [transaction]
  prepend_domain_name = 1

Report Backtraces

The instrumented libraries have the ability to collect backtraces; some of them collect backtraces by default, others don't. See the list of modules in Enabling/disabling individual instrumentation hooks. Many public API methods also take backtrace parameters.

• Config File: section [inst], key <module name>.collect_backtraces

• Valid Values: This field expects a boolean value

• Default: module-dependent

• Required: no

• Example:

  [inst]
  memcache.collect_backtraces = 1

Setting Custom Transaction Name

The agent provides the option to customize the reported transaction name through the APPOPTICS_TRANSACTION_NAME environment variable. Please refer to Custom Transaction Name for more information about customize the transaction name reporting.

• System Environment Variable: APPOPTICS_TRANSACTION_NAME
• Valid Values: Any non-empty string
• Default: None
• Required: no
• Examples: Environment variable: export APPOPTICS_TRANSACTION_NAME=my_custom_transaction_name

Disable Agent

The agent provides the option to completely disable the instrumentation without explicitly removing the agent from your application. To disable the agent, simply set the APPOPTICS_AGENT_ENABLED environment variable as described below.

• System Environment Variable: APPOPTICS_AGENT_ENABLED
• Valid Values:
  • false : Do not instrument the application (i.e. do not generate any trace data)
  • true : Normal tracing operation

  This field is case-insensitive.

• Default: true
• Required: no
• Examples: Environment variable: export APPOPTICS_AGENT_ENABLED=false

Configuration File Example

[main]
service_key = 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service
hostname_alias = apm-host-east
debug_level = -1
inst_enabled.pymongo = 0

[transaction]
prepend_domain_name = 1

[inst]
django_orm.collect_backtraces = 1

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.