Skip to main content

Troubleshooting

Troubleshooting Installation and Configuration Issues​

This guide explains how to diagnose and resolve errors that may occur during installation and configuration of the WhaTap PHP Agent.

Linux/FreeBSD​

Manual configuration of PHP extension module and whatap-php service​

If installation of the PHP extension module and whatap-php service (install.sh) has not been successful, you can install them manually. Use this method when environment information cannot be checked for any reasons such as PHP compile installation.

Creation of whatap.ini​

$ cp /usr/whatap/php/template.ini /usr/whatap/php/whatap.ini
$ vi /usr/whatap/php/whatap.ini

# Add this content at the top
; Enable whatap extension module
extension=whatap.so
whatap.license=            # Issued access key
whatap.server.host=        # Issued server IP
whatap.app_name=           # Web server classification: APHP, FPHP (apache: APHP, php-fpm : FPHP)
whatap.app_process_name=   # Process name of apache and php-fpm (httpd,php-fpm)
ConfigurationDescription
whatap.licenseThe access key issued from Project Menu > Management > Agent Installation can be checked.
whatap.server.hostYou can see the server IP issued from Project Menu > Management > Agent Installation.
whatap.app_nameAPHP is used for the Apache server and FPHP is used for php-fpm.
whatap.app_process_nameIf you enter the exact value as the execution process name of Apache or php-fpm, the memory usage for the process is collected. For example, they are httpd, apache2, php-fpm, and such.

Checking the PHP command (CLI)​

$ which php

/usr/bin/php

Configuring the environment variables for the whatap-php service​

Set the PHP CLI command's path in the $WHATAP_PHP_BIN environment variable.

$ sudo vi /etc/init.d/whatap-php

export WHATAP_PHP_BIN=    # PHP command's location (/usr/bin/php)

Checking the PHP API version​

Set the PHP CLI command's path in the $WHATAP_PHP_BIN environment variable.

$ sudo php -i | grep 'PHP API'

PHP API => 20100412

Checking whether PHP ZTS (Zend Thread Safe) is available​

$ sudo apachectl -V | grep MPM

Server MPM: Prefork      # ZTS unavailable
Server MPM: Worker       # ZTS available
$ sudo php-fpm -i | grep Thread

Thread Safety => disabled       # ZTS unavailable
Thread Safety => enabled       	# ZTS available

Checking and configuring the PHP extension module's path​

Checking the PHP extension module's path​

$ sudo php -i | grep extension_dir

extension_dir => /usr/lib64/php/modules => /usr/lib64/php/modules

Configuring the PHP extension module​

After checking the PHP API version and PHP ZTS's availability, select a library that meets the environment. In the PHP extension module's path, copy the whatap.so file name.

  • In case PHP ZTS is available - whatap_zts_[PHP API version].so
  • In case PHP ZTS is unavailable - whatap_[PHP API version].so 
    # Example in case the PHP ZTS is not supported
    $ sudo cp /usr/whatap/php/modules/x64/whatap_20100412.so /usr/lib64/php/modules/whatap.so

Configuring the environment variables for the whatap-php service​

$ sudo vi /etc/init.d/whatap-php

export WHATAP_PHP_EXT_HOME=   # PHP extension path (/usr/lib64/php/modules)
export WHATAP_PHP_EXT_SRC=    # whatap library path and file name
                              # (/usr/whatap/php/modules/x64/whatap_20100412.so)]
  1. In the $WHATAP_PHP_EXT_HOME environment variable, set the PHP extension module's path.
  2. In the $WHATAP_PHP_EXT_SRC environment variable, set the whatap library's full file path.

whatap.ini configuration​

  1. Check the PHP ini file's path that has been added.

    $ sudo php -i | grep '.ini files'

    Scan this dir for additional .ini files => /etc/php.d

  2. Copy whatap.ini and paste it to the path.

    $ sudo cp /usr/whatap/php/whatap.ini /etc/php.d/whtap/ini

Windows​

Manual Configuration of PHP Extension Module and WhaTap PHP Service​

If the PHP extension module or the whatap-php service was not installed correctly, or the optional installation (install.sh) did not complete properly, follow the manual configuration steps below.

Checking PHP Environment Information​

Check your PHP environment:

