Configuration

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:

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:

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 Config Options

The following is the complete list of instrumentation configuration options:

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:

    • always Continue existing traces, otherwise attempt to start a new one.
    • never Never continue existing traces or start new ones.

    This field is case-insensitive.

  • Default: always

  • Required: no

  • Example:

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

    [main]
    tracing_mode = never
    

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

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
    

Configuration File Example

Note

The INI file format does not support sub-sections. Instead, use a dot in the key to represent the corresponding config object hierarchy as shown in the example file below.

[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