Instrument PHP Applications Appdynamics Pro Documentation Version 4.0.X

Instrument PHP Applications AppDynamics Pro Documentation Version 4.0.x

Page 1 Instrument PHP Applications ...... 3 Install the PHP Agent ...... 8 Install the PHP Agent using a Shell Script ...... 11 Install the PHP Agent using RPM ...... 15 Upgrade the PHP Agent ...... 19 Uninstall the PHP Agent ...... 20 Resolve Installation Issues for PHP ...... 21 Special Considerations for PHP on Mac OSX ...... 23 PHP Supported Environments ...... 23 AppDynamics for PHP Architecture ...... 27 Controller Information in the PHP Configuration Files ...... 28 Special Procedures for PHP CLI ...... 31 Set Up a Multi-Tenant Proxy for PHP Agents ...... 33 Run the Proxy Daemon Manually for PHP Agents ...... 34 Configure Manual Startup of the runProxy Script for PHP Agents ...... 34 Execute the runProxy Script Manually ...... 35

Page 2 Instrument PHP Applications

On this page: Before You Begin Instrument Your PHP Application Related pages: AppDynamics Essentials Upgrade the PHP Agent Uninstall the PHP Agent Install the PHP Agent PHP Supported Environments AppDynamics for PHP Architecture Resolve Installation Issues for PHP Watch the video: Quick Install: App Agent for PHP

Use these instructions to install the PHP Agent using the Agent Download Wizard in the Controller. This installer configures your agents with the values that you supply in the wizard. This is the simplest way to install the agent. If you downloaded the agent from the AppDynamics download zone, see Install the PHP Agent an d its subpages to instrument your application manually, using either a shell script or an RPM installer. If you are instrumenting an application running on Mac OSX, you need to instrument it manually using the shell script. If you are instrumenting a PHP CLI script, see Special Procedures for PHP CLI.

Before You Begin

1. Confirm you have access to a controller, the web application where you monitor your application performance: If you use a SaaS controller, AppDynamics sent you the controller host in your Welcome Email. If you use the on-premise controller, you supplied the host and port at install time. 2. Verify you have root access to run the install. 3. Verify support for your environment at PHP Supported Environments.

Instrument Your PHP Application

There are four steps to instrument your PHP application and begin monitoring:

Copyright © AppDynamics 2012-2015 Page 3 1. Download: Use the Agent Download Wizard to configure and download the agent. 2. Install: Unzip the agent on your server and run the install script. 3. Apply Load: Restart your web server and application and apply load to activate instrumentation. 4. View Your Application: Log on to the Controller to monitor application performance.

Download the PHP Agent

The Agent Download Wizard walks you through configuration steps and helps you download the agent. Show me the Download Agent Wizard steps... 1. Log on to the Controller and click the Agent Download Wizard tab. The download wizard configures the agent with information to connect to the Controller.

2. Click PHP, then click Next.

3. Click to Select Operating System and 32-bit or 64-bit bit System, then click Next.

4. The Controller Location URL window displays the connection info for the Controller. Click Next. Click SSL to enable SSL encryption between the agent and the Controller. Enter the SSL port. For AppDynamics SaaS, the SSL port is 443.

5. Enter an application name or, click an existing application name if one exists. Then click Next. For new users, it is OK to use the default "MyApp". You can change it later when know more about how you want to organize your applications in AppDynamics.

6. Enter a tier name. Then click Next. For new users, it is OK to use the default "MyTier". You can change it later when know more about how you want to organize your applications in AppDynamics.

7. Click Click here to Download to download the App Agent for PHP.

Now you're ready to install the agent on your app server.

Install the PHP Agent on your app server

After you download the agent, install it to your app server. The final window of the Agent Download Wizard includes brief instructions for installing the agent. 1. Log on as an administrator to the machine running your PHP application. Unzip the agent zip file into a directory that can be accessed the same user that runs Apache or php-fpm. For example, for a 64 bit agent on Linux:

unzip appdynamics-php-agent-x64-linux-tar-self-service.zip -d /opt/appdynamics/appagent

2. Run the installer script.

sudo bash runme.sh

By default the PHP agent installer uses the PHP directory specified in your environment's PATH variable to determine where to install the agent. If you are using a different PHP installation not specified in the PATH environment variable, follow the instructions below to run the installer with custom options instead of using the Agent Download Wizard. Install the PHP Agent using a Shell Script Install the PHP Agent using RPM

Now you're ready to restart your application and put some load on it.

Apply load to your application

1. Restart your web server. 2. Apply load to your application.

The agent instruments the application code and reports metrics back to the Controller. You're ready to begin monitoring.

View your application

From here, you can install more agents or you can begin monitoring your application. The links below will help you get started:

Install the PHP Agent

On this page: Prerequisites for Agent Installation Installing the PHP Agent Files Added to Your Installation Installing the Standalone Machine Agent on a PHP Node Related pages: Install the PHP Agent using a Shell Script Install the PHP Agent using RPM Special Procedures for PHP CLI Special Considerations for PHP on Mac OSX Upgrade the PHP Agent Resolve Installation Issues for PHP

You can install the PHP Agent using either a shell script (install.sh) or the RPM Package Manager (RPM). These instructions assume that you are installing the AppDynamics PHP Agent in a standard PHP environment, specifically: a single PHP installation running on the Linux or OSX machine PHP running in a single Apache or FPM pool