REM Check PHP API version
php -i | findstr "PHP API"

REM Check Thread Safety
php -i | findstr "Thread Safety"

REM Check extension directory
php -i | findstr extension_dir

REM Check PHP configuration file location
php --ini

Example Output

PHP API => 20230831
Thread Safety => disabled
extension_dir => C:\PHP\ext

Configuration File (php.ini) Path: C:\Windows
Loaded Configuration File:         C:\PHP\php.ini
Scan for additional .ini files in: C:\PHP\conf.d
Additional .ini files parsed:      (none)

Copying php_whatap.dll​

Copy the correct DLL to the extension_dir path you confirmed:

REM Example: extension_dir => C:\PHP\ext

REM Non-ZTS version
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_[API_VERSION].dll" "C:\PHP\ext\php_whatap.dll"

REM ZTS version
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_zts_[API_VERSION].dll" "C:\PHP\ext\php_whatap.dll"

Examples

REM PHP 8.3 (API 20230831) NTS
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_20230831.dll" "C:\PHP\ext\php_whatap.dll"

REM PHP 8.3 (API 20230831) ZTS
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_zts_20230831.dll" "C:\Program Files\PHP\v8.3\ext\php_whatap.dll"

Creating whatap.ini or Editing php.ini​

When Scan Directory Exists​

Create whatap.ini in the Scan Directory detected by php --ini.

REM Example: Scan for additional .ini files in: C:\PHP\conf.d
notepad "C:\PHP\conf.d\whatap.ini"

whatap.ini

extension=php_whatap.dll
When Scan Directory Does Not Exist​

Add configuration directly to php.ini:

REM Example: Loaded Configuration File: C:\PHP\php.ini
notepad "C:\PHP\php.ini"

Add to php.ini

[whatap]
extension=php_whatap.dll

Editing whatap.ini​

Edit the configuration file located at C:\Program Files\WhaTap\PHP\whatap.ini:

whatap.license=your_access_key
whatap.server.host=13.124.11.223
whatap.app_name=APHP
whatap.app_process_name=httpd.exe

Setting Environment Variables​

Configure the environment variables required by the WhaTap PHP Agent:

REM Required: Installation directory
setx WHATAP_PHP_HOME "C:\Program Files\WhaTap\PHP"

REM Required: Configuration file name
setx WHATAP_PHP_CONFIG "whatap.ini"

REM Optional: License key
REM setx WHATAP_LICENSE "your_access_key"

REM Optional: Server host
REM setx WHATAP_SERVER_HOST "13.124.11.223"

Environment variables automatically set by the installer

VariableDescriptionWhen SetDefault
WHATAP_PHP_HOMEInstallation directoryAlwaysC:\Program Files\WhaTap\PHP
WHATAP_PHP_CONFIG_HOMEDirectory of whatap.iniAlwaysC:\Program Files\WhaTap\PHP
WHATAP_PHP_CONFIGwhatap.ini file nameAlwayswhatap.ini
WHATAP_DATETIME_MODETime mode (Windows only)AlwaysWINDOWS
WHATAP_PHP_BINPath to php.exeWhen PHP is detected(detected)
WHATAP_PHP_DIRPHP installation directoryWhen PHP is detected(detected)
WHATAP_PHP_API_VERSIONPHP API versionWhen PHP is detected(detected)
WHATAP_PHP_EXTENSION_DIRPHP extension directoryWhen PHP is detected(detected)
WHATAP_PHP_INI_FILEphp.ini pathWhen PHP is detected(detected)
WHATAP_PHP_THREAD_SAFETYenabled/disabledWhen PHP is detected(detected)

Optional user-set environment variables

VariableDescriptionPriorityDefault
WHATAP_LICENSELicense keyEnv > INI-
WHATAP_SERVER_HOSTServer hostEnv > INI-
Note

setx writes permanent environment variables.
Reload your terminal or restart services for changes to apply.
For system-wide variables:

setx WHATAP_PHP_HOME "C:\Program Files\WhaTap\PHP" /M

Registering and Starting the Service​

sc create "WhaTap PHP" binPath="C:\Program Files\WhaTap\PHP\whatap_php.exe" start=auto
net start "WhaTap PHP"

