Python Agent Settings

You can configure operating settings for the Python Agent using a configuration file or by setting environment variables in the application environment. This page lists the Python Agent settings.

See Configure the Agent for information about the configuration file.

Note: Older version of the environment variables are backward compatible and are deprecated which will eventually be removed in future releases. You will have to update the environment variables to the latest version. The new environment variables take precedence over the deprecated variables in case both are set in an environment (e.g., APPDYNAMICS_AGENT_APPLICATION_NAME takes precedence over the deprecated APPD_APP_NAME if both are set).

[instrumentation]

Directive Description Example Default Environment Variable
enable_openai Enable or disable OperAI instrumentation. true or false false APPDYNAMICS_ENABLE_OPENAI

[agent]

Directive Description Example Default Environment Variable
app App Name MyApp Required APPDYNAMICS_AGENT_APPLICATION_NAME
tier Tier Name web-fe Required APPDYNAMICS_AGENT_TIER_NAME
node Node Name web-fe1 Required APPDYNAMICS_AGENT_NODE_NAME
dir Base directory for files related to the AppDynamics agent /mysite/appd/agent/python/ /tmp/appd/ APPDYNAMICS_AGENT_BASE_DIR
nodereuse Reuse Node Name true or false Optional APPDYNAMICS_AGENT_REUSE_NODE_NAME
nodereuseprefix Reuse Node Name Prefix My Node Name Optional APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX
uniquehostid Unique host id for the app agents Optional APPDYNAMICS_AGENT_UNIQUE_HOST_ID

[agent:proxy]

Directive Description Example Default
curve-enabled APPDYNAMICS_CURVE_ENABLED on off
curve-zap-enabled APPDYNAMICS_CURVE_ZAP_ENABLED on off
curve-public-dir APPDYNAMICS_CURVE_PUBLIC_KEY_DIR /tmp/certificates /tmp/appd/certs/public
curve-secret-dir APPDYNAMICS_CURVE_SECRET_KEY_DIR /tmp/secret-certificates /tmp/appd/certs/secret
curve-agent-public-file APPDYNAMICS_CURVE_AGENT_PUBLIC_KEY_FILE /tmp/certs/agent.key /tmp/appd/certs/public/<node_name>.key
curve-agent-secret-file APPDYNAMICS_CURVE_AGENT_SECRET_KEY_FILE /tmp/certs/agent.key_secret /tmp/appd/certs/secret/<node_name>.key_secret
curve-proxy-public-file APPDYNAMICS_CURVE_PROXY_PUBLIC_KEY_FILE /tmp/certs/proxy.key /tmp/appd/certs/public/proxy.key
curve-proxy-secret-file APPDYNAMICS_CURVE_PROXY_SECRET_KEY_FILE /tmp/certs/proxy.key_secret /tmp/appd/certs/secret/proxy.key_secret

[wsgi]

Directive Description Example Default Environment Variable
script Path to WSGI script file /var/www/acme/bookstore.py n/a APPDYNAMICS_WSGI_SCRIPT_ALIAS
callable Name of WSGI callable in script/module app application APPDYNAMICS_WSGI_CALLABLE_OBJECT
module Fully-qualified name of app module acme.bookstore:app n/a APPDYNAMICS_WSGI_MODULE

If both the script and module directives are specified, the module directive takes precedence.

The module value may be the fully-qualified name of a module, or it may be the fully-qualified name of a module followed by a colon and the name of the WSGI callable in that module. In the latter form, the module directive overrides the callable directive.

Both the long-form of the module directive and the callable directive may take either the name of a symbol, or the name of a symbol followed by an empty pair of parentheses. In the latter form, the callable is taken to be the result of calling the callable specified by the directive. This latter form can be used with Django; for example:

module = django.core.handlers.wsgi:WSGIHandler()

[log]

Directive Description Example Default Environment Variable
dir The directory to write proxy and agent logs to /var/log/appdynamics /tmp/appd/logs APPDYNAMICS_LOGS_DIR
level The level to log at one of: warning, info, or debug debug warning APPDYNAMICS_LOGGING_LEVEL
debugging On to write DEBUG level logs to stderr and log files on off APPDYNAMICS_DEBUG_LOG

[tags]

Tags are key-value pairs that are associated with your entities, such as applications, tiers, nodes, and so on. These tags act as metadata that help you find your application resources in the Controller UI. You can reduce the Mean Time To Detection (MTTD) of any entity related issues by tagging them using appropriate custom tags. To know how to import tags in Controller, see Custom Tag APIs.

