본문으로 건너뛰기

Windows

WhaTap PHP 모니터링 에이전트를 Windows 시스템에 설치하는 방법을 설명합니다. InnoSetup 기반 설치 프로그램을 통해 GUI 또는 CLI 방식으로 간편하게 설치할 수 있습니다.

노트

Windows 지원은 v2.13.0부터 제공됩니다.

  • 대상 OS: Windows Server 2016+, Windows 10+

  1. WhaTap PHP Windows 설치 프로그램을 다운로드합니다.

    https://repo.whatap.io/windows/whatap_php_setup.exe

    https://repo.whatap.io/windows/whatap_php_setup.zip

    또는 WhaTap 콘솔에서 프로젝트 선택한 후, 관리 > 에이전트 설치 > Windows 다운로드에서 설치 프로그램을 받을 수 있습니다.

  2. 설치 프로그램을 실행한 후, PHP 에이전트를 설치합니다. 자동으로 PHP 환경을 감지하거나 수동으로 구성하세요.

    시스템 요구사항 확인
    - Windows Server 2016 이상 또는 Windows 10 이상
    - PHP 7.0 ~ 8.4 (x64 버전)
    - 관리자 권한

  3. 설치 프로그램이 자동으로 다음 작업을 수행합니다.

    • PHP extension module (php_whatap.dll) 설치
    • whatap.ini 설정 파일 생성
    • WhaTap PHP 서비스 등록 및 시작
    • 환경 변수 등록

자동 설치(GUI Mode)​

표준 PHP 설치 환경에서 설치를 권장합니다.

whatap_php_setup.exe

GUI 자동 설치 단계​

  1. Windows 언어 기준으로 언어 자동 선택됩니다.

  2. 설치 모드는 기본 설치(Basic Installation)를 선택합니다.

  3. 라이센스 키를 입력합니다.

    예시: x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1

  4. 서버 호스트를 입력합니다.

    • 기본값: 13.124.11.223 (또는 13.209.172.35)

  5. php.exe 파일을 선택합니다.

    • 일반적인 위치:
      • C:\PHP\php.exe
      • C:\Program Files\PHP\v8.x\php.exe
      • C:\Apache24\php\php.exe

  6. 자동 감지를 확인합니다.

    • PHP 버전(예: 8.2.12)
    • Thread Safety (NTS/ZTS)
    • 아키텍처(x64)
    • Extension 디렉토리

수동 설치(Advanced Installation)​

수동 설치는 다음 경우에 사용합니다.

  • php.exe 파일 경로를 알 수 없는 경우
  • 복잡한 PHP 환경(커스텀 빌드)
  • PHP 설정을 직접 제어해야 하는 경우
whatap_php_setup.exe

GUI 수동 설치 단계​

  1. 설치 모드는 세부 설치(Advanced Installation)로 선택합니다.

  2. 라이센스 키를 입력합니다.

    예시: x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1

  3. 서버 호스트를 입력합니다.

    • 기본값: 13.124.11.223 (또는 13.209.172.35)

  4. PHP 버전를 드롭다운 메뉴에서 선택합니다.

    • 버전: 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4

  5. Thread Safety 옵션을 선택합니다.

    • disabled (NTS): Non-Thread Safe(대부분의 환경에 적합)
    • enabled (ZTS): Zend Thread Safe(Apache Worker/Event MPM)

  6. Scan INI Directory를 입력합니다. (권장)

    • 일반적인 위치:
      • C:\PHP\conf.d\
      • C:\Program Files\PHP\v8.x\conf.d\
    • 없는 경우: 다음 단계에서 php.ini 경로 입력

  7. Extension Directory를 입력합니다.

    • 일반적인 위치:
      • C:\PHP\ext\
      • C:\Program Files\PHP\v8.x\ext\

  8. Scan Directory가 없는 경우, php.ini 경로를 입력합니다.

    • 예시: C:\PHP\php.ini

CLI 수동 설치(VERYSILENT Mode)​

CI/CD 및 Docker 환경에서는 CLI 방식의 자동 설치를 사용할 수 있습니다.

기본 설치 모드(php.exe 경로 제공)​
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /TYPE="basic" ^
  /ACCESSKEY="x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1" ^
  /SERVERHOST="13.124.11.223" ^
  /PHPPATH="C:\PHP\php.exe"
세부 설치 모드(Scan Directory 있는 경우)​
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /TYPE="advanced" ^
  /ACCESSKEY="x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1" ^
  /SERVERHOST="13.124.11.223" ^
  /PHPVERSION="8.3" ^
  /THREADSAFETY="disabled" ^
  /SCANDIR="C:\PHP\conf.d" ^
  /EXTENSIONDIR="C:\PHP\ext"
