Python Agent API Reference

The Python Agent APIs provide facilities to support:

• Custom business transactions
• Custom exit points
• Custom data collectors

List of the APIs:

Access to the APIs

Before your app can access the Python Agent APIs, install the Python Agent using:

pip install appdynamics

Then at the top of the instrumented application add:

from appdynamics.agent import api as appd

Start and Stop Agent

init(environ=None, timeout_ms=NO_TIMEOUT)

Initializes the Python Agent.

Call this function at the very beginning of your instrumented application, preferably before any other imports and before creating any other threads.

Agent initialization occurs asynchronously. init() returns immediately if no timeout is specified but it is possible that the agent will not immediately be ready to report business transactions. In this case, the start_bt() method will return None.

This function will never raise an exception.

Returns True if the agent is properly configured, False if the agent is not properly configured.

To be properly configured the agent configuration file must contain the minimal settings and possibly some additional settings if they are required for your environment. See Configure the Agent in Install the Python Agent for the minimal settings and Python Agent Settings for the complete list.

environ: dict, optional

If specified, a dictionary of environment variables to use to override the agent's configuration, derived from the actual OS environment variables.

timeout_ms: int or None, optional

Timeout interval in milliseconds.

By default, init() returns immediately, even if the Python agent has not received its configuration from the controller. If timeout_ms is None, init() blocks until the agent is properly configured. Otherwise, init() waits for up to timeout_ms for agent to become properly configured.

shutdown(timeout_ms=None)

Shuts down the Python Agent. The agent stops reporting metrics to the Controller.

This function ends all active business transactions and waits for them to finish reporting to the controller before returning.

timeout_ms: int, optional

By default, this function waits until all pending business transactions have been reported before returning. If timeout_ms is set, this function will return after timeout_ms, regardless of whether all business transactions have been reported.

Business Transaction Management

start_bt(name, correlation_header=None)

Starts a business transaction of the specified name.

There can only be one active business transaction per thread. Attempts to start subsequent business transactions in the same thread will return None.

Returns a BtHandle on starting the transaction or None if no transaction was started.

name: str

Name of the business transaction being started. The following characters cannot be used in business transaction names:  { } [ ] | & ;

correlation_header: str, optional

If specified, a correlation header that has been generated by another AppDynamics agent and passed to this agent as a string. A correlation header provides information to enable this transaction to correlate with a transaction that is upstream to this one.

end_bt(bt_handle, exc=None)

Ends the business transaction identified by bt_handle.

bt_handle: BtHandle

Identifies the business transaction being ended. The handle is returned by start_bt().

exc: Exception, optional

If an exception occurred during processing this business transaction that you have caught with a try-except block, and you wish to report the exception as part of the business transaction, pass the exception as the exc.

add_snapshot_data(bt_handle, key, value)

Attaches custom data to transaction snapshots generated for the business transaction identified by bt_handle.

The custom data is exposed in the USER DATA tab of the transaction snapshot details in the Controller UI.

The custom data is added to the business transaction but reported only when a transaction snapshot is generated. See Transaction Snapshots for information on when transaction snapshots are generated.

bt_handle: BtHandle

Identifies the business transaction to which custom data is added. The handle is returned by start_bt().

key: bytes or unicode

Name of the data item to be reported in the snapshot.

If passed as bytes, the buffer must represent a UTF-8 encoded string.

value: any

Value of the data. 

Exit Call Management

start_exit_call(bt_handle, exit_type, display_name, identifying_properties, optional_properties=None)

Starts a custom exit call from within the specified business transaction.

There can be only one active exit call per business transaction. Attempts to start subsequent exit calls will return None.

Returns an ExitCallHandle that identifies this exit call.

bt_handle: BTHandle

Identifies the business transaction making the exit call. Handle is returned from start_bt().

exit_type: int

The type of exit call. Valid values are:

• appd.EXIT_HTTP

• appd.EXIT_DB

• appd.EXIT_CACHE 

• appd.EXIT_QUEUE

display_name:str

Name used to identify this exit call in the controller. This is the label that will be used to display the exit call in the AppDynamics UI.

identifying_properties: dict

A dictionary of name/value pairs that uniquely identify the downstream component being called.

In the Controller UI, these properties are visible in the upper right panel of the backend dashboards.

The key of the dict is the name of the property; the value is the value of the property.

operation: str, optional

A string describing the operation that is being performed, such as the URL of an HTTP request or an SQL query.

optional_properties: dict, optional

A dictionary of name/value pairs that identify additional properties for this exit call. In the Controller UI, these properties are visible in the Exit Calls and Async Activities modal in the snapshot drill-down pane.

end_exit_call(exit_call_handle, exc=None)

Ends the exit call identified by exit_call_handle.

exit_call_handle: ExitCallHandle

Identifies the exit call being ended. The handle is returned from start_exit_call().

exc: Exception

If an exception occurred during the exit call that you have caught with a try-except block, and you wish to report the exception as part of the exit call, pass the exception as the exc argument.

make_correlation_header(bt_handle, exit_call_handle)

Make a correlation header for a custom exit call.

If you are performing custom exit calls to other instrumented tiers, adding a correlation header allows continuing business transactions on the downstream tier.

It is up to you to send the header, as well as parse it at the other end and pass it to start_bt().

Returns a tuple of header name and header value, or None if correlation is disabled.

bt_handle: BtHandle

A handle identifying the business transaction.

exit_call_handle: ExitCallHandle

A handle identifying the exit call. 

Context Managers

bt(name, correlation_header=None)

Context manager for reporting some work as a business transaction. Yields a BtHandle.

If you need to start and end the transaction in different places in the code, use start_bt() and  end_bt().

exit_call(bt_handle, exit_type, display_name, identifying_properties, optional_properties=None)

Context manager for adding exit calls to a business transaction. Yields an ExitCallHandle.

If you need to start and end exit calls in different places in your code, you can use start_exit_call() and end_exit_call().

HTTP Status Codes

HTTP status codes will not cause error transactions when you use the using the Python Agent API to instrument your application, regardless of the error detection configuration.