You can define the custom tags during the configuration of Python Agent, see Configure the Agent. These tags are sent to the Controller UI and help filter data using tag-based filtering and tag-based columns. If you make changes to your tagging configuration, you must restart the agent.

For example:

[tags]
tag1 = value1
tag2 = value2
tag3 = value3
Note: if you have deployed Dynamic Languages Proxy, ensure to use the Dynamics Languages Proxy >=24.5.0 to define custom tags. See Docker Hub.

[controller]

This section specifies configuration for the AppDynamics Controller.

Directive Description Example Default Environment Variable
host Controller host mycontroller.example.org Required APPDYNAMICS_CONTROLLER_HOST_NAME
port Controller port 9000

8090 for HTTP on-prem

443 for HTTPS, in which case SSL must also be set

APPDYNAMICS_CONTROLLER_PORT
ssl Is SSL set be used to talk to the controller? on or off on off APPDYNAMICS_CONTROLLER_SSL_ENABLED
account AppDynamics Controller account user1 For a single-tenant controller defaults to customer1 .Otherwise required. APPDYNAMICS_AGENT_ACCOUNT_NAME
accesskey AppDynamics Controller account access key XC6v2n8m2$543 Required. To find your account name and access key, click
in the upper right corner of the AppDynamics UI, then click License.
APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
certfile Controller Certificate
Note:
  • This certfile must be the default agent keystore (found under site-packages/appdynamics_proxysupport/lib/security/cacerts) with necessary additional .pem/.crt certs embedded within it using keytool.
  • Java proxy supports only .jks and .pkcs12 formats in the keystore. If you want to include .crt format in Java proxy, run the following command:

    keytool -import -alias rootCA -file /etc/ssl/certs/ca-certificates.crt -keystore cacerts.jks -storepass changeit

/tmp/ssl/cacerts Optional APPDYNAMICS_CONTROLLER_SSL_CERTFILE

[controller:http-proxy]

If you need to use an HTTP proxy to talk to your Controller, use this section to configure the HTTP proxy.

Directive Description Example Default Environment Variable
host HTTP proxy host proxy.example.org n/a APPDYNAMICS_HTTP_PROXY_HOST
port HTTP proxy port 8090 80 APPDYNAMICS_HTTP_PROXY_PORT
user HTTP proxy user proxyuser n/a APPDYNAMICS_HTTP_PROXY_USER
password-file HTTP proxy password file /etc/http-proxy.passwd n/a APPDYNAMICS_HTTP_PROXY_PASSWORD_FILE

[proxy]

Directive Description Example Default Environment Variable
max-heap-size Max heap size for proxy 450m 300m APPDYNAMICS_MAX_HEAP_SIZE
min-heap-size Min heap size for proxy 100m 50m APPDYNAMICS_MIN_HEAP_SIZE
max-perm-size Max permanent generation size 150m 120m APPDYNAMICS_MAX_PERM_SIZE
proxy-debug-port Port number to which to attach the JAVA debugger 8092 None APPDYNAMICS_PROXY_DEBUG_PORT
start-suspended Specifies whether to debug proxy startup with a JAVA debugger. on off APPDYNAMICS_START_SUSPENDED
debug-opt Specifies the debug opt for debugging -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8090 None APPDYNAMICS_DEBUG_OPT
agent Specifies the Agent type (e.g. PYTHON_APP_AGENT, NODEJS_APP_AGENT etc) NODEJS_APP_AGENT PYTHON_AGENT APPDYNAMICS_AGENT_TYPE
tcp-comm-host Host over which the agent-proxy TCP communication takes place 127.0.0.1 Default APPDYNAMICS_TCP_COMM_HOST
tcp-comm-port Port over which initial communication requests between the agent and proxy occurs 8080 None APPDYNAMICS_TCP_COMM_PORT
tcp-reporting-port Port for reporting transport (Agent only property) 10010 None APPDYNAMICS_TCP_REPORTING_PORT
tcp-request-port Port for request and config transport (Agent only property) 10011 None APPDYNAMICS_TCP_REQUEST_PORT
tcp-port-range Port range to allocate request and report port for agents (Proxy only property) 10000-10100 None APPDYNAMICS_TCP_PORT_RANGE
use_installed_jre To use the custom JRE that is installed on your machine to run proxy. For more information, see Run the agent using your JRE. True

