Troubleshoot the PHP Library

If you are not receiving traces and metrics in the Traces Explorer and Metrics Explorer, these are some options to troubleshoot.

Are both my platform and application supported?

See SolarWinds Observability SaaS System Requirements to for a list of supported platforms for your application's host environment. While the PHP Library may work on an unsupported platform, it may also result in crashes or unexpected behavior.

For a list of PHP versions and components the PHP Library supports, see Components supported by the PHP Library. If your component is not on the list, use the SDK for custom instrumentation.

Are there problems with the Just-In-Time (JIT) compiler in PHP >= 8.0?

The PHP Library is not compatible with the JIT compiler. If you do not disable JIT, JIT will be automatically disabled.

Are requests being sent to the application?

Restart the web server or PHP process and make sure that your application is receiving requests. For traces and metric data to be sent to the Traces Explorer or Metrics Explorer, your application must receive requests.

Do you have more than one APM extension installed?

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*'

Is the library extension enabled?

Depending on your PHP used, do the following to get information about the PHP Library:

• PHP (CLI):
  • Run the php -i command to get PHP module and configuration information.
• PHP (Apache mod_php):
  • Run the php -m command to verify the SolarWinds Observability PHP library is loaded without errors or warnings.
  • Run the php --ini command to find out where the configuration files in use are located (for example, /etc/php/7.4/cli).
  • Run the php -i command to get PHP module and configuration information.
  • Use the phpinfo() function in the PHP webpage to verify the SolarWinds Observability PHP Library.
• PHP-FPM (for example, php-fpm7.4): 
  • Run the php-fpm7.4 -m command to verify the SolarWinds Observability PHP library is loaded without errors or warnings.
  • Run the php-fpm7.4 -i command to get PHP module and configuration information.
  • Run the service php7.4-fpm status to check if the PHP-FPM service is active. If it is not, stop the php-fpm service and investigate the PHP-FPM configuration (for example, /etc/php/7.4/fpm)
  • After service php7.4-fpm start is good, use the phpinfo() function in the PHP webpage to verify the SolarWinds Observability PHP Library.
  • Depending on the PHP-FPM version used, the name of the service and executable may vary.

The PHP Library extension name is solarwinds-apm. If the library is enabled, the above commands show the location of solarwinds-apm.ini, along with the version and configuration options in effect for the library.

The PHP Library is disabled by default for CLI. To enable it, use the configuration option solarwinds-apm.enable_cli.

Is the library installed for the correct SAPI?

If you used the wrapper script to install the library and did not specify the parameters --extension-dir, --ini-dir, and --thread-safety, the wrapper script will attempt to detect these values automatically for your SAPI.

If your system uses both a non-thread safe version of CLI PHP and a thread-safe version of Apache/FPM PHP, automatic detection does not work for the thread-safe version. During installation, use installation options to specify the parameters --extension-dir, --ini-dir, and --thread-safety to match your SAPI.

For example Amazon Linux 2 uses a non-thread-safe version of CLI PHP and a thread-safe version of Apache PHP. The call to solarwinds-apm-php.sh looks like this to install the library for Apache PHP:

./solarwinds-apm-php.sh --service-key=YourServiceKey --extension-dir=/usr/lib64/php-zts/modules --ini-dir=/etc/php-zts.d --thread-safety=TS

Replace YourServiceKey with the Service key you are using to identify your account and the service being instrumented. 

For more information see Install with a wrapper script.

Has the library been initialized?

Look at the response headers returned to check if the library has been initialized. The PHP Library adds the header X-Trace to the response. If the response does not contain the header X-Trace, then the library likely was not loaded correctly.

Review the other troubleshooting options to try to resolve the issue.

Is the library connected to the SolarWinds APM collector?

Review the PHP Library logs in the Log File Locations to see if there are any connection issues logged.

If your server is behind a firewall, you may not be able to connect to the SolarWinds APM collector. See Firewall or access control requirements.

Are requests being sampled for tracing?

If there is a low sample rate or connection issues, requests may not be sampled. The X-Trace response header ends in 00 if a request isn’t traced and ends in 01 if the request is being traced.

There should be some requests that return an X-Trace header ending in 01. If all X-Trace headers end in 00, this may indicate the server cannot connect to the SolarWinds APM collector.

Review the logs in the Log File Locations for connection issues logged by the PHP Library.

Is the service key configured correctly?

The Service key is added to the solarwinds-apm.ini file under your PHP configuration INI files directory.

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and 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.

Where can library logs be found?

The web server log file contains the PHP Library logs.

How can I increase log verbosity?

To set the logging level, modify the config option solarwinds-apm.debug_level or the environment variable SW_APM_DEBUG_LEVEL. The values for the logging level are: -1 disable, 0 fatal, 1 error, 2 warning (the default), 3 info, 4 debug low, 5 debug medium, 6 debug high. Increase the logging verbosity to one of the debug levels to add more detailed information to the PHP Library logs.

