PHPエージェントのトラブルシューティング

インストールおよび設定エラーのトラブルシューティング

WhaTap PHP エージェントのインストールおよび設定時に発生する可能性のある問題を診断・解決する方法を説明します。

Linux/FreeBSD

PHP拡張モジュールおよびwhatap-phpサービスの手動設定

PHP拡張モジュールとwhatap-phpサービスのインストールおよびオプションのインストール(install.sh)が正しく動作しない場合の手動で設定する方法を説明します。PHPコンパイルのインストールなど、環境情報が確認できない場合に使用してください。

whatap.ini作成

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

# 上部に内容を追加
; Enable whatap extension module
extension=whatap.so
whatap.license=            # 発行されたアクセスキー
whatap.server.host=        # #発行されたサーバーIP
whatap.app_name=           # Webサーバー区分APHP、FPHP (apache : APHP, php-fpm : FPHP)
whatap.app_process_name=   # apache, php-fpmのプロセス名(httpd,php-fpm)

設定	説明
whatap.license	*プロジェクトメニュー* > 管理 > *エージェントインストール*ページで発行されたアクセスキーを確認できます。
whatap.server.host	*プロジェクトメニュー* > 管理 > *エージェントインストール*ページで発行されたサーバーのIPを確認できます。
whatap.app_name	Apacheサーバーは、`APHP`を使用し、php-fpmは、`FPHP`を使用します。
whatap.app_process_name	Apacheまたはphp-fpmで実行可能なプロセス名を設定して正しいプロセス名を入力すると、そのプロセスに使用されるメモリが収集されます。例として、`httpd`、`apache2`、`php-fpm`などが挙げられます。

PHPコマンド(CLI) パスの確認

$ which php

/usr/bin/php

whatap-phpのサービス環境変数の設定

$WHATAP_PHP_BIN環境変数にPHP CLIコマンドパスを設定します。

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

export WHATAP_PHP_BIN=    # PHP コマンドの場所(/usr/bin/php)

PHP APIバージョンの確認

$WHATAP_PHP_BIN環境変数にPHP CLIコマンドパスを設定します。

$ sudo php -i | grep 'PHP API'

PHP API => 20100412

PHP ZTS(Zend Thread Safe) サポート有無の確認

$ sudo apachectl -V | grep MPM

Server MPM: Prefork      # ZTSサポート無し
Server MPM: Worker       # ZTSサポート

$ sudo php-fpm -i | grep Thread

Thread Safety => disabled       # ZTS非対応
Thread Safety => enabled       	# ZTS対応

PHP拡張モジュールのパスを確認して設定

PHP拡張モジュールパスの確認

$ sudo php -i | grep extension_dir

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

PHP拡張モジュールの設定

PHP APIバージョン、PHP ZTSのサポートを確認して、環境に適したライブラリを選択します。PHP拡張モジュール(PHP Extension module) パスにwhatap.soファイル名をコピーします。

PHP ZTSにサポートされている場合 - whatap_zts_[PHP APIバージョン].so

PHP ZTSにサポートされていない場合 - whatap[PHP APIバージョン].so_

# PHP ZTSをサポートしていない場合の例
$ sudo cp /usr/whatap/php/modules/x64/whatap_20100412.so /usr/lib64/php/modules/whatap.so

whatap-phpのサービス環境変数の設定

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

export WHATAP_PHP_EXT_HOME=   # PHP Extensionパス(/usr/lib64/php/modules)
export WHATAP_PHP_EXT_SRC=    # WhaTapライブラリパスおよびファイル名
                              # (/usr/whatap/php/modules/x64/whatap_20100412.so)]

$WHATAP_PHP_EXT_HOME環境変数にPHP拡張モジュールパスを設定します。
$WHATAP_PHP_EXT_SRC環境変数にWhaTapライブラリ全体のファイルパスを設定します。

whatap.ini設定

PHP追加のini設定パスを確認します。

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

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

whatap.iniをそのパスにコピーします。

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

Windows

PHP 拡張モジュールおよび WhaTap PHP サービスの手動設定