None

APPDYNAMICS_USE_INSTALLED_JRE
installed_jre_path Path of the installed JRE to run proxy.
Note: Python Agent first checks for installed_jre_path. If it is unset, then the Python Agent checks for JAVA_HOME.
/usr/lib/jvm/java-17-openjdk None APPDYNAMICS_INSTALLED_JRE_PATH
tls-version Supports TLS version 1.2 and 1.3. TLSv1.3 TLSv1.2 APPDYNAMICS_TLS_VERSION
Note: If PROXY_DEBUG_PORT is defined, then -agentlib:jdwp=transport=dt_socket,server=y,suspend=${START_SUSPENDED},address=${PROXY_DEBUG_PORT} is used as the debug opt. PROXY_DEBUG_PORT takes priority over DEBUG_OPT if both are specified. Also ensure that PROXY_DEBUG_PORT is not set if you want to use a self defined DEBUG_OPT.

[eum]

Directive Description Example Default Environment Variable
disable-cookie If set, the agent does not add EUM correlation data to WSGI response headers. on off APPDYNAMICS_EUM_DISABLE_COOKIE
user-agent-allowlist If specified overwrites the default allowlist for user agent added as EUM correlation data headers Use this setting to specify alternate user agents as a comma separated list. Use '*' to allow all user agents. 'iPad, Android'

'Mozilla, Opera, WebKit, Nokia'

APPDYNAMICS_EUM_USER_AGENT_ALLOWLIST

[services:snapshot]

Directive Description Example Default Environment Variable
exit-call-details-length Specifies the number of characters in the details string describing exit calls in transaction snapshots. 200 100 APPDYNAMICS_EXIT_CALL_DETAILS_LENGTH

[services:transaction-monitor]

Directive Description Example Default Environment Variable
bt-max-duration-ms Maximum duration of a business transaction in milliseconds. 60000 120000 APPDYNAMICS_BT_MAX_DURATION_MS

[services:analytics]

Directive Description Example Default Environment Variable
host Analytics Agent host

localhost APPDYNAMICS_ANALYTICS_HOSTNAME
port Analytics Agent port 9000 9090 APPDYNAMICS_ANALYTICS_PORT
ssl Set it on to enable SSL communication with the Analytics Agent on off APPDYNAMICS_ANALYTICS_SSL_ENABLED
ca-file Certificate of the CA authority that signed the certificate of Analytics Agent.
Note: The certificate format must be .pem. If there are intermediate certificate authorities, specify the path of the chain of trust in place of the root certificate authority.
/tmp/certs/ca-cert.pem optional APPDYNAMICS_ANALYTICS_CAFILE

Node Reuse for Python Agent

Reuse Node Name

To reuse node names in AppDynamics, you have to set nodereuse property to true. When you set this property to true, you do not have to supply a node name, but you do need to provide a node name prefix using nodereuseprefix .

Note: When nodereuse and a node name is used, the nodereuseprefix property is given precedence.

This property is useful for monitoring environments where there are many VMs (Virtual Machines) with short life spans. When set to true, AppDynamics reuses the node names of historical VMs for new VMs. This avoids a proliferation of differently named nodes in AppDynamics over time, particularly when the nodes are essentially identical processes that run over different times.

AppDynamics generates a node name with App, Tier, and Sequence number, and the node names are pooled. For example, the sequence numbers are reused when the nodes are purged (based on the node lifetime).

System Property: nodereuse

Type: Boolean

Default: False

Required: No

Reuse Node Name Prefix

When you configure the agent to reuse node names, use this property to specify the prefix that the Controller uses to generate node names dynamically.

System Property: nodereuseprefix

Type: String

Default: None

Required: When nodereuse=true

Note: Reuse node feature example:

With the following configuration, the Controller generates a node name with the prefix "reportGen". Node names will have suffixes -1, -2, and so on, depending on the number of nodes are running in parallel. The name of a node that is shut down and qualifies as a historical node may be reused by a new node.

nodereuse=true nodereuseprefix=reportGen

TCP Mode Configuration

By default, Python Agent and Java proxy communicate with each other using Inter-Process Communication (IPC).

However, using Transmission Control Protocol (TCP) communication is beneficial in these scenarios:

  • When you want the Java proxy and Python Agent to run over different host operating systems.
  • In containers (such as Docker and Kubernetes), where mounting the same volume for all the containers is possible but not recommended.

