The following content pertains to
AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries can send APM data in AppOptics and are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider transitioning to the SolarWinds Observability libraries for your APM needs. For more information about the benefits of migrating to the SolarWinds Observability libraries. Alternatively, you can use SolarWinds Observability as your primary APM solution.
If you have already transitioned to the new SolarWinds Observability PHP Library, see the SolarWinds PHP Library documentation for installation information.
SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.
The AppOptics PHP instrumentation is distributed as a .so binary file. There are several ways you can install the instrumentation depending on your needs.
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
--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:
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
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
Once instrumentation is successfully deployed, make sure to restart the PHP service. Usually this is accomplished by restarting the web server.
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
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.
These steps are only required if you're not using the wrapper script mentioned above but prefer to install the PHP instrumentation manually.
Support for PHP 5 was dropped in agent version 5.0.0; the latest version with PHP 5 support will be agent versions 4.x
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’.
Only install the +zts version of the .so if your server is using a zend thread safety version of PHP.
For Alpine Linux please choose the .so file with the tag "alpine" and the
corresponding SSL version (for Alpine 3.5/3.6/3.7/3.8 choose the libreSSL
appoptics-php-<API>-alpine-libressl-x86_64.so) and for Alpine >= 3.9
the non-libreSSL version (
appoptics-php-<API>-alpine-x86_64.so)). For all
other distributions choose the .so file without the tag "alpine"
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
Then, either * edit your php configs to load the module. You'll need to
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.
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
--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.
There is a different extension .so binary file per PHP version, so if you change the PHP version configured for the stack please rerun the wrapper script which reinstalls the correct binary to match the new PHP version.
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.
The PHP Agent log messages are sent to stderr, which is usually written to log files configured for the web server.
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
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
[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.
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.
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
--ini-dir=<DIR>. For a full list of options simply run the script
without any options (see Installing via wrapper
Once the script completes, restart your application/service.
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
and delete the file
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.