REM Restart web server
net stop Apache2.4 && net start Apache2.4
REM or
iisreset

Checking Runtime Environment​

Collecting PHP Environment Information​

php -v > php_version.txt
php -i > phpinfo.txt
php -m > modules.txt
php --ini > ini.txt

Network Connectivity Test​

Test-NetConnection -ComputerName 13.124.11.223 -Port 6600
telnet 13.124.11.223 6600
tracert 13.124.11.223

Checking Processes​

tasklist | findstr whatap
tasklist | findstr php
netstat -ano | findstr 6600

Additional Troubleshooting​

Unable to Detect Additional PHP ini Scan Directory​

If PHP was compiled without the --with-config-file-scan-dir=PATH option, the additional ini scan directory will not be detected, resulting in missing configuration loading.

How to Check​

  • Linux/FreeBSD
$ sudo php -i | grep '.ini files'

Scan this dir for additional .ini files => (none)
  • Windows
php --ini

How to Fix​

Append the contents of whatap.ini to the end of the php.ini file.

Linux​
$ php -i | grep 'php.ini'

Loaded Configuration File => /etc/php.ini

$ sudo vi php.ini

# Add at the end of the file
[whatap]
;Enable whatap extension module
extension=whatap.so
whatap.ext.error_enabled=true
whatap.ext.exception_enabled=true
whatap.trace_user_enabled=true
whatap.trace_user_using_ip=false

For all other options, refer to /usr/whatap/php/whatap.ini.

Windows​
REM Append whatap.ini content to php.ini
type "C:\Program Files\WhaTap\PHP\template.ini" >> C:\PHP\php.ini

REM Or edit manually
notepad C:\PHP\php.ini
  • Content to append to php.ini (Windows example)
[whatap]
extension=php_whatap.dll

# For additional whatap.ini settings, see C:\Program Files\WhaTap\PHP\whatap.ini

Setting Environment Variable for whatap-php Service​

Set the whatap.ini directory path to the $WHATAP_CONFIG_HOME environment variable.

If PHP cannot detect the additional ini scan directory, set the path where you created whatap.ini (e.g., /usr/whatap/php).

$ sudo vi /etc/init.d/whatap-php

export WHATAP_CONFIG_HOME=      # Path to whatap.ini (/etc/php.d)

Restart Services​

  • Restart Apache and PHP-FPM services
  • Restart whatap-php service

Error: Not found PHP API​

This occurs when the PHP CLI command cannot be located.

Verify the correct location of the PHP CLI, then complete the steps in
Manual Installation of PHP Extension Module and whatap-php Service.

Linux​
Check PHP API version
$ sudo php -i | grep 'PHP API'

PHP API => 20100412
Windows​
REM Check PHP path
where php

REM Add PHP path to environment PATH
setx PATH "%PATH%;C:\PHP"

REM Or add manually via system environment variables
sysdm.cpl → Advanced → Environment Variables → Edit PATH

PHP ini Directory Not Found​

Error: Not found PHP ini directory

This issue occurs when PHP cannot detect the value of the Scan this dir for additional .ini files field.
If PHP was compiled without the --with-config-file-scan-dir=PATH option, this information will not appear.

Check the correct location of the PHP CLI, then proceed with
Manual setup of PHP extension module and whatap-php service.

How to Check​

Use the following commands to verify whether PHP recognizes an additional ini directory.

Linux/FreeBSD​
$ sudo php -i | grep '.ini files'

Scan this dir for additional .ini files => (none)
Windows​
php --ini

Configuration File (php.ini) Path: /etc/php
Loaded Configuration File:         /etc/php/php.ini
Scan for additional .ini files in: (none)
Additional .ini files parsed:      (none)

How to Fix​

If no additional ini directory is configured, merge the whatap.ini content directly into php.ini.

Windows​
REM Append whatap.ini content to php.ini
type "C:\Program Files\WhaTap\PHP\template.ini" >> C:\PHP\php.ini

REM Or edit manually
notepad C:\PHP\php.ini

Content to add into php.ini

[whatap]
extension=php_whatap.dll

; Refer to C:\Program Files\WhaTap\PHP\whatap.ini for additional settings

Response Time Heatmap Not Displayed​