If using the SW_APM_DEBUG_LEVEL environment variable and running under Apache mod_php, make the SW_APM_DEBUG_LEVEL environment variable available at Apache startup. For a default apache2 install on a Debian/Ubuntu system, set the environment variable in the /etc/apache2/envvars file. For a default httpd install on RHEL/CentOS/Amazon Linux, set the environment variable in the /etc/sysconfig/httpd file. The following example sets the SW_APM_DEBUG_LEVEL environment variable to high.

export SW_APM_DEBUG_LEVEL=6

Restart the web server or PHP process so the new level can take effect. Log messages from the PHP Library are sent to stderr and end with [liboboe-...].

PHP C extension logging may also need to be increased to see certain messages from the APM library. This can be done using PHP’s error_reporting setting.

Before PHP version 8.0.0, the default value of error_reporting is E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED. This means diagnostics of level E_NOTICE, E_STRICT, and E_DEPRECATED were not shown.

In PHP version 8.0.0 or later, the default value of error_reporting is E_ALL.

To troubleshoot a user-defined trusted certificate path issue, set the error_reporting to E_ALL in php.ini.

Are there warnings reported by the library?

Review the logs in the Log file locations for errors and warnings messages from the PHP Library that include [liboboe-...-error or [liboboe-...-warn.

Why are errors or exceptions not reported?

Check if the xdebug extension is enabled. This extension interferes with the PHP Library's ability to see and report errors. If the xdebug extension is enabled, disable it.

Is there a limit set on memory usage?

The PHP Library increases the memory usage of the application. Trace data needs to be buffered before it is sent to the SolarWinds APM collector for analysis. A slow connection causes additional buffering. There is a default limit for the buffers, however if your application does not have enough available memory to accommodate the default limit try the following:

• Increase the PHP memory limit. Set the PHP memory limit with the memory_limit configuration option. This configuration option can be set in either the INI file (memory_limit = 512M), or the PHP script itself (ini_set( 'memory_limit', '512M' )).

• Disable backtrace collection. By default, the library generates backtrace data for each request, which can add a lot of extra data to be buffered. Set the solarwinds-apm.enable_backtrace = 0 config option in solarwinds-apm.ini to disable backtrace.

• Reduce the number of max transactions. Each transaction within a 30 second period is stored with a histogram object, which takes up a lot of memory. Change the solarwinds-apm.max_transactions config option to a lower value; the default is a maximum of 50 transactions per process.

• Reduce buffer sizes. Collected data is internally stored in buffers before sending them to the SolarWinds APM collector. The default buffer size is 1,000, which allows 1,000 total status and/or metric messages and 10 x 1,000 event messages. Set the environment variable SW_APM_BUFSIZE to reduce the buffer size. A value of 100 will reduce the buffer size to 100 total status and/or metrics messages and 1,000 event messages.

Can I enable/disable tracing for a particular CLI invocation?

See Enable CLI for a description and examples for the configuration option solarwinds-apm.enable_cli.

Can I use pcntl_fork() in my PHP application?

The pcntl_fork() function is currently only supported if a trace is started manually after pcntl_fork() has been invoked.

An example of how to start and stop traces in a forked environment is:

<?php
  $pid = pcntl_fork();

  if ($pid == -1) {

    die('could not fork');
  } else if ($pid) {

    // in parent process
    solarwinds_apm_start_trace('parent');
    echo "this is the parent\n";
    solarwinds_apm_end_trace();
    pcntl_wait($status);

  } else {

    // in child process
    solarwinds_apm_start_trace('child');
    echo "this is the child\n";
    solarwinds_apm_end_trace();

  }
?>

Why is there an error about GLIBC?

If you encounter this error or similar one:

PHP Warning: PHP Startup: Unable to load dynamic library '/usr/lib64/php/modules/solarwinds-apm.so' - /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.18' not found (required by /usr/lib64/php/modules/solarwinds-apm.so) in Unknown on line 0

This can happen if you run the PHP Library on an unsupported platform. Make sure your platform is supported.

What should I do in case of a crash?

Confirm your platform is supported and this is the only APM extension installed.

A wide variety of combinations of PHP extensions, PHP frameworks, and workflows is available. It's possible that a specific combination could result in an unexpected error. If you encounter an error or crash that occurs only when the SolarWinds Observability PHP Library is enabled, contact Support. See Support.

To help us identify the problem:

1. Create a core dump (see Generating a gdb backtrace in the PHP bug tracking system). On systems that have Apport enabled, first find the crash file (typically under /var/crash), extract the CoreDump file from it using apport-unpack <filename>.crash <destination>, then in the next step run the packcore script from the destination directory.

2. Run the SolarWinds Observability packcore script on the core dump to collect all relevant binaries (executable + shared libraries) from the system. The SolarWinds Observability packcore script creates a .tar.xz archive that you can send to SolarWinds support.

   wget https://agent-binaries.cloud.solarwinds.com/apm/php/latest/php-agent-packcore.sh
   sh php-agent-packcore.sh <COREFILE>

3. (Optional) Provide a PHP script SolarWinds support can use to reproduce the error.

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.