세부 설치 모드(Scan Directory 없는 경우)​
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /TYPE="advanced" ^
  /ACCESSKEY="x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1" ^
  /SERVERHOST="13.124.11.223" ^
  /PHPVERSION="8.3" ^
  /THREADSAFETY="disabled" ^
  /PHPINIPATH="C:\PHP\php.ini" ^
  /EXTENSIONDIR="C:\PHP\ext"

설치 파라미터​

설치 프로그램이 지원하는 CLI 파라미터 목록입니다.

공통 파라미터​
파라미터설명필수 여부예시
/VERYSILENT완전 자동 설치 (UI 없음)선택/VERYSILENT
/SUPPRESSMSGBOXES모든 메시지 박스 억제선택/SUPPRESSMSGBOXES
/NORESTART설치 후 시스템 재시작 방지선택/NORESTART
/LOG설치 로그 파일 생성선택/LOG="C:\install.log"
/TYPE설치 모드 (basic/advanced)필수/TYPE="basic"
/ACCESSKEYWhaTap 액세스 키필수/ACCESSKEY="x4g2e..."
/SERVERHOSTWhaTap 서버 호스트필수/SERVERHOST="13.124.11.223"
기본 설치 모드 (TYPE="basic") 파라미터​
파라미터설명필수 여부예시
/PHPPATHphp.exe 전체 경로필수/PHPPATH="C:\PHP\php.exe"
세부 설치 모드 (TYPE="advanced") 파라미터​
파라미터설명필수 여부예시
/PHPVERSIONPHP 버전 (7.0-8.4)필수/PHPVERSION="8.3"
/THREADSAFETYThread Safety (enabled/disabled)필수/THREADSAFETY="disabled"
/EXTENSIONDIRPHP 확장 디렉토리 경로필수/EXTENSIONDIR="C:\PHP\ext"
/SCANDIRScan INI Directory 경로 (권장)선택/SCANDIR="C:\PHP\conf.d"
/PHPINIPATHphp.ini 파일 경로선택/PHPINIPATH="C:\PHP\php.ini"
노트

참고
/SCANDIR 또는 /PHPINIPATH 중 하나는 반드시 제공해야 합니다.

배치 스크립트 예시​

기본 설치(Basic Mode)

@echo off
setlocal

:: 설치 변수
set INSTALLER=whatap_php_setup_2.13.0.exe
set ACCESS_KEY=x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1
set SERVER_HOST=13.124.11.223
set PHP_PATH=C:\PHP\php.exe
set LOG_FILE=C:\whatap_install.log

:: 설치 실행
echo Installing WhaTap PHP Agent (Basic Mode)...
%INSTALLER% /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /LOG="%LOG_FILE%" ^
  /TYPE="basic" ^
  /ACCESSKEY="%ACCESS_KEY%" ^
  /SERVERHOST="%SERVER_HOST%" ^
  /PHPPATH="%PHP_PATH%"

if %errorlevel% equ 0 (
    echo Installation completed successfully!
    echo Log file: %LOG_FILE%
) else (
    echo Installation failed with error code: %errorlevel%
    if exist "%LOG_FILE%" type "%LOG_FILE%"
    exit /b %errorlevel%
)

endlocal

세부 설치(Advanced Mode - Scan Directory 있음)

@echo off
setlocal

:: 설치 변수
set INSTALLER=whatap_php_setup_2.13.0.exe
set ACCESS_KEY=x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1
set SERVER_HOST=13.124.11.223
set PHP_VERSION=8.3
set THREAD_SAFETY=disabled
set SCAN_DIR=C:\PHP\conf.d
set EXT_DIR=C:\PHP\ext
set LOG_FILE=C:\whatap_install.log

:: 설치 실행
echo Installing WhaTap PHP Agent (Advanced Mode with Scan Directory)...
%INSTALLER% /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /LOG="%LOG_FILE%" ^
  /TYPE="advanced" ^
  /ACCESSKEY="%ACCESS_KEY%" ^
  /SERVERHOST="%SERVER_HOST%" ^
  /PHPVERSION="%PHP_VERSION%" ^
  /THREADSAFETY="%THREAD_SAFETY%" ^
  /SCANDIR="%SCAN_DIR%" ^
  /EXTENSIONDIR="%EXT_DIR%"

if %errorlevel% equ 0 (
    echo Installation completed successfully!
    echo Log file: %LOG_FILE%
) else (
    echo Installation failed with error code: %errorlevel%
    if exist "%LOG_FILE%" type "%LOG_FILE%"
    exit /b %errorlevel%
)

endlocal

세부 설치(Advanced Mode - php.ini 직접 수정)

@echo off
setlocal