To enable TCP communication, set -tcp-comm-port to a valid port value while installing the agent. Also, set -tcp-port-range to a valid port range (3000-3005). The PHP Agent and Java proxy can now communicate using TCP.

The Java proxy listens to the incoming connection requests from agents over the APPDYNAMICS_TCP_COMM_PORT. The communication occurs for every agent over these two unique ports:

  • Reporting port
  • Request port

These ports can be set by either the agent or the proxy.

TCP Mode Configuration - Environment Variables

For cfg file versions of the environment variables, see Python Agent Settings.

This table lists the TCP mode configuration environment variables:

Environment Variable Name Description

APPDYNAMICS_TCP_COMM_HOST

  • For Java proxy - Defines the host over which the proxy listens to the incoming connections.

  • For Python Agent - Defines the host over which the agent tries to communicate with the proxy.

APPDYNAMICS_TCP_COMM_PORT
  • The port over which the initial communication occurs.

  • You should set it to enable TCP communication.

APPDYNAMICS_TCP_PORT_RANGE (Proxy only) The port range over which the proxy allocates ports to communicate with the agents.
APPDYNAMICS_TCP_REPORTING_PORT (Agent only)
  • The port for reporting transport between the agent and proxy.
  • If this variable is not set, then the proxy assigns a port to the agent in APPDYNAMICS_TCP_PORT_RANGE.
APPDYNAMICS_TCP_REQUEST_PORT (Agent only)
  • The port for request and configuration transport between the agent and proxy.
  • If this variable is not set, then the proxy assigns a port to the agent in APPDYNAMICS_TCP_PORT_RANGE.

Deploy Python Agent with Shared Proxy on Kubernetes

Note: Kubernetes does not support exposing a range of ports for the Proxy service. This prevents the Proxy service from allocating and using two ports for each Python Agent.

This page describes how to deploy Python Agent with shared Java proxy on Kubernetes. You can deploy the shared Java proxy using one of these methods:

  • Expose a continuous range of ports in the proxy service for the proxy-agent communication

  • Run the proxy pod as a static pod with hostNetwork: true

Note: Applications that run with Python Agent must run in pods. You can scale the Python Agent pods up and down.The proxy runs as a single, separate pod and is exposed to the Python Agents through a service. You should not scale or replicate the proxy pod.

Expose Continuous Range of Ports Manually in the Proxy Service

To deploy the shared Java proxy manually:

  1. Expose a few ports (atleast two times the number of agents) using the YAML file in Kubernetes in the proxy service.
  2. Configure the Python Agent using either of these methods:
    • Set the APPDYNAMICS_TCP_PORT_RANGE to the exposed port range to enable the proxy service to allocate ports to the Python Agent.
    • When the Python Agent selects request and report port, set the APPDYNAMICS_TCP_REQUEST_PORT and the APPDYNAMICS_TCP_REPORTING_PORT to a port in the exposed port range.

Run the Proxy Pod as a Static Pod

You can run the TCP proxy pod as a static pod which makes it use the host network. The TCP proxy is bound to the host IP address and ports.

To deploy the shared proxy by running the proxy pod:

  1. Set hostNetwork: true in the proxy pod.
  2. Set the APPDYNAMICS_TCP_COMM_HOST to the host IP address in the Python Agent pods.

Set Up CurveZMQ for Encrypted Communication

By default, the communication between Java Proxy and Python Agent is not encrypted. This page describes how to configure communication between Java Proxy and Python Agent and encrypt and authenticate using CurveZMQ. CurveZMQ is an authentication and encryption protocol for ZeroMQ.

To set up CurveZMQ, perform these steps:

  1. Generate Certificates
  2. Enable Curve Encryption
  3. Enable Curve Authentication

Generate Certificates

The Python Agent and Java Proxy automatically generate CurveZMQ certificates if you enable the Curve encryption. CurveZMQ uses certificates to encrypt and authenticate communication between Python Agent and Java Proxy. To generate the certificates manually, use this Python script:

import appdynamics.agent
import appdynamics_bindeps.zmq.auth
# This creates a <cert_name>.key and <cert_name>.key_secret in the <certs_directory>
# public_file and secret_file will be set to the public keyfile name and secret keyfile name respectively
public_file, secret_file = appdynamics_bindeps.zmq.auth.create_certificates(certs_directory, cert_name)

