This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Related pages:
Your Rating:
Results:
PatheticBadOKGoodOutstanding!
42 rates

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.

List of the APIs:

The PHP AppDynamics API Header File

Include the appdynamics_api_header.php file in your instrumented application to ensure that the application works correctly if the agent is uninstalled or temporarily disabled. This file contains empty API functions that, when included, 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.

Before calling any of the APIs:

  1. Copy appdynamics_api_header.php to where you keep the header files for the monitored application.
  2. Make sure that appdynamics_api_header.php is in your include path.
  3. Then add the following to your script:
 require 'appdynamics_api_header.php';

Basic Business Transaction Management

bool appdynamics_start_transaction ($transaction_name, $entry_point_type)

Starts a custom business transaction.

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.

Return

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.

bool appdynamics_continue_transaction ($correlation_header)

Correlates a custom business transaction with an upstream service.

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

Parameter

$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() .

Return

Returns true on success, false on failure.

bool appdynamics_end_transaction ()

Ends the transaction initiated by the previous appdynamics_begin_transaction() or continued by the previous appdynamics_continue_transaction().

When paired with an appdynamics_continue_transaction(), 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 there is no previous appdynamics_begin_transaction() or appdynamics_continue_transaction() in the request/script, this function returns false, and does not change the transaction.

Exit Call Management

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

Marks the start of an exit call.

Parameters

$type

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

  • AD_EXIT_HTTP
  • AD_EXIT_DB
  • AD_EXIT_CACHE
  • AD_EXIT_RABBITMQ
  • AD_EXIT_WEBSERVICE

$label

Label for the exit call in the AppDynamics UI. Use a label under 40 characters long so that it fits neatly in the 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 advisable to specify at least "HOST, "PORT" and "VENDOR", as these properties are used by the AppDynamics DB 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.

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

Marks the end of an exit call.

Parameters

$exitCall

An object representing the exit call, to be ended returned from a previous 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.

string ADExitCall::getCorrelationHeader()

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" sample in PHP Agent API User Guide for an example of injecting the correlation header into an HTTP payload.

 

  • No labels