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=           # 웹서버 구분 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=    # 와탭 라이브러리 경로 및 파일명
                              # (/usr/whatap/php/modules/x64/whatap_20100412.so)]

$WHATAP_PHP_EXT_HOME 환경변수에 PHP 확장 모듈 경로를 설정하세요.
$WHATAP_PHP_EXT_SRC 환경변수에 와탭 라이브러리 전체 파일 경로를 설정하세요.

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 위에서 확인한 extension_dir 사용
REM 예: extension_dir => C:\PHP\ext

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"

예시

REM PHP 8.3 (API 20230831) NTS, extension_dir = C:\PHP\ext
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, extension_dir = C:\Program Files\PHP\v8.3\ext
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 파일을 생성합니다.

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

whatap.ini

extension=php_whatap.dll

Scan Directory가 없는 경우

php --ini에서 확인한 php.ini 파일에 직접 추가합니다.

REM 예: Loaded Configuration File: C:\PHP\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

환경 변수 설정

WhaTap PHP 에이전트가 사용하는 환경 변수를 설정합니다.

REM 필수: WhaTap PHP 설치 디렉토리
setx WHATAP_PHP_HOME "C:\Program Files\WhaTap\PHP"

REM 필수: whatap.ini 파일 이름 또는 경로
setx WHATAP_PHP_CONFIG "whatap.ini"

REM 선택: 라이센스 키 (whatap.ini 대신 환경 변수로 지정 가능)
REM setx WHATAP_LICENSE "your_access_key"

REM 선택: 수집 서버 주소 (whatap.ini 대신 환경 변수로 지정 가능)
REM setx WHATAP_SERVER_HOST "13.124.11.223"

설치 프로그램이 자동으로 설정하는 환경 변수

환경 변수	설명	설정 시점	기본값
`WHATAP_PHP_HOME`	WhaTap PHP 설치 디렉토리	항상	`C:\Program Files\WhaTap\PHP`
`WHATAP_PHP_CONFIG_HOME`	whatap.ini 파일이 위치한 디렉토리	항상	`C:\Program Files\WhaTap\PHP`
`WHATAP_PHP_CONFIG`	whatap.ini 파일 이름	항상	`whatap.ini`
`WHATAP_DATETIME_MODE`	시간 모드 (Windows 전용)	항상	`WINDOWS`
`WHATAP_PHP_BIN`	php.exe 전체 경로	PHP 감지 시	(감지된 경로)
`WHATAP_PHP_DIR`	PHP 설치 디렉토리	PHP 감지 시	(감지된 경로)
`WHATAP_PHP_API_VERSION`	PHP API 버전 (예: 20230831)	PHP 감지 시	(감지된 버전)
`WHATAP_PHP_EXTENSION_DIR`	PHP extension 디렉토리	PHP 감지 시	(감지된 경로)
`WHATAP_PHP_INI_FILE`	php.ini 파일 전체 경로	PHP 감지 시	(감지된 경로)
`WHATAP_PHP_THREAD_SAFETY`	Thread Safety (enabled/disabled)	PHP 감지 시	(감지된 값)

사용자가 선택적으로 설정 가능한 환경 변수(whatap.ini 대신 사용)

환경 변수	설명	우선순위	기본값
`WHATAP_LICENSE`	라이센스 키	환경변수 > whatap.ini	-
`WHATAP_SERVER_HOST`	수집 서버 주소	환경변수 > whatap.ini	-

노트

참고

setx 명령은 영구적으로 환경 변수를 설정합니다. (재부팅 후에도 유지)
설정 후 새로운 명령 프롬프트나 서비스 재시작 필요
시스템 전체 환경 변수로 설정하려면 관리자 권한으로 실행 후 /M 옵션 사용
```
setx WHATAP_PHP_HOME "C:\Program Files\WhaTap\PHP" /M
```

서비스 등록 및 시작

