This topic introduces the PHP Agent API and provide example use cases for the API.
About the PHP Agent API
The PHP Agent API enables you to:
- Define custom business transactions programmatically.
- Provide correlation headers for entry points not supported by default detection.
- Create custom exit calls to discover backends that are not automatically detected by the PHP Agent.
Include the AppDynamics API Header
You should include the appdynamics_api_header.php file in your application to ensure that it works correctly if the agent is uninstalled or temporarily disabled. This file contains empty API functions that will prevent the application from throwing errors if the agent is not present.
The appdynamics_api_header.php file is located in the PHP Agent package in the same directory as the install.sh script.
To include the header file:
- Copy appdynamics_api_header.php to where you keep the header files for the monitored application.
- Make sure that appdynamics_api_header.php is in your include path.
- Then add the following to your script:
Backend Detection with the MySQLi Driver
As noted on PHP Supported Environments, the PHP Agent does not work with PHP 5.2 applications that use the
new keyword to instantiate database backend with the MySQLi database driver. For example, AppDynamics does not detect the MySQLi backend created as follows in a PHP 5.2 application:
You can work around this by using
Parts of a Script are Business Transactions
Say you have a long PHP script application that performs a number of discrete tasks, but you want the agent to detect only one or more of them as business transactions.
In this case, enclose the code for each of those tasks within
appdynamics_end_transaction() calls. The agent will detect those blocks as separate business transactions. Otherwise, the agent detects the entire script as a single business transaction.
Handling Business Transaction Code Executing in a Loop
For a script-based CLI application that executes in a loop, perhaps fetching items from a database or remote service, you may want the agent to detect every iteration of the loop as a separate business transaction. In this case, enclose the code inside the loop within
If you do not do this, the agent will aggregate each iteration through the loop into a single business transaction.
In the following example, the agent detects a business transaction named "getItem" for every iteration.
Correlating with an Upstream Service
If you have a distributed business transaction in which a tier needs to correlate with an upstream service that is not an entry point supported by the PHP Agent, you can maintain transaction correlation using
appdynamics_continue_transaction() in the downstream tier, passing it the correlation header from the service.
You need to extract the correlation header from the service as shown in the following sample. The sample function extracts the correlation header from each message in an AMQP message queue and passes it to
After processing the message, it calls
appdynamics_end_transaction(), which ends the continuation of the transaction on the calling tier. The
appdynamics_end_transaction() call does not end the entire distributed transaction in the case where that tier makes a distributed call to another downstream tier.
If the service is not a supported entry point and you do not do this, the tier will not be correlated with the upstream transaction.
Make Socket-based HTTP Calls Example
While the API does not include built-in calls for socket-based HTTP call, you can implement monitoring of socket-based HTTP exit calls yourself as shown in the following example:
Inject a Correlation Header into an HTTP Payload Example
The next example injects a correlation header into the socket-based HTTP payload.
The next example shows how to use non-exclusive flag to start an exit call that may be wrapping other exit calls. The outer socket-HTTP call is started, then the file_get_contents() call is processed by the agent normally, and finally the outer call is finished. We also pass the exception object to report any errors. The end result is that both backends are displayed on the flowmap.