Copyright © AppDynamics 2012-2015 Page 8 standard packages have been used to install PHP, Apache and/or PHP-FPM no customizations have been made to your PHP configuration It is possible that the installer will work if one or more of these assumptions is violated. This installation results in an AppDynamics model of your application consisting of one application, one tier, and one node.

Prerequisites for Agent Installation

1. Confirm that you have a supported environment installed on the server and that the server is configured correctly to run PHP scripts. How you do this depends on your PHP environment. For example, in our Ubuntu 12+ web server running Apache we use:

sudo apt-get install apache2 php5 php5-cli php -i

In our CentOS 5+ web server running Apache mod_ssl we use:

sudo yum install httpd mod_ssl php53 php53-cli php -i

2. Confirm that your PHP was not built with the enable-debug configure option. The PHP Agent is incompatible with PHP builds that were compiled with debugging symbols. To determine whether your PHP was built with debugging symbols you can use the following command:

php -i | grep -e "Debug Build"

The response should be:

Debug Build => no

3. Install the PHP application that you want to monitor, if it is not already installed. 4. Download the the appropriate PHP agent installer for your platform. On RedHat and CentOS: PHP Agent - 32 bit RPM PHP Agent - 64 bit RPM On all other Linux: PHP Agent - 32 bit Linux

Copyright © AppDynamics 2012-2015 Page 9 PHP Agent - 64 bit Linux On Mac OSX: PHP Agent - 64 bit OSX If you use an on-premise Controller, download the latest version of the AppDynamics Controller. The download site is http://download.appdynamics.com. 5. Be prepared to provide the following information to the installation script: controller host and controller port: These are the host name or IP address and the port number of the AppDynamics controller that the agent connects to. SaaS customers receive this information from AppDynamics. On-premise customers establish these settings when they install the controller. AppDynamics application name: This is the name that you assign to the business application you will monitor with AppDynamics. AppDynamics tier name: This is the name that you assign to the tier you will monitor with AppDynamics. AppDynamics node name: This is the name of the basic unit of processing that the agent monitors. If you have an on-premise AppDynamics controller running in multi-tenant mode or if you are using the AppDynamics SaaS Controller, you will also need to provide the following, which were included in your Welcome email from AppDynamics: AppDynamics account name AppDynamics account key 6. Stop the Apache server.

Tip: Do not install the PHP Agent along with other non-AppDynamics Application Performance Management (APM) tools, especially in a production environment. The PHP agent installation may fail if there are other APM products installed in the same managed environment.

Installing the PHP Agent

To use install.sh, see Install the PHP Agent using a Shell Script. Use install.sh to install on OSX as well as LInux. To use RPM, see Install the PHP Agent using RPM. To instrument PHP CLI, see also Special Procedures for PHP CLI. To instrument an application on OSX, see Special Considerations for PHP on Mac OSX.

Files Added to Your Installation

PHP configuration files For AppDynamics, the PHP configuration files of interest are the php.ini and appdynamics_agent.ini fragment. AppDynamics settings can be found in either .ini file, depending

Copyright © AppDynamics 2012-2015 Page 10 on the operating system under which your PHP is installed. The PHP agent installer adds the appdynamics_agent.ini file to the directory that contains your php.ini file. You can find this directory using the following command:

php -i | grep -e "Additional .ini files parsed"

If the installer is not able to determine the directory where the ini fragments for your PHP deployment live, it displays the required AppDynamics ini fragment and prompts you to copy and paste it into your main php.ini file. Also see http://php.net/manual/en/configuration.file.php for information about possible locations.

.so files The installer also installs the appdynamics_agent.so file in your PHP extensions directory. You can find this directory using the following command:

php -i | grep extension_dir

Logs There is an agent log and a proxy log for each application. The agent log is located at $/logs/agent.log. The log contains the transactions that the agent processes and then sends to the proxy. The default pattern for agent log naming is: agent.log: the current log agent.log.1: most recent log agent.log.2: second most recent log agent.log.3: third most recent log agent.log.4: fourth most recent log agent.log.5: fifth recent log The proxy log is located $/logs/proxy_$date.log. This log contains the transactions that the proxy accepts from the agent and then sends to the Controller.

Installing the Standalone Machine Agent on a PHP Node

If you install the Standalone Machine Agent on the machine hosting the instrumented PHP node and you specify the tier and node name in the Standalone Machine Agent controller-info.xml file, the PHP Agent will fail to register. To avoid this problem: Install the PHP Agent before you install the Standalone Machine Agent. Do not specify the tier and node in the Standalone Machine Agent controller-info.xml, where it is optional. The Standalone Machine Agent will pick up the tier and node from the app agent configuration.

On this page: Install the PHP Agent using install.sh Installation Samples Uninstall the PHP Agent using install.sh Related pages: Install the PHP Agent Install the PHP Agent using RPM Upgrade the PHP Agent Resolve Installation Issues for PHP Special Considerations for PHP on Mac OSX Special Procedures for PHP CLI Watch the video: PHP Agent Installation and Manual Configuration

Install the PHP Agent using install.sh 1. Untar the tarball containing the agent into a directory. The directory should be owned by the same user that runs Apache or php-fpm. AppDynamics recommends /opt/appdynamics/php-agent. This documentation refers to this directory as the php_agent_install directory or $.

cd $ tar -xvjf appdynamics-php-agent-x64-linux.tar.bz2

2. Set the following permissions. php - Make every directory that leads to the PHP agent logs directory readable and executable by all and writable by the directory owner.

