Related pages:

The PHP Agent APIs support custom business transaction definition and correlation. They provide a way to generate multiple business transactions in a single PHP request.

They also enable you to monitor exit calls that are not automatically detected by the PHP Agent.

API Reference Overview

The operations in the API fall into two categories, business transaction management and exit call management.

Business transaction management methods are:

Exit call management methods are:

The following sections detail the methods in the API. 

Start Transaction

Starts a custom business transaction.

Format

bool appdynamics_start_transaction($transaction_name, $entry_point_type) 

Description

If the business transaction initiated by this call is not matched by an appdynamics_end_transaction() call, the transaction terminates at the end of the request or script.

Custom business transactions cannot be nested. If you call appdynamics_start_transaction() multiple times before calling appdynamics_end_transaction(), the last appdynamics_start_transaction() is used and the previous calls are discarded.

Parameters

$transaction_name: The name used for the transaction in the controller. The following characters are not allowed in transaction names: { } [ ] | & ;

$entry_point_type: Indicates the framework or protocol of the entry point. Valid entry point types are provided as PHP extension constants, shown below:

  • AD_WEB
  • AD_MVC
  • AD_DRUPAL
  • AD_WORDPRESS
  • AD_CLI
  • AD_WEBSERVICE

Entry point types are case sensitive.

Returns

True on success, false on failure.

Failure conditions are reported in the Apache log. Reasons for failure include:

  • Invalid transaction name, contains disallowed characters 
  • Invalid entry point type
  • Agent not initialized
  • EUM headers were sent prior to the appdynamics_start_transaction() call.
  • Correlation headers were sent prior to the appdynamics_start_transaction() call.

Continue Transaction

Correlates a custom business transaction with an upstream service.

Format

bool appdynamics_continue_transaction($correlation_header, $entry_point_type) 

Description

Used by a downstream tier to correlate with a service that is not an entry point supported by the PHP Agent.

Parameters

$correlation_header: Correlation header of the upstream service with which to correlate.

It is the developer's responsibility to extract the correlation information from the service to provide the $correlation_header. See getCorrelationHeader() .

$entry_point_type: Optional parameter that indicates the framework or protocol of the entry point for the continued transaction. By default, the value is automatically set to AD_CLI when the application is running in CLI mode, and AD_WEB otherwise.

Use this parameter to indicate a different originating PHP application type for continuing transactions that cross PHP types, such as for a transaction originating at a PHP web application that crosses to a PHP CLI leg of the transaction. 

Valid entry point types are provided as PHP extension constants:

  • AD_WEB
  • AD_MVC
  • AD_DRUPAL
  • AD_WORDPRESS
  • AD_CLI
  • AD_WEBSERVICE

Entry point types are case sensitive.

Return

Returns true on success, false on failure.

End Transaction

Ends a transaction created by a previous call to appdynamics_begin_transaction() or continued by appdynamics_continue_transaction().

Format

bool appdynamics_end_transaction() 

Description

When paired with an appdynamics_continue_transaction() call, this call ends the transaction on the tier being continued but does not end any subsequent calls downstream from that tier that are part of the distributed transaction.

If the business transaction is invalid or if there were no previous appdynamics_begin_transaction() or appdynamics_continue_transaction() calls in the request/script, this function returns false and throws a warning message that is captured by the application and reported as an exception.

Your application is recommended to wrap appdynamics_begin_transaction() and handle possible exceptions so that they are not logged as application exceptions.  

Begin Exit Call

Marks the start of an exit call.

Format

ADExitCall appdynamics_begin_exit_call($type, $label, $properties, $exclusive=true) 

Parameters

$type: The type of exit call. Must be one of the following:

  • AD_EXIT_HTTP
  • AD_EXIT_DB
  • AD_EXIT_CACHE
  • AD_EXIT_RABBITMQ
  • AD_EXIT_WEBSERVICE

$label

Label for the exit call in the Controller UI. Use a label under 40 characters long so that it fits in flowmaps.

$properties

An associative array of identifying properties—name/value pairs—for the exit call. Property names and values must be strings.

Each exit call type has its own properties. There is no validation of property names, but each exit type has traditionally used the names listed below.

type




AD_EXIT_HTTP"HOST""PORT""URL""QUERY_STRING"
AD_EXIT_DB"HOST""PORT""DATABASE""VENDOR""URL"
AD_EXIT_CACHE"SERVER POOL""VENDOR"


AD_EXIT_RABBITMQ"HOST""PORT""EXCHANGE""ROUTING KEY"
AD_EXIT_WEBSERVICE"SERVICE""OPERATION""SOAP ACTION""VENDOR""URL"

For AD_EXIT_DB exit call type it is advisable to specify at least HOST, PORT and VENDOR, as these properties are used by the Splunk AppDynamicsDB integration. The VENDOR property for AD_EXIT_DB backends should be one of the following:

  • MYSQL
  • POSTGRESQL
  • SQLSERVER
  • ORACLE
  • SYBASE
  • DB2

$exclusive: Boolean that Indicates whether the exit call is exclusive.

Only one exclusive exit call can be in progress at a time. For example, if this API is used to start an HTTP exit call and there is a mysql_connect() call immediately following it, the MySQL call will not be detected while the HTTP call is in progress. An exclusive exit call has to be explicitly ended before subsequent exit calls can be detected or initiated.

Exit calls are exclusive by default, but you can make them non-exclusive by setting this parameter to false.

See the last code sample in the 'Scenario: Application makes socket-based HTTP calls' in PHP Agent API User Guide for an example of how setting this flag to false can be used to support nested exit calls.

Return

Returns an instance of the ADExitCall class on success, NULL on error.

End Exit Call

Marks the end of an exit call.

Format

void appdynamics_end_exit_call(ADExitCall $exitCall, $exception = null) 

Parameters

$exitCall: An object representing the exit call to be ended, and returned from its appdynamics_begin_exit_call().

$exception: An exception object—either Exception class or one derived from it—specifying if an error occurred during the exit call.

Get Correlation Header

Returns the correlation header for this exit call. The returned correlation header can be passed to appdynamics_continue_transaction to correlate with this exit call.

See also the 'Scenario: Application makes socket-based HTTP calls" 'ample in PHP Agent API User Guide for an example of injecting the correlation header into an HTTP payload.

Format

string ADExitCall::getCorrelationHeader() 

Set SQL Query Info

Sets the SQL query for this exit custom call.

Format

void ADExitCall::setSQLQueryInfo($querystring, $boundparams) 

Parameters

$querystring: String containing the SQL query. Use question marks to indicate the bound parameters.

$boundparams: Optional comma-separated array of bound parameters as quoted strings.

Example

$exitCall->setSQLQueryInfo("SELECT * FROM mytable where id1=? and id2=?;", ('Susie', '12345'));
CODE