PHP 拡張モジュールや whatap-php サービスが正しくインストールされなかった場合、または選択インストール (install.sh) が正常に実行されなかった場合は、以下の手動設定手順を行います。

PHP 環境情報の確認

PHP の環境情報を確認します。

REM PHP API バージョン確認
php -i | findstr "PHP API"

REM Thread Safety 確認
php -i | findstr "Thread Safety"

REM Extension ディレクトリ確認
php -i | findstr extension_dir

REM PHP 設定ファイル確認
php --ini

例

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)

php_whatap.dll のコピー

確認した extension_dir に DLL をコピーします。

REM Non-ZTS バージョン
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_[API_VERSION].dll" "C:\PHP\ext\php_whatap.dll"

REM ZTS バージョン
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_zts_[API_VERSION].dll" "C:\PHP\ext\php_whatap.dll"

例

copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_20230831.dll" "C:\PHP\ext\php_whatap.dll"
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_zts_20230831.dll" "C:\Program Files\PHP\v8.3\ext\php_whatap.dll"

whatap.ini の作成または php.ini の修正

Scan Directory がある場合

php --ini で確認された Scan Directory に whatap.ini を作成します。

notepad "C:\PHP\conf.d\whatap.ini"

whatap.ini

extension=php_whatap.dll

Scan Directory がない場合

php.ini に直接追加します。

notepad "C:\PHP\php.ini"

php.ini に追加

[whatap]
extension=php_whatap.dll

whatap.ini の設定

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

環境変数の設定

setx WHATAP_PHP_HOME "C:\Program Files\WhaTap\PHP"
setx WHATAP_PHP_CONFIG "whatap.ini"
REM setx WHATAP_LICENSE "your_access_key"
REM setx WHATAP_SERVER_HOST "13.124.11.223"

インストーラーが自動設定する環境変数

サービス登録と開始

sc create "WhaTap PHP" binPath="C:\Program Files\WhaTap\PHP\whatap_php.exe" start=auto
net start "WhaTap PHP"
net stop Apache2.4 && net start Apache2.4
iisreset

運用環境チェック

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

Test-NetConnection -ComputerName 13.124.11.223 -Port 6600

telnet 13.124.11.223 6600
tracert 13.124.11.223

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

追加トラブルシューティング

PHP 追加 ini スキャンディレクトリを認識できない問題

PHP を --with-config-file-scan-dir=PATH オプションなしでコンパイルした場合、追加 ini スキャンディレクトリが検出されず、設定ファイルが読み込まれない問題が発生します。

確認方法

Linux/FreeBSD

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

Scan this dir for additional .ini files => (none)

Windows

php --ini

解決方法

whatap.ini の内容を php.ini の最後に追加します。

Linux

$ php -i | grep 'php.ini'

Loaded Configuration File => /etc/php.ini

$ sudo vi php.ini

# ファイルの最後に追加
[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

その他の設定は /usr/whatap/php/whatap.ini を参照してください。

Windows

REM whatap.ini の内容を php.ini に追加
type "C:\Program Files\WhaTap\PHP\template.ini" >> C:\PHP\php.ini

REM または手動で編集
notepad C:\PHP\php.ini

php.ini に追加する内容（Windows例）

[whatap]
extension=php_whatap.dll

# 詳細設定は C:\Program Files\WhaTap\PHP\whatap.ini を参照

whatap-php サービス用の環境変数設定

$WHATAP_CONFIG_HOME 環境変数に whatap.ini のパスを設定します。

PHP が追加 ini ディレクトリを検出できない場合は、whatap.ini を作成した /usr/whatap/php を設定してください。

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

export WHATAP_CONFIG_HOME=      # whatap.ini のディレクトリ（例：/etc/php.d）

サービス再起動

Apache および PHP-FPM の再起動
whatap-php サービスの再起動

Error: Not found PHP API

PHP CLI コマンドを見つけられない場合に発生します。

PHP CLI の位置を正しく確認し、
PHP 拡張モジュールおよび whatap-php サービスの手動設定を実行してください。

Linux

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

PHP API => 20100412

Windows

REM PHP の場所を確認
where php

REM PATH 環境変数に PHP のパスを追加
setx PATH "%PATH%;C:\PHP"

REM またはシステム環境変数で直接追加
sysdm.cpl → 詳細設定 → 環境変数 → PATH 編集

PHP ini ディレクトリが見つからない

Error: Not found PHP ini directory

PHP が Scan this dir for additional .ini files の値を取得できない場合に発生します。
PHP を --with-config-file-scan-dir=PATH オプションなしでコンパイルした場合、この情報は出力されません。

PHP CLI の場所を正しく確認し、
PHP 拡張モジュールと whatap-php サービスの手動設定を実施してください。

確認方法

以下のコマンドで PHP が追加 ini ディレクトリを認識しているか確認します。

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)

