참고: Windows에서는 APM만 지원됩니다. Windows에서 PHP 애플리케이션을 추적할 때 --enable-appsec 및 --enable-profiling 플래그를 사용하지 마세요.
이 명령을 실행하면 호스트 또는 컨테이너에서 찾은 모든 PHP 바이너리에 확장을 설치합니다. --php-bin이 생략되면 설치 프로그램이 대화형 모드로 실행되고, 사용자에게 설치할 바이너리를 선택해 달라고 요청합니다. dd-trace-php가 특정 바이너리에만 설치되어야 하는 경우, --php-bin의 값이 해당 바이너리로의 경로일 수 있습니다.
PHP(PHP-FPM 또는 Apache SAPI)를 다시 시작하고 애플리케이션의 추적이 활성화된 엔드포인트를 방문하세요. 생성된 트레이스를 보려면 APM Traces 페이지로 이동합니다.
--enable-appsec를 지정하지 않으면, 시작 시 짧게 AppSec 확장이 로드되고, 기본적으로 활성화되지 않습니다. 이것은 즉시 단락되어 미미한 성능 오버헤드를 초래합니다.
트레이스가 UI에 표시되려면 몇 분 걸릴 수 있습니다. 몇 분이 지난 뒤에도 여전히 트레이스가 표시되지 않는 경우, 호스트 머신에서 phpinfo() 페이지를 만든 다음 `ddtrace`까지 스크롤을 내립니다. 이 섹션에 실패한 진단 검사가 표시되어 문제가 있는지 식별하는 데 도움이 됩니다.
Apache ZTS:
PHP CLI 바이너리가 NTS로 빌드되었고(스레드 안전(thread-safe)하지 않음) Apache는 PHP의 ZTS(Zend thread-safe) 버전을 사용하는 경우, ZTS 바이너리에 대한 확장 로드를 수동으로 변경해야 합니다. 코드 /path/to/php-zts --ini 를 실행하여 Datadog의 .ini 파일 위치를 찾은 다음, 파일 이름에서 -zts 접미사를 추가하세요. 예를 들어 extension=ddtrace-20210902.so 에서 extension=ddtrace-20210902-zts.so입니다.
SELinux:
호스트에서 httpd SELinux 정책이 구성된 경우, SDK의 기능이 제한될 수 있습니다. 단, SELinux 구성에서 임시 파일의 쓰기 및 실행이 명시적으로 허용된 경우는 예외입니다.
# ... leave here all the pre-existing packages
# add a `deb` deb http://deb.debian.org/debian-debug/ $RELEASE-debug main
# For example for buster
debhttp://deb.debian.org/debian-debug/buster-debugmain
apt 업데이트:
apt update
먼저 디버그 기호의 표준 패키지 이름을 사용해 보세요. 예를 들어 패키지 이름이 php7.2-fpm인 경우, 다음을 사용해 보기:
apt install -y php7.2-fpm-dbgsym
# if the above does not work
apt install -y php7.2-fpm-dbg
디버그 기호를 찾을 수 없는 경우, 유틸리티 도구 find-dbgsym-packages를 사용합니다. 바이너리 설치:
apt install -y debian-goodies
바이너리로의 전체 경로 또는 실행 중인 프로세스의 프로세스 id로부터 디버그 기호 찾기 시도:
PHP가 ppa:ondrej/php에서 설치된 경우, main/debug 구성 요소를 추가하여 apt 소스 파일 /etc/apt/sources.list.d/ondrej-*.list를 편집합니다.
전:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main
후:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main main/debug
디버그 기호를 업데이트하고 설치합니다. 예를 들어 PHP-FPM 7.2의 경우:
apt update
apt install -y php7.2-fpm-dbgsym
다른 패키지에서 설치된 PHP
PHP 바이너리의 패키지 이름을 찾으세요. 이 이름은 PHP 설치 방법에 따라 다를 수 있습니다.
apt list --installed | grep php
참고: 상황에 따라 php-fpm이 실제 패키지를 참조하는 메타패키지일 수 있습니다. 예를 들어 PHP-FPM 7.2인 경우 php7.2-fpm이 됩니다. 이런 경우 패키지 이름은 실제 패키지 이름입니다.
먼저 디버그 기호의 표준 패키지 이름을 사용해 보세요. 예를 들어 패키지 이름이 php7.2-fpm인 경우, 다음을 사용해 보기:
apt install -y php7.2-fpm-dbgsym
# if the above does not work
apt install -y php7.2-fpm-dbg
-dbg 및 -dbgsym 패키지를 찾을 수 없는 경우, ddebs 리포지토리를 활성화합니다. ddebs에서 디버그 기호를 설치하는 방법에 관한 자세한 정보는 Ubuntu 설명서를 참조하세요.
예를 들어 Ubuntu 18.04+의 경우, ddebs 리포지토리 활성화:
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
특히 PHP-FPM에서는 PHP 애플리케이션의 코어 덤프를 획득하기 어려울 수 있습니다. 코어 덤프 획득에 도움이 되는 몇 가지 팁을 소개합니다.
애플리케이션 오류 로그를 살펴보아 PHP-FPM이 코어 덤프를 생성했는지 판단:
(SIGSEGV - core dumped)와 같은 메시지가 있으면 덤핑되었다는 뜻이므로 해당 메시지 검색: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV - core dumped) after <duration> seconds from start.
(SIGSEGV)와 같은 메시지가 있으면 코어가 덤핑되지 않았다는 뜻이므로 해당 메시지 검색: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV) after <duration> seconds from start.
cat /proc/sys/kernel/core_pattern을 실행하여 코어 덤프의 위치를 찾습니다. 기본 값은 일반적으로 core이며, 이는 이름이 core인 파일이 웹 루트 폴더에서 생성될 것이라는 의미입니다.
생성된 코어 덤프가 없으면 다음 구성을 검사하고 필요에 따라 변경하세요.
/proc/sys/kernel/core_pattern이 중첩된 디렉터리를 포함하는 경로를 포함하는 경우, 전체 디렉터리 경로가 존재하는지 확인합니다.
PHP-FPM 풀 워커를 실행 중인 사용자가 root 외의 다른 사용자인 경우(보편적인 사용자 이름은 www-data임) 해당 사용자에게 코어 덤프 디렉터리에 대한 쓰기 권한을 부여합니다.
/proc/sys/fs/suid_dumpable의 값이 0이 아니어야 합니다. 이 값을 1 또는 2로 설정합니다(단, PHP-FPM 워커 풀을 root로 실행하는 경우는 예외). 시스템 관리자에게 문의하여 옵션을 확인하세요.
PHP-FPM 풀 구성 섹션에 적합한 rlimit_core가 있어야 합니다. 이것을 무제한 rlimit_core = unlimited로 설정할 수 있습니다.
시스템에 적절한 ulimit가 설정되어 있어야 합니다. 이것을 무제한 ulimit -c unlimited로 설정할 수 있습니다.
애플리케이션이 Docker 컨테이너에서 실행되는 경우, /proc/sys/*에 대한 변경은 호스트 머신에 대하여 수행해야 합니다. 사용 가능한 옵션을 알아보려면 시스템 관리자에게 문의하세요. 할 수 있다면, 문제를 테스트 또는 스테이징 환경에서 재현해 보세요.
Docker 컨테이너 내에서 코어 덤프 획득
Docker 컨테이너에서 코어 덤프를 획득하는 데 도움이 되는 아래 정보 활용:
Docker 컨테이너는 권한 있는 컨테이너로 실행해야 하며, 코어 파일의 ulimit 값을 아래 예시에 표시된 것과 같이 최댓값으로 설정해야 합니다.
docker run 명령을 실행하는 경우, --privileged 및 --ulimit core=99999999999 인수 추가
docker compose를 사용하는 경우, docker-compose.yml 파일에 다음 추가:
privileged:trueulimits:core:99999999999
컨테이너를 실행할 때(그리고 PHP 애플리케이션을 시작하기 전에) 다음 명령을 실행해야 함:
