Installation (legacy agent)

The following content pertains to installation for the legacy AppOptics PHP Agent.

The AppOptics PHP instrumentation is distributed as a .so binary file. There are several ways you can install the instrumentation depending on your needs.

Installing the agent

Installing via wrapper script

This is the easiest option since the download and deployment of the .so file is taken care of by the wrapper script. If your PHP is installed in the default location, all you need to do is to download the wrapper script and run it like so:

curl -sSO https://files.appoptics.com/appoptics-php.sh
sh appoptics-php.sh --service-key=<your service key>

Note that this script requires PHP CLI. If your PHP is installed in a non-default location you can pass in the extra options --extension-dir=<DIR> and --ini-dir=<DIR>. If your CLI API differs from your Server API (Apache/FPM) in terms of the Thread Safety compile option (TS vs. NTS) you will also have to pass in another option --thread-safety=<TS|NTS> to install the correct version for your API. For a full list of options simply run the script without any options:

sh appoptics-php.sh

Please pass in a service key via the --service-key option.
Usage: appoptics-php.sh --service-key=<KEY> [--mode=<install|uninstall>] [--extension-dir=<DIR>] [--ini-dir=<DIR>] [--thread-safety=<TS|NTS>] [--version=<VERSION>] [--url=<URL>]
--service-key: unique service identifier
---mode: install or uninstall the PHP agent (optional, default: install)
--extension-dir: Extension directory (optional, will attempt to detect automatically if not set)
--ini-dir: INI directory (optional, will attempt to detect automatically if not set)
--thread-safety: install thread-safe (TS) or non-thread-safe (NTS) version (optional, will attempt to detect automatically if not set)
--api: install PHP extension version (e.g. 20170718, optional, will attempt to detect automatically if not set)
--version: version to install (optional, default: latest)
--url: URL to get the PHP agent from (optional, default: https://files.appoptics.com/php)

You can verify a successful installation by checking the existence of appoptics.so in your PHP extension directory and appoptics.ini in your INI directory (note: if for some reason you don’t use additional INI files, the AppOptics options will be shown on the console output and you will have to manually add them to the main configuration file php.ini).

Once instrumentation is successfully deployed, make sure to restart the PHP service. Usually this is accomplished by restarting the web server.

Installing via wrapper script (no download)

If the server you are installing the PHP instrumentation on doesn't have direct access to the internet, the wrapper script won't be able to download the required files. In that case you can manually download the tarball appoptics-php.tar.gz that contains the instrumentation files for all supported PHP versions from https://files.appoptics.com/php and place it in the same directory as the wrapper script (note: leave tarball as is, no need to extract the content).

Then simply run the wrapper script to start the installation:

sh appoptics-php.sh --service-key=<KEY>

Refer to the install options discussed in Installing via wrapper script.

Installing manually

These steps are only required if you're not using the wrapper script mentioned above but prefer to install the PHP instrumentation manually.

First, find the .so for your PHP version at https://files.appoptics.com/php. You can discover your PHP API number (20160303, 20151012, 20131226, …) by running php -i or phpinfo() and looking for ‘PHP Extension’.

Then, download the appropriate .so file, change its name to ‘appoptics.so', and place it in your extensions directory. If you're not sure where that is, you can find out by running php-config --extension-dir.

Then, either * edit your php configs to load the module. You'll need to add extension=appoptics.so wherever you are loading your extensions — usually in php.ini * or download appoptics.ini and place it in your PHP INI directory.

Lastly, restart the PHP service. Usually this is accomplished by restarting the web server.

Installing on Heroku

Ensure that the AppOptics add-on is attached to your Heroku application, then follow the PHP agent steps to install and enable the agent.

Installing on Azure App Service

If your PHP application platform is Azure App Service on Linux, installing APM is as simple as adding the PHP agent extension, configuring it to be loaded in the App Service environment, then restarting the app.

To install the agent, SSH into your App Service instance and create the directory /home/site/wwwroot/appoptics where agent files will be kept:

# in the app instance console session
mkdir -p /home/site/wwwroot/appoptics
cd /home/site/wwwroot/appoptics

In this directory, download the agent install wrapper and run it with the --extension-dir=./ and --ini-dir=./ options to install agent files into the current directory. Then edit the INI configuration file so it has the correct extension location, e.g. extension=/home/site/wwwroot/appoptics/appoptics.so. An example is shown below, note that you’ll need to switch in a valid service key:

# in the app instance console session, pwd is /home/site/wwwroot/appoptics
curl -sSO https://files.appoptics.com/appoptics-php.sh
sh appoptics-php.sh --extension-dir=./ --ini-dir=./ --service-key=<your service key>
sed -i -e 's|extension=appoptics.so|extension=/home/site/wwwroot/appoptics/appoptics.so|' appoptics.ini

Then in the Azure portal for your App Service, use application settings to configure a custom PHP_INI_SCAN_DIR that includes /home/site/wwwroot/appoptics. You may also override the service key via an application setting. For example:

Finally, restart the application and you should see trace data and metrics shortly.

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, please review the Troubleshooting page for tips on how to resolve.

Log File Locations

The PHP Agent log messages are sent to stderr, which is usually written to log files configured for the web server.

Apache

With the default apache2 install on a Debian/Ubuntu system the logfile is /var/log/apache2/error.log, and with the default http install on RHEL/CentOS/Amazon Linux this is /var/log/httpd/error.log.

Nginx (PHP-FPM)

The main error log location is defined in the main config file (e.g. /etc/php/7.0/fpm/php-fpm.conf) and the location is /var/log/php7.0-fpm.log. By default the PHP-FPM workers redirect stdout and stderr to /dev/null. In order to redirect messages into the main error log, set this option in the pool config file (e.g. /etc/php/7.0/fpm/pool.d/www.conf):

catch_workers_output = yes

The string [AppOptics-...] appears at the end of each agent message. By default only messages with verbosity warning or lower (error, etc.) are reported. To see debugging messages, please set the logging level to debug. More details in Troubleshooting.

Uninstalling the agent

Just like with the installation, you can either use the wrapper script to uninstall the PHP instrumentation or do it manually, if that's your preferred method.

Uninstalling via wrapper script

If your PHP and instrumentation is installed in the default location, all you need to do is to download the wrapper script (if you haven't already) and run it like so:

curl -sSO https://files.appoptics.com/appoptics-php.sh
sh appoptics-php.sh --mode=uninstall

If your PHP and instrumentation is installed in a non-default location you can pass in the extra options --extension-dir=<DIR> and --ini-dir=<DIR>. For a full list of options simply run the script without any options (see Installing via wrapper script).

Once the script completes, restart your application/service.

Uninstalling manually

These steps are only required if you're not using the wrapper script mentioned above but prefer to uninstall the PHP instrumentation manually.

Find your extensions directory by running php-config --extension-dir and delete the file appoptics.so.

Then find your INI directory by running php -i | grep -i "additional .ini" and delete the configuration appoptics.ini. Alternatively, if your AppOptics options live in the main configuration file php.ini, remove all AppOptics-specific options from that configuration file.

Once the script completes, restart your application/service.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.