REM 서비스 등록
sc create "WhaTap PHP" binPath="C:\Program Files\WhaTap\PHP\whatap_php.exe" start=auto

REM 서비스 시작
net start "WhaTap PHP"

REM 웹 서버 재시작
net stop Apache2.4 && net start Apache2.4
REM 또는
iisreset

운영 환경 점검

PHP 환경 정보 수집

Windows

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

네트워크 연결 테스트

Windows

# Windows PowerShell
Test-NetConnection -ComputerName 13.124.11.223 -Port 6600

# Windows CMD
telnet 13.124.11.223 6600
tracert 13.124.11.223

프로세스 상태 확인

Windows

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

추가 문제 해결

PHP 추가 ini 설정 경로 확인 불가

PHP 컴파일(Compile) 설치 옵션 --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

# whatap.ini 설정은 C:\Program Files\WhaTap\PHP\whatap.ini 참조

whatap-php 서비스(Service) 환경 변수 설정

$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

; whatap.ini 설정은 C:\Program Files\WhaTap\PHP\whatap.ini 참조

응답 시간 분포도에 트랜잭션이 표시되지 않음

CPU와 Memory 그래프를 볼 수 있지만 응답 시간 분포도 즉 히트맵을 볼 수 없는 현상은 다음과 같은 경우에 발생합니다.

에이전트가 수집 서버와 정상적으로 연결되었으나 트레이서가 정상적으로 PHP 확장 모듈에 적용되지 않은 경우
설정 후 Apache 및 PHP-FPM 서비스를 재시작하지 않은 경우

PHP 모듈 로드를 확인하세요.

Linux/FreeBSD

$ sudo php -m

[PHP Modules]
bz2
calendar
Core
ctype
curl
date
…
whatap               # 와탭 모듈 로드 확인
…
[Zend Modules]

Windows

php -m | findstr whatap

예시. 정상 출력

whatap

웹 서비스를 재시작하세요.

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 복사 (확인한 extension_dir 경로 사용)
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 확장 모듈 경로, PHP 추가 ini 설정 경로 항목들을 확인하세요.

Segmentation fault, Sig bus 오류

PHP 모니터링을 적용한 후 서비스에 오류가 발생할 경우 Apache 또는 PHP-FPM의 error log를 확인하세요.

error log 내용 중 segmentation fault, sig bus 등의 오류 문구가 있는지 확인하세요. kill child process, exit child, exit process 등의 문구와 같이 발생합니다.

해당 오류가 발생하는 경우는 PHP Extension 모듈인 whatap.so 모듈에서 충돌이 발생하는 것으로 볼 수 있습니다. PHP Extension 모듈인 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 웹 서버 재시작
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 conf 에 CoreDumpDirectory 항목을 설정하세요.

vi /etc/httpd/conf/httpd.conf

CoreDumpDirectory /home/httpd-core

Apache를 재시작하면 설정이 완료됩니다.
오류가 발생하면 dump 파일이 생성됩니다. 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 파일이 생성됩니다. 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 환경 정보 수집​

네트워크 연결 테스트​

프로세스 상태 확인​

추가 문제 해결​

PHP 추가 ini 설정 경로 확인 불가​

확인하기​

해결하기​

Linux​

Windows​

whatap-php 서비스(Service) 환경 변수 설정​

서비스 재시작​

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 환경 정보 수집

네트워크 연결 테스트

프로세스 상태 확인

추가 문제 해결

PHP 추가 ini 설정 경로 확인 불가

확인하기

해결하기

Linux

Windows

whatap-php 서비스(Service) 환경 변수 설정

서비스 재시작

Error: Not found PHP API

Linux

Windows

PHP ini 디렉토리를 찾을 수 없음

확인하기

Linux/FreeBSD

Windows

해결하기

Windows

응답 시간 분포도에 트랜잭션이 표시되지 않음

Segmentation fault, Sig bus 오류

모듈 비활성화 및 로그 확인

Windows

Core Dump 설정

Apache

PHP-FPM