You may see CPU and memory graphs, but the response time distribution (heatmap) does not appear.
This occurs in the following cases:

  • The agent is connected to the collector, but the tracer is not properly applied to the PHP extension module.
  • Apache or PHP-FPM was not restarted after configuration changes.

  1. Check whether the PHP module is loaded.

    • Linux/FreeBSD
    $ sudo php -m

    [PHP Modules]
    bz2
    calendar
    Core
    ctype
    curl
    date
    …
    whatap               # Verify that the WhaTap module is loaded
    …
    [Zend Modules]
    • Windows
    php -m | findstr whatap
    • Example (normal output)
    whatap

  2. Restart the web service.

    • Windows
    REM Apache
    net stop Apache2.4 && net start Apache2.4

    REM IIS
    iisreset

  3. Check the extension directory.

    • Windows
    REM Check PHP extension directory
    php -i | findstr extension_dir
    REM Example output: extension_dir => C:\PHP\ext

    REM Verify php_whatap.dll exists (use the directory confirmed above)
    dir "C:\PHP\ext\php_whatap.dll"

    If the file does not exist, copy it manually (use the directory confirmed above).

    REM Check PHP API version
    php -i | findstr "PHP API"
    REM Example: PHP API => 20230831

    REM Check Thread Safety
    php -i | findstr "Thread Safety"
    REM Example: Thread Safety => disabled

    REM Copy the appropriate DLL (use the correct extension_dir path)
    copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_20230831.dll" "C:\PHP\ext\php_whatap.dll"

  4. Check the PHP configuration file.
    Make sure the path of whatap.so or whatap.ini matches your PHP environment.

    • Windows
    php --ini

  5. Check the logs.

    • Windows
    REM Installation log
    type "C:\Program Files\WhaTap\PHP\logs\whatap-install.log"

    REM Latest boot log
    dir "C:\Program Files\WhaTap\PHP\logs\whatap-boot-*.log" /O-D
Note

Check the following items:
PHP CLI Path,
PHP Extension Module Path,
PHP Additional ini Path.

Segmentation fault, Sig bus Error​

If an error occurs after applying PHP monitoring, check the Apache or PHP-FPM error log.

Check whether the error log contains messages such as segmentation fault or sig bus.
These errors often appear together with messages like kill child process, exit child, or exit process.

If these errors occur, it indicates a conflict with the PHP extension module whatap.so.
Disable the PHP extension module whatap.so and restart Apache or PHP-FPM.

In an environment that does not affect the service, enable the Core dump configuration for Apache and PHP-FPM, then reload whatap.so.
If an error occurs afterward, a dump file will be generated.
Analyze the dump file using gdb to identify the cause.

Disable Module & Check Logs​

Disable the module first and check the logs to identify the issue.

Windows​

Disable Test

REM Temporarily disable php_whatap.dll
ren "C:\PHP\conf.d\whatap.ini" "whatap.ini.disabled"

REM Restart web server
net stop Apache2.4 && net start Apache2.4

Check error logs

  • Apache
type "C:\Apache24\logs\error.log"
  • IIS
REM Check Event Viewer
eventvwr.msc
→ Windows Logs → Application

Core Dump Configuration​

  1. Grant permissions to the directory where the dump file will be stored:
chmod 0777 /home/httpd-core
  1. Apply system settings:
ulimit -c unlimited
sysctl fs.suid_dumpable=2
sysctl kernel.core_uses_pid=0
sysctl kernel.core_pattern='| /home/httpd-core/core-%e.%p'

Apache​

  1. Add CoreDumpDirectory to Apache configuration:
vi /etc/httpd/conf/httpd.conf

CoreDumpDirectory /home/httpd-core

  1. Restart Apache to apply the setting.

  2. When an error occurs, a dump file is generated.
    Analyze the file using gdb and use bt full to print the full stack trace:

# gdb /usr/sbin/httpd /home/httpd-core/core-httpd.31832
...

> bt full

PHP-FPM​

  1. Configure rlimit_core in the FPM configuration file:
rlimit_core = unlimited

  1. Restart PHP-FPM.

  2. When an error occurs, a dump file will be created.
    Analyze it using gdb with bt full:

# gdb /usr/sbin/php-fpm /home/httpd-core/core-php-fpm.31832
...

> bt full
Last updated on