chmod -R 755

logs - Make the logs subdirectory readable/writable/executable by all.

chmod 777 /logs

If 777 access on the logs directory is too permissive for your organization's security policies, this setting is not strictly necessary as long as that directory is owned by the apache/php/proxy user.

3. Run the installation script using the following syntax. Each PHP instance is a single node.

$/install.sh [-s] [-a=@] [--http-proxy-host=] [--http-proxy-port=] [--enable-cli-long-running=true|false] [-e ] [-i ] [-p ] [-v ]

-s option: You can optionally specify the -s option if you want the agent to use SSL (HTTPS) to connect to the controller. In this case, set the Controller port to the HTTPS port of the controller. account_key and_account name: The AppDynamics account_key and account_name are required for a controller running in multi-tenant mode. These values are provided in your welcome email from AppDynamics. http-proxy-host: http-proxy-port: http-proxy-user: http-proxy-password-file: Set the http-proxy-host and http-proxy-port to route data to the controller through a proxy server. The http-proxy-host is the host name or IP address of the proxy server. The http-proxy-port is the proxy server's HTTP or HTTPS port, whichever you are using. If you set the http-proxy-host you must set the http-proxy-port as well. Use the http-proxy-user and http-proxy-password-file if the proxy server requires credentials. -e option: extensions directory for the appdynamics_agent.so file; needed only when the default PHP CLI binary cannot be determined. -i option: ini directory for the appdynamics_agent.ini file; needed only when the default PHP CLI binary cannot be determined. -v option: version of PHP that you are instrumenting. Valid formats are version numbers to one or two decimal positions; e.g. "5.4" and "5.4.21" are both valid. Needed only when the default PHP CLI binary cannot be determined or there is no PHP CLI binary. -p option: path to the PHP binary enable-cli-long-running: Set to true to defend PHP in long-running CLI applications. Defaults to false. See Long-Running CLI Applications with the Suhosin Patch in Special Procedures for PHP CLI. By default the installer uses the PHP CLI binary to determine where to install the PHP Agent. This works for most PHP environments.If you are instrumenting a different PHP, use the -e option to indicate the correct extensions directory for the appdynamics_agent.so file and the -i option for the

Copyright © AppDynamics 2012-2015 Page 13 correct ini directory for the appdynamics_agent.ini file. If you are installing in an environment where there is no PHP CLI binary available, you must use the -v option as well as the -e, and -i op tions. If all options are used, the -e, -i and -v options have precedence over the -p option.

Installing as root On some systems, such as Ubuntu, it is necessary to perform the installation as root. Verify whether you need to install as root in your environment. You can use sudo to do this. See http://linux.about.com/od/commands/l/blcmdl8_sudo.htm.

4. Restart the web server, unless you are installing an agent to monitor PHP-CLI only. If you are running multiple installations of Apache on the same machine, run install.sh once for each Apache, each time with the appropriate node, php_ini dir and php_ext dir options. In this case see also Run the PHP Proxy Daemon Manually. See Files Added to Your Installation for information about the default installation directories. If your installation failed, see Resolve Installation Issues for PHP.

Installation Samples Here is a sample command to install the agent on a single-tenant controller:

install.sh controller 8090 myApp myTier myNode

Here is a sample command to install the agent using SSL on a multi-tenant on-premise controller:

install.sh -s -a=PHPCust1000@9456d222-66e2-54d2-f8aabbc66c4e controller1.appdynamics.com 8818 myApp myTier myNode

Here is a sample command to route traffic to the controller through a proxy server.

install.sh --http-proxy-host=myproxyhost --http-proxy-port=8099 controller 8090 myApp myTier myNode

Tip: The installer overwrites your existing settings in the AppDynamics PHP Agent ini fragment, found in appdynamics-php-agent/php/conf/appdyanmics_agent.ini. If you configured properties in that file, you need to update them every time you run the installer. It does not overwrite the php.ini file.

If the startup does not succeed, file a support ticket.

Uninstall the PHP Agent using install.sh

Copyright © AppDynamics 2012-2015 Page 14 If you installed the agent using install.sh, use install.sh to uninstall it. To uninstall: 1. Shut down the web server. 2. From the PHP agent install directory, run the PHP installer with the -u option:

install.sh -u

3. Delete the directory.

Install the PHP Agent using RPM

On this page: Procedure for Installing the PHP Agent Using RPM RPM Environment Variables Run the RPM Package RPM Log File Uninstall the Agent for PHP using RPM Related pages: Install the PHP Agent Install the PHP Agent using a Shell Script Run the Proxy Daemon Manually for PHP Agents Resolve Installation Issues for PHP

The RPM package lets you automate the installation of the PHP Agent. RPM is supported on RHEL and CentOS. You must run the package as root. RPM installs one agent at a time. Installation of multiple agents is not supported.

Procedure for Installing the PHP Agent Using RPM 1. Download the RPM package from the AppDynamics download site. 2. Set the environment variables. RPM gets its installation information from the environment, not from the command-line. See RPM Environment Variables. 3. Run the RPM package. See Run the RPM Package. 4. If there are errors, examine the log file. See RPM Log File. See also Resolve Installation Issues for PHP 5. Restart Apache, unless you are installing an agent to monitor PHP CLI only.

RPM Environment Variables

