Install the PHP Library

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

Before you start

Verify the following to ensure the library can collect and transmit data:

The platform where your APM library will be installed is supported.
Your application components are supported by the library.
Your firewall configuration permits TCP/HTTPS/TLS outbound connections to otel.collector.xx-yy.cloud.solarwinds.com (or apm.collector.xx-yy.cloud.solarwinds.com when using legacy mode) port 443, where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs. See Firewall or access control requirements.

If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM library extensions alongside the SolarWinds Observability PHP Library. Remove other APM libraries from your PHP installation before using the SolarWinds Observability PHP Library.

If you have an AppOptics PHP Agent installed, execute the following command under /etc/php to determine where the agent files or references are located.

find . -iname 'appoptics*'

See Uninstalling the PHP agent in the AppOptics documentation.

Requirements on Alpine

On Alpine, the libstdc++ system package is required. The installer script checks for this and stops with a warning if the requirement is not satisfied.

Install the library

Install with a wrapper script

Additional installation options are available for when PHP is installed in a non-standard location or your CLI API differs from your Server API.

To install the library in a standard environment where PHP is installed in the default location:

Copy the command below or click Copy in step 1 of the Add Data dialog. Run the copied command in the command line to download the wrapper script.
```
curl -sSO https://agent-binaries.cloud.solarwinds.com/apm/php/latest/solarwinds-apm-php.sh
```
If the server you are installing the PHP Library on does not have direct access to the internet, download the tarball located at https://agent-binaries.cloud.solarwinds.com/apm/php/latest/solarwinds-apm-php.tar.gz and place the unextracted tarball in the same directory as the wrapper script. This tarball contains the instrumentation files for all supported PHP versions.
Copy the command below or click Copy in step 2 of the Add Data dialog. Run the copied command in the command line to run the wrapper script.
```
sh solarwinds-apm-php.sh --service-key=YourServiceKey
```
Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented.

The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

To verify a successful installation, look for solarwinds-apm.so in your PHP extension directory and solarwinds-apm.ini in your INI directory.

If your PHP configuration is already customized, the PHP Library does not replace your configuration. Instead, the options available to customize for the PHP Library are printed to the console. Manually add the library configuration options to the main php.ini config file.
Restart the PHP service and web server. Trace data and metrics will soon be accessible in the Traces Explorer and Metrics Explorer. For some example commands to restart the service, see Examples: Restart PHP and verify loaded modules.

To help ensure the PHP Library is initiated, especially if your application has infrequent activity, use the application for a few seconds to generate data. Look for the data in the Traces Explorer and Metrics Explorer.

Installation options

The wrapper script uses the PHP command line interface (CLI). If your PHP deployment is installed in a non-default location, 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), pass in the --thread-safety=<TS|NTS> option as well to install the correct version for your API.

For a full list of options, run the script without any options:

sh solarwinds-apm-php.sh