You must ensure that these environment variables point to the correct CurveZMQ certificates:

  • APPDYNAMICS_CURVE_AGENT_PUBLIC_KEY_FILE
  • APPDYNAMICS_CURVE_AGENT_SECRET_KEY_FILE
  • APPDYNAMICS_CURVE_PROXY_PUBLIC_KEY_FILE
  • APPDYNAMICS_CURVE_PROXY_SECRET_KEY_FILE

See the Curve Environment Variables table.

Enable Curve Encryption

To enable and encrypt the communication between Java Proxy and Python Agent, set the APPDYNAMICS_CURVE_ENABLED variable to Yes.

Enable Curve Authentication

Before enabling Curve authentication (ZAP or ZeroMQ Authentication Protocol), ensure that:

  • The Python Agent public keys (which to connect to the proxy) and the Java Proxy public keys are located in a directory.
  • Java Proxy can access the directory or the directory is located inside the Java Proxy container.
  • The APPDYNAMICS_CURVE_PUBLIC_KEY_DIR environment variable points to that directory.

To enable Curve authentication, set the APPDYNAMICS_CURVE_ZAP_ENABLED True.

The proxy then authenticates the agent if the agent's public keys are available in APPDYNAMICS_CURVE_PUBLIC_KEY_DIR

Curve Environment Variables

This table describes the available Curve environment variables.

Environment Variable Description

APPDYNAMICS_CURVE_ENABLED

Sets whether Curve is enabled.

APPDYNAMICS_CURVE_ZAP_ENABLED

Sets whether Curve ZAP (authentication) is enabled.

APPDYNAMICS_CURVE_PUBLIC_KEY_DIR

Location of the Curve public certificates.

APPDYNAMICS_CURVE_SECRET_KEY_DIR

Location of the Curve secret certificates.

APPDYNAMICS_CURVE_AGENT_PUBLIC_KEY_FILE

Curve public key file for the agent.

If the file does not exist, then the agent attempts to create it.

APPDYNAMICS_CURVE_AGENT_SECRET_KEY_FILE

Curve secret key file for the agent.

If the file does not exist, then the agent attempts to create it.

APPDYNAMICS_CURVE_PROXY_PUBLIC_KEY_FILE

Curve public key file for the proxy.

If the file does not exist, then the proxy attempts to create it.

APPDYNAMICS_CURVE_PROXY_SECRET_KEY_FILE

Curve secret key file for the proxy.

If the file does not exist, then the proxy attempts to create it.

Backend Resolution for the Python Agent

Backend resolution is the association of a backend (through identity) to node or tier.

Problem

In the traditional way of generating flow maps, the Controller UI displays the upstream tier as connected directly to the downstream tier when it makes an exit call. If a Service Proxy is present in between these tiers, the Controller is unable to identify that Service Proxy as a backend.

The inaccurate identification of the backend component causes the system to periodically change the association of the single backend with one of the potential target downstream tiers to which the Service Proxy could route. This results in an incorrect flowmap with the wrong metrics.

Solution

A Service Proxy is marked as a backend and shown on the flow map. This Service Proxy ensures that the requests from the upstream tiers to the downstream tiers are displayed accurately. The metrics are reported accurately and shown in such a way that the metrics tally between the tiers.

For example, the Controller identifies a backend named 192.168.1.9 as a Service Proxy, and that proxy routes requests to restTier21 and restTier22at the rate of 15 calls/min, the flow map distributes the metrics (calls/min) accurately between restTier21 (8 calls/min) and restTier22 (7 calls/min). The downstream metrics collectively add up to 15 calls/min, which is the same value as the upstream metric.

Once the Service Proxy is marked as backend, re-resolution stops.

How Does Backend Resolution Work for Python Agent?

The backend resolution works when the backend.detect.loadbalancer.enabledbackend.detect.urimisconfig.enabled true

After the Controller identifies a Service Proxy for the Backend Resolution, the Python Agent gets the information that a Service Proxy has been detected and the agent sends the right metric to the controller. The upstream agent version should also support the Service Proxy feature for this to work as designed. If the agent is not upgraded, then the Service Proxy is not detected and the backend is reverted as a normal backend and the Controller will function with the previous behavior.

Therefore, it is recommended that a compatible agent is used in the Backend resolution.

Enable the Service Proxy

The Service Proxy detection is enabled on the Controller by setting the backend.detect.loadbalancer.enabled backend.detect.urimisconfig.enabled Service Proxy Overview.