Copyright © AppDynamics 2012-2015 Page 15 The RPM installer attempts to determine the location of your PHP installation based on the PATH environment variable. It uses the first PHP installation that it encounters in the PATH to configure the installer. If you have installed PHP in a non-standard location, you must provide the directory of your PHP binary in APPD_PHP_PATH. You can route data to the controller through a proxy server, but proxy servers that require a username and password are not supported. The installer uses the default values for the other variables if you do not set them. Set the APPD environment variables at the operating system level. You may want to use a script to set the environment variables.

Environment Variable Description Default

APPD_PHP_PATH Directory containing the PHP binary None

APPD_PHP_CONFIGURATION_DIR INI directory in which to install the Directory appdynamics_agent.ini file. Takes containing precedence over the your php.ini APPD_PHP_PATH setting. file. See inf ormation on files added to your installation in Install the PHP Agent.

APPD_PHP_EXTENSION_DIR Extensions directory in which to Your PHP install the appdynamics_agent.so file. extensions Takes precedence over the directory. S APPD_PHP_PATH setting. ee informat ion on files added to your installation in Install the PHP Agent.

Copyright © AppDynamics 2012-2015 Page 16 APPD_PHP_VERSION Version of PHP that you are Version instrumenting. Valid formats are used by version numbers to one or two your PHP decimal positions; e.g. "5.4" and CLI binary "5.4.21" are both valid. Takes precedence over the APPD_PHP_PATH setting.

APPD_CONF_CONTROLLER_HOST Controller host name "localhost"

APPD_CONF_CONTROLLER_PORT Controller port 8080

APPD_CONF_APP Application name "MyApp"

APPD_CONF_TIER Tier name Hostname of the machine running the script (same as the node name)

APPD_CONF_NODE Node name Hostname of the machine running the script

APPD_CONF_ACCOUNT_NAME Account name None

APPD_CONF_ACCESS_KEY Account key None

APPD_CONF_SSL_ENABLED true to enable SSL communication false with the controller, false otherwise

APPD_CONF_HTTP_PROXY_HOST Hostname or IP address of the http None proxy server

APPD_CONF_HTTP_PROXY_PORT HTTP or HTTPS port of the http None proxy server; must be set if APPD_CONF_HTTP_PROXY_HOST is set

APPD_CONF_HTTP_PROXY_PASSWORD_FILE password on the http proxy server None

APPD_PROXY_CTRL_DIR initial control communication None directory between the agent and the Java proxy

APPD_CONF_CLI_LONG_RUNNING_ENABLED Defends PHP in long-running CLI False applications

Run the RPM Package To run the installer package:

rpm -i

If you have multiple installations of PHP on one machine, run the package once for each PHP installation, each time with the appropriate APPD_PHP_PATH and APPD_CONF_NODE settings.

Using sudo to install If you are using sudo to pass the environment variables to the installation script you can use:

sudo APPD_PHP_PATH=/opt/php rpm -i

APPD_PHP_PATH=/opt/php sudo -E rpm -i

Updating the Installation Any changes that you made to the configuration files are preserved when you re-run the installer. RPM saves your original settings and appdynamics_agent_log4cxx.xml files with the settings from the previous installation.

RPM Log File If the installation succeeds, no log file is generated. If there were errors, a message displays the location of the log file generated in the /tmp directory.

Uninstall the Agent for PHP using RPM If you installed the agent using RPM, use RPM to uninstall it. To uninstall:

rpm -e appdynamics-php-agent-

To find the version of the package that you installed you can use:

rpm -qa | grep appdynamics-php-agent

The existing configurations are saved in a tarball in /tmp, the location of which will be displayed after the uninstall completes.

Upgrade the PHP Agent

On this page: Upgrade the PHP Agent Related pages: Install the PHP Agent Uninstall the PHP Agent Resolve Installation Issues for PHP

If you are upgrading both the Controller and agents, first upgrade the Controller and then upgrade the agents. Also, if you are upgrading multiple agents in your monitored environment, upgrade the agents for the tiers on which business transactions originate last. For more information about this requirement, along with Controller and agent compatibility information, see Agent - Controller Compatibility Matrix.

Upgrade the PHP Agent 1. Shut down the web server or php-fpm. 2. Copy the controller host, controller port, application name, tier name and node name property values from your ini file. If you are running in multi-tenant mode, also copy the account name and account access key property values. 3. Recursively remove or rename the old AppDynamics PHP installation directory. 4. Download and extract the most recent agent tarball. 5. Run the installation script, using the values that you copied from controller-info.xml for the parameters.

If you are using the agent to monitor PHP CLI without running a web server, you can omit steps 1 and 6.

Uninstall the PHP Agent

On this page: Uninstall the PHP Agent Agents Installed with the Agent Download Wizard Related pages: Install the PHP Agent using a Shell Script Install the PHP Agent using RPM

Uninstall the PHP Agent 1. Shut down Apache. If you are using the agent to monitor PHP CLI without running a web server, you can omit step 1. 2. Do one of the following: If the agent was installed with the shell script installer, enter:

install.sh -u

Then delete the directory. If the agent was installed with the RPM installer, enter:

rpm -e appdynamics-php-agent-

where is the package you installed. You can find the version using:

rpm -qa | grep appdynamics-php-agent

Agents Installed with the Agent Download Wizard If your agent was downloaded and installed using the Agent Download Wizard, it might not be obvious which installer was used. The name of the actual installer called by the runme.sh command in the wizard is hidden from the user. Normally, if RHEL and CentOS was selected in the wizard, the RPM installer was used. If All