Pass a service key as an argument with the --service-key option.
Usage: solarwinds-apm-php.sh --service-key=<KEY> [--mode=<install|uninstall>] [--extension-dir=<DIR>] [--ini-dir=<DIR>] [--thread-safety=<TS|NTS>] [--api=<API>] [--version=<VERSION>] [--url=<URL>] [--collector=<COLLECTOR>] [--timeout=<TIMEOUT>]
--service-key: unique service identifier
--mode: install or uninstall the PHP Library (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 Library from (optional, default: https://agent-binaries.cloud.solarwinds.com/apm/php/latest/)
--collector: the collector endpoint (optional, default: apm.collector.xx-yy.cloud.solarwinds.com)
--timeout: TIME in second to allow wget/curl to download the PHP Library (optional, default: 60)

Install manually

To install the PHP Library manually instead of using the wrapper script:

Find the .so for your PHP version at https://agent-binaries.cloud.solarwinds.com/index.html?prefix=apm/php/latest/. To discover your PHP API number (for example: 20160303), run the command php -i or phpinfo() and look for PHP Extension. Use the following rules as a guide when choosing the.so file:
- Only install the +zts version of the .so if your server is using a zend thread safety version of PHP.
- For Alpine Linux choose the .so file that includes the tag alpine and the corresponding SSL version. For Alpine 3.5/3.6/3.7/3.8 choose the libreSSL version (-<API>-alpine-libressl-x86_64.so), and for Alpine >= 3.9 the non-libreSSL version (solarwinds-apm-<API>-alpine-x86_64.so).
- For all other distributions choose the .so file without the tag alpine (solarwinds-apm-<API>-x86_64.so).
Download the .so file, rename it to solarwinds-apm.so, and place it in your extensions directory. To find your extensions directory, run the command php-config --extension-dir.
Either download the solarwinds-apm.ini config file to your PHP INI directory or edit your existing PHP config files to load the module. If you edit your PHP config files to load the module, add extension=solarwinds-apm.so wherever you are loading your extensions (usually in php.ini).
Restart the PHP service and web server. Trace data and metrics will soon be accessible in the Traces Explorer and Metrics Explorer. For some example commands to restart the service, see Examples: Restart PHP and verify loaded modules.

To help ensure the PHP Library is initiated, especially if your application has infrequent activity, use the application for a few seconds to generate data. Look for the data in the Traces Explorer and Metrics Explorer.

Install on Azure App Service

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

Open an SSH session to your app instance and create the directory /home/site/wwwroot/solarwinds-apm where library files will be kept.
```
# in the app instance console session
mkdir -p /home/site/wwwroot/solarwinds-apm
cd /home/site/wwwroot/solarwinds-apm
```
Download the library install wrapper to the /home/site/wwwroot/solarwinds-apm directory. From the /home/site/wwwroot/solarwinds-apm directory, run the wrapper script with the --extension-dir=./ and --ini-dir=./ options. This installs the PHP Library to the current directory.

Edit the INI config file so it has the correct extension location. For example, extension=/home/site/wwwroot/solarwinds-apm/solarwinds-apm.so.

An example of the commands to download and install the library, and edit the INI is:
```
# in the app instance console session, pwd is /home/site/wwwroot/solarwinds-apm
curl -sSO https://agent-binaries.cloud.solarwinds.com/apm/php/latest/solarwinds-apm-php.sh
sh solarwinds-apm-php.sh --extension-dir=./ --ini-dir=./ --service-key=YourServiceKey
sed -i -e 's|extension=solarwinds-apm.so|extension=/home/site/wwwroot/solarwinds-apm/solarwinds-apm.so|' solarwinds-apm.ini
```
Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented.

The Service key should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
In the Azure portal for your App Service, use application settings to configure a custom PHP_INI_SCAN_DIR that includes /home/site/wwwroot/solarwinds-apm. If desired, override the Service key using an application setting.

See Customize PHP_INI_SYSTEM directives in Microsoft Azure documentation.
Restart the service and web server. Trace data and metrics will soon be accessible in the Traces Explorer and Metrics Explorer.

To help ensure the PHP Library is initiated, especially if your application has infrequent activity, use the application for a few seconds to generate data. Look for the data in the Traces Explorer and Metrics Explorer.

There is a different extension .so binary file for each PHP version. If you change the PHP version configured for the stack, rerun the wrapper script to reinstall the correct binary for the new PHP version.

Examples: Restart PHP and verify loaded modules

The service and web server must be restarted for trace data and metrics to be sent to SolarWinds Observability SaaS. The exact commands used to restart PHP and verify which PHP modules are loaded will vary by operating system and configuration. The below commands are some examples.

To see a list of loaded PHP modules and verify whether the PHP library is loaded in PHP use the following command. It should not have any errors:
```
php -m
```
To start a PHP-FPM and NGINX service in Ubuntu, use the following commands:
```
service php8.1-fpm start
service nginx start
```
To start a mod-php and Apache service in Ubuntu, use the following command:
```
service apache2 start
```

Troubleshooting

See Troubleshoot the PHP Library if traces and metric data do not appear in the Traces Explorer and Metrics Explorer.

Log file locations

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

Apache

For a default apache2 install on a Debian/Ubuntu system, the log file is located at /var/log/apache2/error.log. For the default http install on RHEL/CentOS/Amazon Linux, the log file is located at /var/log/httpd/error.log.

Nginx (PHP-FPM)

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

catch_workers_output = yes

The string [liboboe-...] appears at the end of each library message. By default, only messages with verbosity level of warning or lower are reported. To see debugging messages, set the logging level to debug. See Troubleshoot the PHP Library.

Uninstall the library

Uninstall with wrapper script

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

curl -sSO https://agent-binaries.cloud.solarwinds.com/apm/php/latest/solarwinds-apm-php.sh
sh solarwinds-apm-php.sh --mode=uninstall

The same installation options can be used to uninstall the library. If PHP is installed in a non-standard location pass in the extra options --extension-dir=<DIR> and --ini-dir=<DIR>

When the wrapper script is complete, restart the PHP service and web server.

Uninstall manually

To uninstall the PHP Library manually instead of using the wrapper script:

Run php-config --extension-dir to find the extensions directory and delete solarwinds-apm.so
Run php -i | grep -i "additional .ini" to find your INI directory and delete solarwinds-apm.ini. If you used your main PHP config file php.ini to define your SolarWinds Observability PHP Library configuration options, remove all SolarWinds Observability-specific options from the config file.
Restart the PHP service and web server.

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.

Search SolarWinds Support