:: 설치 변수
set INSTALLER=whatap_php_setup_2.13.0.exe
set ACCESS_KEY=x4g2e21g8a9m-z2glc38mmd1fa-x2vunh5jms4u1
set SERVER_HOST=13.124.11.223
set PHP_VERSION=8.3
set THREAD_SAFETY=disabled
set PHP_INI=C:\PHP\php.ini
set EXT_DIR=C:\PHP\ext
set LOG_FILE=C:\whatap_install.log

:: 설치 실행
echo Installing WhaTap PHP Agent (Advanced Mode with php.ini)...
%INSTALLER% /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /LOG="%LOG_FILE%" ^
  /TYPE="advanced" ^
  /ACCESSKEY="%ACCESS_KEY%" ^
  /SERVERHOST="%SERVER_HOST%" ^
  /PHPVERSION="%PHP_VERSION%" ^
  /THREADSAFETY="%THREAD_SAFETY%" ^
  /PHPINIPATH="%PHP_INI%" ^
  /EXTENSIONDIR="%EXT_DIR%"

if %errorlevel% equ 0 (
    echo Installation completed successfully!
    echo Log file: %LOG_FILE%
) else (
    echo Installation failed with error code: %errorlevel%
    if exist "%LOG_FILE%" type "%LOG_FILE%"
    exit /b %errorlevel%
)

endlocal

설치 후 작업​

주의

설정 변경사항을 적용하려면 웹 서버를 재시작해야 합니다.

Apache 2.4 재시작​

# 서비스로 실행 중인 경우
net stop Apache2.4
net start Apache2.4

# 또는 서비스 관리자 사용
services.msc → Apache2.4 → 재시작

IIS 재시작​

# 관리자 권한 명령 프롬프트
iisreset

# 또는 IIS 관리자
인터넷 정보 서비스(IIS) 관리자 → 서버 → 재시작

설치 확인​

1. PHP 모듈 로드 확인​

php -m | findstr whatap

정상 출력

whatap

2. 서비스 상태 확인​

sc query "WhaTap PHP"

정상 출력

SERVICE_NAME: WhaTap PHP
STATE : 4 RUNNING

서비스 관리자 실행

services.msc
  • WhaTap PHP 서비스의 상태가 '실행 중'인지 확인하세요.

3. 로그 확인​

C:\Program Files\WhaTap\PHP\logs\
├── whatap_php.log      # 메인 로그
└── error.log           # 에러 로그

4. WhaTap 콘솔 확인​

  1. https://service.whatap.io 에 로그인합니다.

  2. 프로젝트를 선택합니다.

  3. 관리 > 에이전트 설정으로 이동합니다.

  4. 설치한 서버가 목록에 표시되는지 확인합니다.

업데이트​

노트

업데이트 전, 웹 서버를 중지하는 것을 권장합니다.

자동 업데이트(권장)​

설치 프로그램이 WHATAP_PHP_HOME 환경 변수를 통해 기존 설치를 자동으로 감지하고 업데이트합니다.

업데이트 시 자동 처리 항목

  • 기존 whatap.ini 설정 보존 (라이센스, 서버 주소, 커스텀 설정 유지)

  • 기존 php.ini의 [whatap] 섹션 보존

  • 에이전트 파일만 교체 (whatap_php.exe, php_whatap.dll)

  • WhaTap PHP 서비스 자동 재시작

  • 환경 변수 자동 업데이트

GUI 방식 업데이트​
# 1. 웹 서버 중지 (권장)
net stop Apache2.4
# 또는
iisreset /stop

# 2. 새 버전 설치 프로그램 실행
whatap_php_setup.exe

# 설치 프로그램이 자동으로:
# - 기존 설치 감지
# - 업데이트 모드로 진행
# - 설정 파일 보존
# - 파일만 교체

# 3. 웹 서버 시작
net start Apache2.4
# 또는
iisreset /start
CLI 방식 자동 업데이트​

기존 설치가 있으면 설치 프로그램이 자동으로 업데이트 모드로 실행됩니다.

# 1. 웹 서버 중지 (권장)
net stop Apache2.4

# 2. 업데이트 실행 (파라미터 없이 실행)
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

# 설치 프로그램이 WHATAP_PHP_HOME을 확인하여 자동 업데이트

# 3. 웹 서버 시작
net start Apache2.4

배치 스크립트 (자동 업데이트)

@echo off
echo Stopping web server...
net stop Apache2.4

echo Updating WhaTap PHP Agent...
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

if %errorlevel% equ 0 (
    echo Update completed successfully!
) else (
    echo Update failed with error code: %errorlevel%
    exit /b %errorlevel%
)

timeout /t 3

echo Starting web server...
net start Apache2.4
echo Update completed!

수동 제거 후 재설치(문제 해결용)​

업데이트가 실패하거나 설정을 초기화하려는 경우 수동 제거 후 재설치합니다.

# 1. 웹 서버 중지 (권장)
net stop Apache2.4