Copyright © AppDynamics 2012-2015 Page 20 Other LInux OS was selected in the wizard, the shell script installer was used. So use the appropriate uninstall command based on the command that was used to install the agent.. If you do not know which selection was checked in the wizard, run

rpm -qa | grep appdynamics-php-agent

If this does not list any results, assume that the shell script installer was used to install the agent.

Resolve Installation Issues for PHP

On this page: Determine whether the installer installed in the correct directory. Verify that the AppDynamics settings block exists in the configuration file. Confirm that the correct permissions are set. Confirm that the proxy is running. Check the Configuration Properties.

If you installed the PHP Agent, started up your instrumented server, and your application is receiving traffic but no metrics are being reported, try these suggestions for investigating installation issues.

Determine whether the installer installed in the correct directory. It is possible that the agent was installed in the wrong directory. Verify the location of your PHP installation. Verify the location of your PHP by running phpinfo. See http://us1.php.net/phpinfo. Then check where the installer actually installed the agent files. The appdynamics_agent.ini file should be in the same directory that contains the php.ini file for your PHP installation. The appdynamics_agent.so file should be in the extensions directory for your PHP installation. See Files Added to Your Installation for information about how to locate these directories. In addition, on Linux you can use pstree to locate the agent. Pstree displays the AppDynamics agent running under Apache if the agent is installed properly. See http://freecode.com/projects/pstr ee. If the agent files are not in the correct directories, re-install the agent with the -i and -e options.

Re-install the agent If the app agent is not installed in the right directory, re-install the agent using the install.sh installer with the -i and -e options. Use the -i to install the appdynamics_agent.ini file in the same directory as your php.ini file and the -e to install the appdynamics_agent.so file in the same directory as

Copyright © AppDynamics 2012-2015 Page 21 your PHP extensions directory. See Install the PHP Agent using a Shell Script. If you initially installed the agent using the RPM installer, you can find the shell script installer at /u sr/lib/appdynamics-php5/install.sh.

Check error messages in the installation output When you reinstall, examine carefully any error messages in the output of the install script, especially those that direct you to copy some settings into php.ini. If necessary copy those settings into the php.ini file. See Controller Information in the PHP Configuration Files for information on common settings that may be missing.

Verify that the AppDynamics settings block exists in the configuration file. Run this command:

php -i | less

and examine the output. You should see should be an appdynamics_agent.ini and a configuration block listing appdynamics ini values.

Confirm that the correct permissions are set. Check that the following permissions are set:

chown -R : chmod -R 755 chmod 777 /logs

Confirm that the proxy is running. The Java proxy is the part of the agent that communicates with the Controller. If the agent is installed in the right place, confirm that the Java proxy is running. 1. From the command line enter 'ps aux | grep java'. 2. Inspect the list. You should see output similar to the following if the proxy is running:

