OpenTelemetry PHP¶

OpenTelemetry PHP는 PHP 확장을 통해 런타임 Hook을 제공하며, Composer로 설치된 프레임워크 계측 라이브러리가 텔레메트리 데이터를 생성합니다. 비즈니스 코드를 수정하지 않고도 지원되는 웹 프레임워크, HTTP 클라이언트, 데이터베이스 등의 호출을 수집할 수 있습니다.

이 문서에서는 DataKit의 OpenTelemetry 수집기를 사용하여 OTLP 데이터를 수신하고 Guance로 전달하는 방법을 설명합니다:

PHP 애플리케이션 + OpenTelemetry 확장/계측 라이브러리 -> OTLP -> DataKit -> Guance

전제 조건¶

• PHP 8.0 이상
• Composer 및 PHP 확장을 설치할 수 있는 PECL 또는 시스템 패키지 관리자
• 애플리케이션이 Composer를 통해 vendor/autoload.php를 로드하고 있어야 함
• DataKit이 설치되어 있고, 대상 Guance 워크스페이스에 연결되어 있어야 함
• PHP 애플리케이션에서 DataKit으로 네트워크 접근이 가능해야 함: OTLP/HTTP는 DataKit HTTP 포트 9529 사용, OTLP/gRPC는 기본적으로 4317 사용

1. OpenTelemetry 수집기 활성화¶

DataKit 설치 디렉터리 아래 conf.d/opentelemetry로 이동합니다. 수집기 설정이 아직 생성되지 않은 경우 샘플 파일을 복사합니다:

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf에 다음 수신 설정이 최소한 포함되어 있는지 확인합니다:

[[inputs.opentelemetry]]
  # Guance에서 태그로 유지할 사용자 정의 속성을 화이트리스트에 추가합니다.
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

수신 주소는 다음과 같습니다:

PHP 애플리케이션이 DataKit와 동일한 호스트에 있지 않은 경우, 실제 배포 환경에 맞게 DataKit 수신 주소, 방화벽 또는 기타 네트워크 접근 제어를 조정해야 합니다. gRPC의 경우 addr을 애플리케이션에서 접근 가능한 수신 주소(예: 0.0.0.0:4317)로 변경할 수 있습니다. OTLP 수신 포트를 공용 네트워크에 직접 노출하지 마십시오.

DataKit을 재시작하고 서비스를 확인합니다:

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

2. 애플리케이션에 OpenTelemetry 연동¶

OpenTelemetry PHP 확장 설치¶

먼저 PHP CLI에서 사용 중인 버전과 설정 파일 위치를 확인합니다:

php --version
php --ini

PHP 개발 환경, PECL, 컴파일러, make, autoconf가 준비되면 PECL 공식 소스에서 확장을 설치합니다:

sudo pecl install opentelemetry

PHP가 스캔하는 추가 설정 디렉터리에 99-opentelemetry.ini를 생성하거나, 현재 php.ini에 다음 설정을 추가합니다:

[opentelemetry]
extension=opentelemetry.so

PHP-FPM, Apache 또는 기타 PHP 애플리케이션 프로세스를 재시작한 후 확장을 확인합니다:

php --ri opentelemetry

확장만 설치하면 자동으로 Trace가 생성되지 않습니다. SDK, OTLP exporter 및 애플리케이션 프레임워크에 해당하는 계측 패키지도 설치해야 합니다.

SDK 및 자동 계측 패키지 설치¶

다음은 Slim 및 PSR-18 HTTP 클라이언트를 예로 들어 애플리케이션의 Composer 프로젝트 디렉터리에서 실행합니다:

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-slim \
  open-telemetry/opentelemetry-auto-psr18

애플리케이션에 OTLP HTTP exporter에서 사용할 PSR-17 Factory 및 비동기 HTTP Client 구현이 없는 경우 다음을 추가로 설치할 수 있습니다:

composer require php-http/guzzle7-adapter nyholm/psr7

프레임워크에 따라 다른 open-telemetry/opentelemetry-auto-* 패키지를 설치해야 합니다. OpenTelemetry PHP 계측 패키지 목록에서 현재 프레임워크, 데이터베이스 또는 클라이언트와 일치하는 패키지를 선택할 수 있습니다. 해당 계측 패키지가 설치되지 않은 컴포넌트는 자동으로 Span을 생성하지 않습니다.

환경 변수로 시작¶

다음은 OTLP/HTTP + Protobuf를 예로 들어 기본적으로 Trace를 연동하고 Metric과 Log는 일시적으로 비활성화합니다:

export OTEL_PHP_AUTOLOAD_ENABLED="true"
export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"

php -S 0.0.0.0:8080 -t public

OTEL_EXPORTER_OTLP_ENDPOINT는 기본 주소입니다. OTLP/HTTP exporter는 데이터 유형에 따라 자동으로 /v1/traces, /v1/metrics 또는 /v1/logs를 추가하여 최종적으로 DataKit의 /otel/v1/* 라우트에 매핑됩니다.

PHP-FPM, Apache, Supervisor 또는 systemd는 현재 터미널의 환경 변수를 상속하지 않을 수 있습니다. 변수를 실제 서비스 프로세스의 시작 환경에 기록하거나 다음 섹션의 PHP 설정 방식을 사용한 후 서비스를 재시작해야 합니다.

PHP 설정으로 활성화¶

PHP-FPM 또는 Apache가 실제로 로드하는 php.ini 또는 추가 INI 파일에 다음 내용을 추가할 수도 있습니다:

OTEL_PHP_AUTOLOAD_ENABLED="true"
OTEL_SERVICE_NAME="order-service"
OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"
OTEL_TRACES_EXPORTER="otlp"
OTEL_METRICS_EXPORTER="none"
OTEL_LOGS_EXPORTER="none"
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
OTEL_PROPAGATORS="tracecontext,baggage"

PHP CLI와 PHP-FPM은 서로 다른 설정 파일을 로드할 수 있습니다. php --ini를 사용하면 CLI 설정만 확인할 수 있습니다. 웹 애플리케이션에 연동할 때는 PHP-FPM 또는 Apache 해당 SAPI에서 확장과 위 설정이 로드되었는지도 확인해야 합니다.

OTLP/gRPC 사용¶

PHP에서 OTLP/gRPC를 사용하려면 grpc PHP 확장과 Composer transport 패키지가 추가로 필요합니다:

sudo pecl install grpc
composer require open-telemetry/transport-grpc

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"

gRPC endpoint에는 /v1/traces 등의 HTTP 경로를 추가할 수 없습니다.

3. 데이터 전송 파라미터¶

기본 파라미터¶

service.name은 Guance에서의 서비스 귀속에 사용됩니다. env와 version도 함께 설정하여 환경 및 버전별로 필터링할 수 있도록 권장합니다. 다른 사용자 정의 리소스 속성은 DataKit customer_tags 화이트리스트에 추가해야 태그로 유지되며, 속성 이름의 .는 _로 변환됩니다.

PHP 자동 계측 파라미터¶

OTLP 파라미터¶

DataKit의 OTLP/HTTP 수집은 Protobuf만 지원하므로 http/protobuf를 사용해야 하며, http/json은 사용하지 마십시오. 통합 endpoint와 특정 데이터 유형의 endpoint가 동시에 존재하는 경우, 특정 데이터 유형의 설정이 우선합니다.

샘플링 파라미터¶

프로덕션 환경에서는 트래픽과 데이터 예산에 따라 샘플링 비율을 설정해야 합니다. 애플리케이션 측 헤더 샘플링과 DataKit 측 샘플링을 동시에 활성화하면 최종 유지율이 중첩되어 낮아지므로, 샘플링 위치를 통합적으로 계획해야 합니다.

연동 확인¶

자동 계측 패키지가 설치된 애플리케이션 라우트를 요청한 후, DataKit 호스트에서 수신 로그를 확인합니다:

curl http://127.0.0.1:8080/
sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces에 대한 POST 요청이 나타나고 응답 코드가 200이면 DataKit이 Trace를 수신한 것입니다. 그런 다음 Guance의 "애플리케이션 성능 모니터링(APM) > 분산 추적"에서 service:order-service로 조회합니다.

데이터가 없는 경우, PHP 웹 SAPI에서 opentelemetry 확장이 로드되었는지, 애플리케이션에서 Composer autoloader를 로드했는지, OTEL_PHP_AUTOLOAD_ENABLED가 true인지, 실제 코드 경로와 일치하는 자동 계측 패키지가 설치되었는지, OTLP endpoint에 접근 가능한지 순서대로 확인합니다.

참고 자료¶

• OpenTelemetry 수집기 설정
• OpenTelemetry PHP 제로 코드 계측
• OpenTelemetry PHP SDK 설정
• OpenTelemetry PHP 계측 라이브러리
• OpenTelemetry OTLP Exporter 설정