# 2. 기존 버전 제거
"C:\Program Files\WhaTap\PHP\unins000.exe" /VERYSILENT

# 3. 새 버전 설치 (새로 설치 모드)
whatap_php_setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ^
  /TYPE="basic" ^
  /ACCESSKEY="your_key" ^
  /SERVERHOST="13.124.11.223" ^
  /PHPPATH="C:\PHP\php.exe"

# 4. 웹 서버 시작
net start Apache2.4

제거​

노트

제거 전, 웹 서버를 중지하는 것을 권장합니다.

GUI 제거​

# 1. 웹 서버 중지(권장)
net stop Apache2.4

# 2. 제거 프로그램 실행
"C:\Program Files\WhaTap\PHP\unins000.exe"

# 3. 웹 서버 시작
net start Apache2.4

CLI 자동 제거​

# 1. 웹 서버 중지 (권장)
net stop Apache2.4
# 또는
iisreset /stop

# 2. 무인 제거
"C:\Program Files\WhaTap\PHP\unins000.exe" /VERYSILENT

# 3. 웹 서버 시작
net start Apache2.4
# 또는
iisreset /start

배치 스크립트

@echo off
echo Stopping web server...
net stop Apache2.4

echo Uninstalling WhaTap PHP Agent...
"C:\Program Files\WhaTap\PHP\unins000.exe" /VERYSILENT

timeout /t 3

echo Starting web server...
net start Apache2.4
echo Uninstallation completed!

Troubleshooting​

PHP 모듈이 로드되지 않는 경우​

  1. 웹 서버 재시작를 확인합니다.

    net stop Apache2.4 && net start Apache2.4

  2. php.ini를 확인합니다.

    • C:\PHP\php.ini 또는 C:\PHP\conf.d\whatap.ini
    extension=php_whatap.dll

  3. DLL 파일 존재 여부를 확인합니다.

    dir "C:\PHP\ext\php_whatap.dll"

  4. 원본 DLL을 확인합니다. (문제 해결용)

    dir "C:\Program Files\WhaTap\PHP\modules\x64\php_whatap_*.dll"

서비스가 시작되지 않는 경우​

# 수동 시작 시도
net start "WhaTap PHP"

# 로그 확인
type "C:\Program Files\WhaTap\PHP\logs\error.log"

# whatap.ini 확인
type "C:\Program Files\WhaTap\PHP\whatap.ini"

트랜잭션 데이터가 수집되지 않는 경우​

  1. 방화벽을 확인합니다.

    Test-NetConnection -ComputerName 13.124.11.223 -Port 6600

  2. whatap.ini 설정을 확인합니다.

    whatap.license=your_access_key
    whatap.server.host=13.124.11.223

부록​

설치 파일 구조​

설치 후 생성되는 디렉토리 및 주요 파일은 다음과 같습니다.

C:\Program Files\WhaTap\PHP\
├── whatap_php.exe              # WhaTap 서비스 실행파일 (Go Agent)
├── whatap.ini                  # 설정 파일 (라이센스, 서버 주소)
├── perfcounter.json            # Windows Performance Counter 설정
├── ChangeLog                   # 버전 변경 이력
├── unins000.exe                # 제거 프로그램
└── modules\x64\                # PHP 확장 DLL (PHP API Version 기반)
    ├── php_whatap_20151012.dll         # PHP 7.0 NTS
    ├── php_whatap_zts_20151012.dll     # PHP 7.0 ZTS
    ├── php_whatap_20160303.dll         # PHP 7.1 NTS
    ├── php_whatap_zts_20160303.dll     # PHP 7.1 ZTS
    ├── ...
    ├── php_whatap_20240924.dll         # PHP 8.4 NTS
    └── php_whatap_zts_20240924.dll     # PHP 8.4 ZTS

PHP 통합 (자동 설정)​

설치 프로그램이 PHP 버전에 맞는 DLL을 자동으로 선택하여 PHP extension 디렉토리에 php_whatap.dll로 복사합니다.

C:\PHP\ext\php_whatap.dll       # 실제 로드되는 파일 (PHP 버전별 DLL에서 복사됨)
C:\PHP\conf.d\whatap.ini        # 설정 파일 (Scan Directory가 있는 경우)
또는
C:\PHP\php.ini                  # Scan Directory가 없는 경우 (whatap 설정 통합됨)

php.ini 또는 whatap.ini 설정​

extension=php_whatap.dll

자동 등록 환경 변수​

  • WHATAP_PHP_HOME: C:\Program Files\WhaTap\PHP

  • WHATAP_PHP_CONFIG: whatap.ini

네트워크 요구사항​

항목값
WhaTap Server IP13.124.11.223, 13.209.172.35
Port6600 (TCP Outbound)
방화벽WhaTap Server로의 아웃바운드 연결 허용 필요
노트

참고 문서