/usr/lib/appdynamics-php5/proxy/jre/bin/java -server -Xmx120m -classpath /usr/lib/appdynamics-php5/proxy/conf/logging/*:/usr/lib/appdynamics- php5/proxy/lib/*:/usr/lib/appdynamics-php5/proxy/lib/tp/*:/usr/lib/a ppdynamics-php5/proxy/* -Djava.library.path=/usr/lib/appdynamics-php5/proxy/lib/tp -Dappdynamics.agent.logs.dir=/usr/lib/appdynamics-php5/logs -Dcomm=/tmp/ad-siJ4rp -DagentType=PHP_APP_AGENT -Dappdynamics.agent.runtime.dir=/usr/lib/appdynamics-php5/proxy com.appdynamics.ee.agent.proxy.kernel.Proxy

Copyright © AppDynamics 2012-2015 Page 22 If you are instrumenting a PHP CLI script, you need to start the proxy manually. You may also need to start the proxy manually if you have special requirements for running Java processes. See Run the Proxy Daemon Manually for PHP Agents .

Check the Configuration Properties. It is possible that the properties that the proxy uses to communicate with the Controller were not set properly. You can modify these properties in the php.ini or appdynamics_agent.ini file, wherever they are set in your environment. See Controller Information in the PHP Configuration Files.

Special Considerations for PHP on Mac OSX

If you are installing the PHP Agent on OSX, set max_execution_time to 0 in the appdynamics_agent.ini file If you have another INI file that is loaded after appdynamics_agent.ini, and sets max_execution time to a non-zero value, set max_execution_time to 0 in the php.ini file instead.

PHP Supported Environments

On this page: PHP Versions PHP Web Servers Operating Systems Architecture PHP Frameworks and Protocols Transaction Naming Exit Points Opcode Cache Compatibility Correlation with AppDynamics for Databases Related pages: Configure Transaction Detection for PHP

Supported Platform Matrix for the PHP Agent

PHP Versions

Supported PHP Comment Versions

5.2 Does not detect mysqli backends instantiated with the new keyword. See note below.

5.4

5.5

5.6

PHP 5.2 Note

The PHP Agent is incompatible with PHP 5.2 applications that use the new keyword to instantiate a mysqli backend. For example, AppDynamics will not detect the mysqli backend created by a PHP 5.2 application that uses an expression like this:

// Does not get detected. $db = new mysqli("localhost", "user", "password", "database");

The workaround is to change such expressions to use mysqli_connect():

$db = mysqli_connect("localhost", "user", "password", "database");

PHP ZTS Note The PHP Agent is incompatible with the mode of PHP called Zend Thread Safety (ZTS). If you are using ZTS, AppDynamics suggests that you review your dependencies on ZTS to confirm that you actually need it, and if you do not, to switch to non-ZTS mode. If you have a legacy infrastructure which requires ZTS or an app library that needs it, such as pthreads, contact AppDynamics Support.

PHP Web Servers

Supported Web Server Version Comment

Apache 2.2 in prefork mode using mod_php

Apache 2.4 in prefork mode using mod_php

Apache 2.2 in worker MPM mode using mod_fastcgi with php-fpm or mod_fcgid with php-cgi

Apache 2.4 2.4 in worker MPM mode using mod_fastcgi with php-fpm or mod_fcgid with php-cgi

Any Web Server compatible with php-fpm

Supported Operating System Version Comment

RHEL/CentOS 5.8+ SELinux is disabled.

Ubuntu 10+ SELinux is disabled.

Debian 6 SELinux is disabled.

OSX Mavericks

Architecture

Supported Architecture

32-bit

64-bit

PHP Frameworks and Protocols

Framework/Protocol Version Entry Point Type

Drupal 7 Drupal

WordPress 3.4 & 3.5 Wordpress

Zend 1 & 2 PHP MVC

CodeIgniter 2.x PHP MVC

Magento 1.5, 1.6 & 1.7 PHP MVC

Symfony 1 & 2 PHP MVC

CakePHP 2.x PHP MVC

HTTP PHP Web

CLI PHP CLI

If your PHP framework is not listed here, the agent detects your entry points as PHP Web and names the business transactions based on the first two segments of the URI (the default naming convention for PHP Web transactions). So it is still possible to monitor applications on "unsupported" frameworks. You can modify the naming convention used for PHP Web Entry points. See Configure PHP Web Transaction Naming.

Transaction Naming

Framework/Environment Default Transaction Naming

Drupal page callback name

Wordpress template name

PHP MVC Frameworks controller:action

PHP Modular MVC module:controller:action Frameworks

PHP Web URI

PHP Web Service service name.operation name

PHP CLI last two segments of the script's directory path plus the name of the script

Virtual host prefixing is available for all supported entry point types except PHP CLI.

Exit Points

Supported HTTP Exit Points

curl/curl-multi

drupal_http_request()

fopen(), file_get_contents()

NuSOAP 0.9.5

Supported Database Exit Points

MySQL old native driver

MySQLi Extension

OCI8

PDO

Supported Cache Exit Points Version

Memcache

Memcached

Predis 0.8.5

Predis is supported on PHP versions 5.3 and higher. Although Predis is a full PHP client library, the PHP Agent supports Predis as an exit point only, not as an entry point.

Supported Web Service Exit Points

PHP SOAPClient

NuSOAP 0.9.5

Supported Message Queue Exit Points

RabbitMQ

RabbitMQ support requires the amqp extension.

Opcode Cache Compatibility

Alternative PHP Cache (APC)

Correlation with AppDynamics for Databases AppDynamics for Databases version 2.7.4 or higher is required if you want to correlate AppDynamics for Databases with the PHP Agent.

AppDynamics for PHP Architecture

Copyright © AppDynamics 2012-2015 Page 27 The PHP Agent consists of: a PHP extension component a proxy component The PHP extension component discovers, maps and tracks metrics for business transactions, app services, and backends in your web application by injecting instrumentation into the PHP application at runtime. The proxy component is a Java daemon process that handles the communication between the PHP extension component and the Controller. The proxy reports the performance metrics to the Controller, where the data is stored, baselined, and analyzed. You can access this performance data interactively using the Controller console or programmatically using the AppDynamics REST API. By default, the proxy component is automatically started when you start the PHP Agent. Certain deployments require starting the proxy manually. Architecture with Each Agent With Its Own Proxy

Architecture with Multi-Tenant Proxy

On this page: agent.controller.hostName agent.controller.port agent.applicationName agent.tierName agent.nodeName agent.accountName agent.accountAccessKey agent.controller.ssl.enabled agent.proxy_ctrl_dir

The PHP installers write information that the agent uses to communicate with the controller to the AppDynamics Agent section of the PHP configuration files. This is different from some of the other AppDynamics application agents, which write this information to an XML file called controller-info.xml. If you re-install the agent, the installer overwrites your settings only if you are using a fragments directory. It never overwrites the php.ini. You can edit the PHP configuration files after installation to add, delete, or modify these settings. If a setting documented as "required" is not provided, the agent will not start. In this case the agent logs the error to the web server error log. For example, if the controller.Hostname is not set you would see the following message in the the apache error log:

[AD agent] agent.controller.hostName is not set. Agent is disabled.

If after successful startup you remove a required setting or set it to an empty value, the change is ignored as long as the application is running, using the original value of the setting as it was at startup. If, you change a required setting to a different valid value, restart the web server to apply the change. The controller information settings are described below.

agent.controller.hostName

This is the host name or the IP address of the AppDynamics Controller. Example values are 192.168.1.22 or myhost or myhost.abc.com. This is the same host that you use to access the AppDynamics browser-based user interface. For an on-premise Controller, use the value for application server host name that was configured when the Controller was installed. This setting is required.

agent.controller.port

Copyright © AppDynamics 2012-2015 Page 29 This is the HTTP(S) port of the AppDynamics Controller. This is the same port that you use to access the AppDynamics browser-based user interface. If agent.controller.ssl.enabled is true, specify the HTTPS port of the Controller; otherwise specify the HTTP port. See agent.controller.ssl.enabled. For on-premise installations, port 8090 for HTTP and port 8181 for HTTPS are the defaults. This setting is required.

agent.applicationName

This is the name of the logical business application that the instrumented node belongs to. If a business application of the configured name does not exist, it is created automatically. This setting is required.

agent.tierName

This is the name of the logical tier that this node belongs to. This setting is required.

agent.nodeName

This is the name of the instrumented node. This setting is required.

agent.accountName

This is the account name used to authenticate with the Controller. This setting is required if the AppDynamics Controller is running in multi-tenant mode or if you are using the AppDynamics SaaS Controller. It specifies the account name for the agent to use to authenticate with the Controller. If you are using the AppDynamics SaaS Controller, the Welcome email sent by AppDynamics provides the account name. This setting is not required if the Controller is running in single-tenant mode.

agent.accountAccessKey

This is the account access key used to authenticate with the Controller. This setting is required if the AppDynamics Controller is running in multi-tenant mode or if you are using the AppDynamics SaaS Controller. It specifies the account access key for the agent to use to authenticate with the Controller. If you are using the AppDynamics SaaS Controller, the Welcome email sent by AppDynamics provides this information. This setting is not required if the Controller is running in single-tenant mode.

When set to true, this setting specifies that the agent should use SSL (HTTPS) to connect to the Controller. If agent.controller.ssl.enabled is true, set the agent.controller.port to the HTTPs port of the Controller.

agent.proxy_ctrl_dir

This specifies the initial control communication directory between the agent and the proxy. Needed only for manual proxy start. See Run the Proxy Daemon Manually for PHP Agents.

Special Procedures for PHP CLI

On this page: Instrumenting PHP CLI Considerations for Various Scenarios Long-Running CLI Applications with the Suhosin Patch Related pages: Run the Proxy Daemon Manually for PHP Agents Controller Information in the PHP Configuration Files

The main consideration for instrumenting a PHP CLI application is that you must arrange to run the proxy dameon manually. By default the proxy is launched automatically when the agent starts up, which works better in most cases for the non-CLI platforms

Instrumenting PHP CLI

1. Create the proxy control directory, which is used for agent/proxy communication. 2. In your PHP configuration file (php.ini or appdynamics_agent.ini depending on your environment) include the following settings: agent.cli_enabled = 1

Copyright © AppDynamics 2012-2015 Page 31 agent.auto_launch_proxy = 0 agent.proxy_ctrl_dir = If you are using the RPM installer to install the agent you may have configured the proxy control directory using the APPD_PROXY_CTRL_DIR environment variable. See Install the PHP Agent using RPM. This environment variable takes precedence over the setting in the ini file. 3. Before running any traffic through the CLI, run the proxy from the directory into which you installed the PHP agent, passing the proxy control directory and proxy log directory as arguments.

proxy/runProxy

For example:

proxy/runProxy /tmp/proxy.communication /tmp/agentLogs

For the full set of options to runProxy see Execute the runProxy Script Manually.

Considerations for Various Scenarios

If you have PHPs running CLI and apache on the same machine, your AppDynamics setup depends on whether you want all the traffic reported against a single AppDynamics node or separate nodes. A separate proxy is required for each AppDynamics node that you want to monitor in the controller. If you want all the CLI traffic to be reported against one node and all the web traffic to be reported against a different node, configure apache to auto-launch the proxy (the default) and configure CLI to use a manually-launched proxy. This requires separate .ini files - one for the web PHP with agent.auto_launch_proxy set to 1 and another for PHP CLI with agent.auto_launch_proxy set to 0. If you want the web traffic and the CLI traffic to be reported against the same node, configure both apache and CLI to use the same manually launched proxy.

Long-Running CLI Applications with the Suhosin Patch

New in 4.0.3 A side effect of the Suhosin patch is that it prevents the PHP Agent from ensuring cleanup in long-running CLI applications. If your PHP has the Suhosin patch, it is possible that resources will not be freed in long-running applications. Thus memory leaks could result if the application itself does not explicitly free these resources. The long-running-cli feature defends PHP applications in a environment in which both of the following conditions exist: PHP with the Suhosin patch is running on Debian or Ubuntu. It is common for Debian and Ubuntu PHPs to have this patch.

Copyright © AppDynamics 2012-2015 Page 32 This feature is not needed for PHPs with only the Suhosin extension, which is different from the patch. Be aware that some PHPs use both the extension and the patch. Using the PHP Agent API, you are instrumenting a CLI application that has multiple unbounded business transactions running on the same process,

How the Long-Running-Cli Feature Works

At Install Time If the installer determines that PHP has the Suhosin patch and CLI is enabled (agent.cli_enabled=1) and the installer option is set to true, a fatal error is generated and the installer terminates. With the option set, the installer refuses to instrument a long-running CLI application on a PHP installation with the Suhosin patch. If the installer determines that PHP has the Suhosin patch and CLI is enabled (agent.cli_enabled=1) and the installer option is set to false (the default), the installation continues and warns that memory leaks could occur in long running CLI processes. If the installer determines that PHP does not have the Suhosin patch, the installation continues. Long-running CLI processes are supported by the agent, since there is no Suhosin patch.

Installer Option If the agent could not determine whether your PHP has the Suhosin patch at install time but it does detect the patch at runtime, having set the installer option to true prevents the agent from instrumenting any CLI processes, not just long-running ones. This is done to prevent the Suhosin-patched PHP from exiting. If CLI is enabled and the installer did not terminate because of the detection of the Suhosin patch, AppDynamics recommends that you install the agent with the enable-cli-long-running option (shell script installs) or the APPD_CONF_CLI_LONG_RUNNING_ENABLED environment variable (RPM installs) set to true. This will defend your PHP if the patch is detected at runtime. If the CLI part of your application does not get instrumented (because the installer detected the Suhosin patch), you can unset the option by setting the agent.cli_long_running option in the PHP ini file to off. Or alternatively, you can re-install with the installer

Set Up a Multi-Tenant Proxy for PHP Agents

On this page: Setting up a Multi-Tenant Proxy Related pages: AppDynamics for PHP Architecture Execute the runProxy Script Manually Run the Proxy Daemon Manually for PHP Agents Install the PHP Agent

By default, if you are running multiple agents, each agent automatically launches its own Java proxy to communicate with the controller.

Copyright © AppDynamics 2012-2015 Page 33 However, if you are running multiple PHP Agents on the same machine, you can reduce your overhead by setting up the agents to report to a single multi-tenant Java proxy. In this case you would need to start that proxy manually. The number of nodes that can report to a single proxy is limited by the size of the heap given to the proxy. You may need to adjust the maxHeapSize and maxPermSize settings in the runproxy script if you have a large number of agents reporting to a single proxy. Contact AppDynamics Support if you need to change these settings.

Setting up a Multi-Tenant Proxy

1. Configure each agent for manual launch of the proxy. To do this, in the PHP configuration file (php.ini or appdynamics_agent.ini depending on your setup) for each agent, set the agent.auto_launch_proxy value to 0. 2. Configure a single proxy control directory for all the agents that will share the proxy. They must all be on the same machine. To do this, in the PHP configuration file for each agent, set agent.proxy_ctrl_dir to the same proxy control directory. The permissions on this directory should be readable and executable by the process that runs apache and writable by the process that runs the proxy. 3. Before you start the agents, arrange to launch the proxy manually, passing the proxy control directory configured in step 2 as the proxyCommunicationDir argument to the runProxy script. See Execute the runProxy Script Manually. AppDynamics recommends launching the proxy on system startup. 4. Verify that each agent reporting to the multi-tenant proxy is configured with a unique app_name/node_name combination. The app_name and node_name are arguments to the agent install script.

Run the Proxy Daemon Manually for PHP Agents

Related pages: Set Up a Multi-Tenant Proxy for PHP Agents Special Procedures for PHP CLI

By default, when the PHP agent starts up, it automatically executes the runproxy shell script. This script runs the Java proxy daemon that handles communication between the PHP agents and the controller. See AppDynamics for PHP Architecture for information about how the Java proxy daemon fits into the PHP agent architecture. Automatic startup of the proxy works for the great majority of situations. However, you can suppress the automatic startup of this script and run it manually. You would do this if: You plan to instrument a PHP CLI entry point. The PHP CLI entry point requires manual startup of the proxy and immediate creation of the node on startup. You have multiple apache pools on the same machine reporting to the same proxy. To do this, you first need to configure the agent for manual proxy launch. Then you need to launch the proxy manually. See:

Related pages: Controller Information in the PHP Configuration Files Install the PHP Agent Execute the runProxy Script Manually Run the Proxy Daemon Manually for PHP Agents

You need to configure the agent for manual startup if you plan to start the runproxy script manually. To do this: 1. By default the agent.auto_launch_proxy setting in php.ini or appdynamics_agent.ini is set to 1 to enable automatic startup of the proxy. Change it to 0 to suppress automatic startup if you want to execute runProxy manually. 2. In the PHP configuration file (php.ini or appdynamics_agent.ini depending on your setup), set the agent.proxy_script to the path of the runproxy that you want to use. The file in the script is relative to the root of the PHP agent. You can specify the absolute path if you prefer. 3. In the PHP configuration file, set the agent.proxy_ctrl_dir to the directory to use for initial control communication between the agent and the proxy. This directory contains the domain control socket, which the agent uses to start an AppDynamics node. This directory is where the agent gets the configuration for the node. The application user must have read permission on the proxy_ctrl_dir. Whenever you install the PHP agent, the installer overwrites the runproxy script and the appdynamics_agent.ini file, but not the php.ini. If you re-install, you need to reset the agent.auto_launch_proxy setting in the appdynamics_agent.ini file before you restart the server.

Execute the runProxy Script Manually

Related pages: Configure Manual Startup of the runProxy Script for PHP Agents Run the Proxy Daemon Manually for PHP Agents

By default, the proxy component is automatically started when you start the agent. Use the command described here only if you have configured the agent for manual proxy launch. Before any traffic is run on the instrumented server, execute the appropriate version of the runproxy script to start the proxy. Here is the full set of options for the runProxy script. The proxy control directory is required.

Options: -r

, --proxy-runtime-dir= Specifies proxy runtime directory -d , --proxy-dir= Specifies root proxy directory -j , --jre-dir= Specifies root JRE directory -v, --verbose Enable verbose output -h,--help Show this message

Example Usage:

./proxy/runProxy -d ./proxy -r /tmp/proxy.communication /tmp/agentLogs

When the proxy starts, nodes are not created immediately. A node is created when the agent first detects traffic on it. Every time you reboot the server, you need to execute the runproxy script if you have opted to start the proxy manually.