AppDynamics Python Agent

Common errors

• java.lang.UnsatisfiedLinkError: no jzmq in java.library.path

  cause The Java-based proxy component of the AppDynamics Python Agent cannot find its required native ZMQ library, often due to an incorrect library path or missing architecture-specific binaries.
  fix Verify that the AppDynamics Python Agent (including `appdynamics-bindeps` and `appdynamics-proxysupport` packages) is correctly installed for your specific operating system and architecture. Check AppDynamics documentation for setting `java.library.path` if running the proxy separately, or ensure `pip install appdynamics` pulls the correct wheel.

• ImportError: cannot import name 'constants' from partially initialized module 'appdynamics_bindeps.zmq.backend.cython'

  cause This error often indicates an issue with the installation or loading of the `appdynamics_bindeps` package, specifically related to its Cython-compiled ZMQ backend, potentially due to a circular import or corrupted installation.
  fix Ensure a clean re-installation: `pip uninstall appdynamics appdynamics-bindeps-* appdynamics-proxysupport-* && pip install appdynamics`. Verify Python version compatibility with the installed agent.

• HTTP Error 401 Unauthorized

  cause The AppDynamics Python Agent is unable to authenticate with the Controller, typically because of an incorrect Account Name or Account Access Key.
  fix Double-check the `APPDYNAMICS_AGENT_ACCOUNT_NAME` and `APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY` environment variables or the corresponding settings in `appdynamics.cfg`. Ensure the client secret generated in the Controller UI was saved correctly.

Warnings

• breaking AppDynamics Python Agent version 26.4.0 deprecates support for Python 3.8 and has removed support for Python 3.7 and older versions.
  Fix: Upgrade your Python environment to version 3.9 or higher. Python 3.14 is supported starting from agent version 26.4.0.
• gotcha Agent startup can fail or data may not be reported to the Controller due to incorrect configuration of Controller Host, Port, Account Name, or Access Key.
  Fix: Verify that `APPDYNAMICS_CONTROLLER_HOST_NAME`, `APPDYNAMICS_CONTROLLER_PORT`, `APPDYNAMICS_AGENT_ACCOUNT_NAME`, and `APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY` environment variables are correctly set, or ensure your `appdynamics.cfg` file contains accurate values. Check agent logs for '401 Unauthorized' errors.
• gotcha Verbose logging from the AppDynamics agent and its proxy can flood stdout, obscuring application-specific logs.
  Fix: Refer to AppDynamics documentation for configuring agent logging levels, often involving modifications to `log4j2.xml` within the agent's bindeps directory. This is sometimes an unsupported workaround.
• gotcha Issues with the Java-based proxy agent failing to find native libraries (e.g., `jzmq`) can lead to agent startup failures, particularly on specific operating systems or architectures.
  Fix: Ensure that all platform-specific dependencies are correctly installed and that the Java proxy can access necessary native libraries. Consult AppDynamics support or documentation for specific troubleshooting steps for your environment, especially on non-standard architectures like Apple M1.

Install

• pip install appdynamics Install latest version

Imports

• pyagent

  pyagent run -c appdynamics.cfg -- python my_app.py

  The primary way to start a Python application with the AppDynamics agent is by wrapping the application's entry point with the `pyagent` command. Direct import is typically for API calls within the application.
• appdynamics.agent.init
  wrong:

  from appdynamics.agent import init; init()

  correct:

  import appdynamics.agent
  appdynamics.agent.init()

  While 'from ... import init' works, the recommended pattern often involves importing the 'appdynamics.agent' module as a whole for accessing other functionalities like decorators.
• appdynamics.agent.bt

  @appdynamics.agent.bt()

  Used as a decorator to define custom business transactions.

Quickstart

This quickstart demonstrates how to instrument a basic Flask application with the AppDynamics Python Agent. The agent can be initialized programmatically using `appdynamics.agent.init()` or via an `appdynamics.cfg` file and environment variables. The recommended way to run the application with the agent is by prefixing your application's startup command with `pyagent run`. Environment variables are used for agent configuration to avoid hardcoding sensitive information.

import os
from flask import Flask
import appdynamics.agent

# Initialize AppDynamics Agent (if not started via pyagent run)
# Ensure APPDYNAMICS_CONTROLLER_HOST_NAME and other env vars are set
# or use an appdynamics.cfg file.
# For a quickstart, assume pyagent run wrapper is used or environment variables.
appdynamics.agent.init(
    controller_host=os.environ.get('APPDYNAMICS_CONTROLLER_HOST_NAME', 'your-controller.saas.appdynamics.com'),
    controller_port=int(os.environ.get('APPDYNAMICS_CONTROLLER_PORT', 443)),
    controller_ssl_enabled=bool(os.environ.get('APPDYNAMICS_CONTROLLER_SSL_ENABLED', 'True').lower() == 'true'),
    account_name=os.environ.get('APPDYNAMICS_AGENT_ACCOUNT_NAME', 'customer1'),
    account_access_key=os.environ.get('APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY', 'YOUR_ACCESS_KEY'),
    application_name=os.environ.get('APPDYNAMICS_AGENT_APPLICATION_NAME', 'MyPythonApp'),
    tier_name=os.environ.get('APPDYNAMICS_AGENT_TIER_NAME', 'MyPythonTier'),
    node_name=os.environ.get('APPDYNAMICS_AGENT_NODE_NAME', 'my-python-node-1')
)

app = Flask(__name__)

@app.route('/')
@appdynamics.agent.bt(name='HelloWorld')
def hello_world():
    return 'Hello, AppDynamics World!'

@app.route('/error')
@appdynamics.agent.bt(name='ErrorRoute')
def error_route():
    raise Exception('This is a simulated error!')

if __name__ == '__main__':
    # In a real scenario, you'd typically run this with 'pyagent run'
    # For direct execution, ensure agent.init() is configured correctly.
    port = int(os.environ.get('PORT', 5000))
    app.run(debug=True, host='0.0.0.0', port=port)