콘텐츠로 이동

PHP 제로 코드 계측

Beacon PHP에는 PHP 8.2 이상, 애플리케이션에 설치된 Composer 패키지, 실행 환경에 맞는 Beacon 네이티브 확장이 필요합니다.

연동 전에 공통 설정에 따라 DataKit OpenTelemetry 수집기를 활성화하세요. 아래 명령은 Linux/macOS 셸을 기준으로 하며 애플리케이션과 DataKit이 같은 호스트에 있다고 가정합니다. 서로 다른 호스트나 컨테이너에서는 127.0.0.1을 바꾸고 수신 주소를 조정하세요.

설치

  1. 네이티브 확장 릴리스 페이지에서 PHP 버전, 스레드 안전 모드, 운영 체제 및 아키텍처에 맞는 빌드를 다운로드하고 확장을 활성화하세요.
  2. 애플리케이션 루트에 .beacon 디렉터리를 만들고 Beacon PHP 릴리스 페이지에서 Composer ZIP 아티팩트를 다운로드하여 해당 디렉터리에 저장하세요. 그런 다음 사용하는 프레임워크의 계측 패키지를 설치하세요.
composer config repositories.beacon artifact "$PWD/.beacon"
composer require beacon-observability/beacon-php
vendor/bin/beacon-php install pdo guzzle

vendor/bin/beacon-php components를 실행하면 다른 구성 요소 별칭을 확인할 수 있습니다.

시작

export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=my-php-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
vendor/bin/beacon-php doctor
php public/index.php

PHP-FPM을 사용하는 경우 서비스 환경에 동일한 변수를 설정하고 워커를 재시작하세요. Beacon PHP는 현재 Profile 구성 요소를 제공하지 않습니다.

디버깅 및 진단

먼저 실행 환경 진단 보고서를 생성한 뒤 SDK 내부 진단 로그를 활성화하세요. 위의 자동 로드 및 OTLP 설정을 유지하세요.

vendor/bin/beacon-php doctor --json > beacon-php-doctor.json
OTEL_LOG_LEVEL=debug OTEL_PHP_LOG_DESTINATION=stderr \
  php public/index.php > beacon-php-debug.log 2>&1

doctor는 PHP, 네이티브 확장, SDK, Exporter, 구성 요소 및 제로 코드 설정을 확인하며 실제 OTLP 전송은 검증하지 않습니다. OTEL_PHP_LOG_DESTINATION=stderr는 SDK 내부 로그를 표준 오류에 출력하고 위 명령은 이를 파일에 저장합니다.

PHP-FPM에서는 실제 워커 환경에 두 변수를 주입하고 워커를 재시작한 뒤 FPM 로그 설정에 따라 표준 오류를 수집하세요. CLI와 FPM은 서로 다른 php.ini, 확장 및 환경 변수를 사용할 수 있으므로 CLI doctor 결과로 FPM 실행 환경 확인을 대체할 수 없습니다.

문제 해결 후 원래 시작 명령으로 복원하거나 FPM 또는 서비스 설정에서 디버그 변수를 제거하고 재시작하세요.

연동 확인

지원되는 프레임워크나 라이브러리를 거치는 요청을 애플리케이션 API에 보낸 뒤 Guance의 APM > 트레이스에서 위에 설정한 서비스 이름으로 필터링하세요. 전체 확인 절차는 공통 설정을, 데이터가 없으면 문제 해결을 참조하세요.

문서 평가

이 페이지가 도움이 되었나요?