解決方法

追加 ini ディレクトリが設定されていない場合、whatap.ini の内容を php.ini に直接追加します。

Windows

REM whatap.ini の内容を php.ini に追加
type "C:\Program Files\WhaTap\PHP\template.ini" >> C:\PHP\php.ini

REM または手動で編集
notepad C:\PHP\php.ini

php.ini に追加する内容

[whatap]
extension=php_whatap.dll

; 詳細設定は C:\Program Files\WhaTap\PHP\whatap.ini を参照

応答時間ヒットマップが表示されない

CPU とメモリのグラフは見えるが、応答時間分布図（ヒットマップ）が表示されない場合、以下の原因が考えられます。

エージェントは収集サーバーに正常接続しているが、トレーサーが PHP 拡張モジュールに適用されていない
設定変更後に Apache または PHP-FPM を再起動していない

PHP モジュールの読み込みを確認します。

Linux/FreeBSD

$ sudo php -m

[PHP Modules]
bz2
calendar
Core
ctype
curl
date
…
whatap               # WhaTap モジュール読み込み確認
…
[Zend Modules]

Windows

php -m | findstr whatap

正常出力例

whatap

Web サービスを再起動します。

Windows

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

REM IIS
iisreset

拡張モジュールの配置場所を確認します。

Windows

REM PHP 拡張ディレクトリ確認
php -i | findstr extension_dir
REM 出力例: extension_dir => C:\PHP\ext

REM php_whatap.dll の存在確認
dir "C:\PHP\ext\php_whatap.dll"

ファイルが無い場合は手動でコピーします（確認した extension_dir を使用）。

REM PHP API バージョン確認
php -i | findstr "PHP API"
REM 例: PHP API => 20230831

REM Thread Safety 確認
php -i | findstr "Thread Safety"
REM 例: Thread Safety => disabled

REM 適切な DLL をコピー
copy "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_20230831.dll" "C:\PHP\ext\php_whatap.dll"

PHP 設定ファイルを確認します。
whatap.so または whatap.ini のパスが PHP 環境と一致しているか確認します。
- Windows
```
php --ini
```

ログを確認します。

Windows

REM インストールログ
type "C:\Program Files\WhaTap\PHP\logs\whatap-install.log"

REM 最新ブートログ
dir "C:\Program Files\WhaTap\PHP\logs\whatap-boot-*.log" /O-D

ノート

以下の項目を確認してください：
PHP CLI パス、
PHP 拡張モジュールパス、
追加 ini パス

Segmentation fault、Sig bus エラー

PHP モニタリングを適用した後にサービスでエラーが発生した場合、Apache または PHP-FPM のエラーログを確認してください。

エラーログの中に segmentation fault、sig bus といったメッセージが含まれていないか確認します。
これらのエラーは kill child process、exit child、exit process などのメッセージと一緒に表示されることがあります。

このエラーが発生する場合、PHP 拡張モジュール whatap.so が衝突している可能性があります。
PHP 拡張モジュール whatap.so を無効化し、Apache または PHP-FPM を再起動してください。

サービスに影響を与えない環境で、Apache と PHP-FPM に Core dump の設定を追加し、再度 whatap.so をロードしてください。
その後エラーが発生すると dump ファイルが生成されます。
生成された dump ファイルを gdb で解析し、原因を特定してください。

モジュール無効化およびログ確認

まずモジュールを無効化し、エラーログを確認します。

Windows

無効化テスト

REM php_whatap.dll を一時的に無効化
ren "C:\PHP\conf.d\whatap.ini" "whatap.ini.disabled"

REM Web サーバー再起動
net stop Apache2.4 && net start Apache2.4

エラーログ確認

Apache

type "C:\Apache24\logs\error.log"

IIS

REM イベントビューアを確認
eventvwr.msc
→ Windows ログ → アプリケーション

Core Dump 設定

dump ファイルを保存するディレクトリの権限を設定：

chmod 0777 /home/httpd-core

システム設定を適用：

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

Apache 設定ファイルに CoreDumpDirectory を追加：

vi /etc/httpd/conf/httpd.conf

CoreDumpDirectory /home/httpd-core

Apache を再起動して設定を反映。
エラーが発生すると dump ファイルが生成されます。
gdb を使って解析し、bt full コマンドで完全なスタック情報を確認します：

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

> bt full

PHP-FPM

FPM 設定ファイルで rlimit_core を設定：

rlimit_core = unlimited

PHP-FPM を再起動。
エラー発生時、dump ファイルが生成されます。
gdb で解析し、bt full でスタックトレースを確認します：

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

> bt full

インストールおよび設定エラーのトラブルシューティング​

Linux/FreeBSD​

PHP拡張モジュールおよびwhatap-phpサービスの手動設定​

whatap.ini作成​

PHPコマンド(CLI) パスの確認​

whatap-phpのサービス環境変数の設定​

PHP APIバージョンの確認​

PHP ZTS(Zend Thread Safe) サポート有無の確認​

PHP拡張モジュールのパスを確認して設定​

PHP拡張モジュールパスの確認​

PHP拡張モジュールの設定​

whatap-phpのサービス環境変数の設定​

whatap.ini設定​

Windows​

PHP 拡張モジュールおよび WhaTap PHP サービスの手動設定​

PHP 環境情報の確認​

php_whatap.dll のコピー​

whatap.ini の作成または php.ini の修正​

Scan Directory がある場合​

Scan Directory がない場合​

whatap.ini の設定​

環境変数の設定​

サービス登録と開始​

運用環境チェック​

追加トラブルシューティング​

PHP 追加 ini スキャンディレクトリを認識できない問題​

確認方法​

解決方法​

Linux​

Windows​

whatap-php サービス用の環境変数設定​

サービス再起動​

Error: Not found PHP API​

Linux​

Windows​

PHP ini ディレクトリが見つからない​

確認方法​

Linux/FreeBSD​

Windows​

解決方法​

Windows​

応答時間ヒットマップが表示されない​

Segmentation fault、Sig bus エラー​

モジュール無効化およびログ確認​

Windows​

Core Dump 設定​

Apache​

PHP-FPM​

インストールおよび設定エラーのトラブルシューティング

Linux/FreeBSD

PHP拡張モジュールおよびwhatap-phpサービスの手動設定

whatap.ini作成

PHPコマンド(CLI) パスの確認

whatap-phpのサービス環境変数の設定

PHP APIバージョンの確認

PHP ZTS(Zend Thread Safe) サポート有無の確認

PHP拡張モジュールのパスを確認して設定

PHP拡張モジュールパスの確認

PHP拡張モジュールの設定

whatap-phpのサービス環境変数の設定

whatap.ini設定

Windows

PHP 拡張モジュールおよび WhaTap PHP サービスの手動設定

PHP 環境情報の確認

php_whatap.dll のコピー

whatap.ini の作成または php.ini の修正

Scan Directory がある場合

Scan Directory がない場合

whatap.ini の設定

環境変数の設定

サービス登録と開始

運用環境チェック

追加トラブルシューティング

PHP 追加 ini スキャンディレクトリを認識できない問題

確認方法

解決方法

Linux

Windows

whatap-php サービス用の環境変数設定

サービス再起動

Error: Not found PHP API

Linux

Windows

PHP ini ディレクトリが見つからない

確認方法

Linux/FreeBSD

Windows

解決方法

Windows

応答時間ヒットマップが表示されない

Segmentation fault、Sig bus エラー

モジュール無効化およびログ確認

Windows

Core Dump 設定

Apache

PHP-FPM