PHP OpenTelemetry 메트릭: Laravel HTTP 요청 계측

PHP OpenTelemetry Metrics SDK로 Laravel 요청 수와 지연 시간을 기록합니다. 라우트 템플릿, PHP-FPM 요청 종료 처리와 OTLP/HTTP 전송을 확인하세요.

모범 사례
애플리케이션 텔레메트리를 살펴보는 일러스트

PHP-FPM 워커 풀에 여유가 있어도 Laravel 주문 API는 503을 반환할 수 있다. 먼저 Laravel이 실제로 반환한 상태 코드와 응답을 만드는 데 걸린 시간을 기록한다. 주문 ID가 달라져도 한곳에서 볼 수 있도록 실제 URL 대신 /orders/{order} 같은 라우트 템플릿을 붙인다.

로컬에 OTLP 수신기 띄우기

예제는 PHP 8.3 이상이 필요한 Laravel 13을 사용한다. 여기서 고정한 OpenTelemetry SDK와 OTLP 익스포터 자체의 요구 사항은 PHP 8.2 이상이다. HTTP 클라이언트는 Guzzle, Protobuf 구현은 Composer 패키지를 사용한다. 수동 계측이라 PHP용 OpenTelemetry 자동 계측 확장은 필요하지 않다. 기존 Laravel 프로젝트의 루트에서 아래 패키지를 설치한다. OpenTelemetry PHP 계측 문서(영어)

composer require open-telemetry/sdk:1.16.1 \
  open-telemetry/exporter-otlp:1.5.0 \
  guzzlehttp/guzzle:7.16.1 google/protobuf:5.36.2

다음 설정을 collector.yaml로 저장하고 otelcol-contrib --config=collector.yaml로 실행한다. OTLP/HTTP 수신기는 루프백에서만 연결을 받는다. 백엔드를 연결하기 전에 debug 출력에서 메트릭 데이터 포인트를 확인할 수 있다.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:14318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]

Laravel이 실제로 돌려준 응답 기록하기

미들웨어를 app/Http/Middleware/OpenTelemetryMetrics.php에 둔다. 단조 시계로 재는 시간은 Laravel의 후속 처리 구간이다. 응답 본문 전송과 텔레메트리 전송은 포함하지 않는다. Laravel은 terminate()를 호출할 때 새 미들웨어 인스턴스를 만들 수 있으므로 측정값을 요청 객체에 둔다. HTTP 예외가 응답으로 처리된 경우에도 terminate()로 넘어온 최종 응답에서 상태 코드를 얻는다. Laravel 종료 미들웨어(영어)

<?php

namespace App\Http\Middleware;

use Closure;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Illuminate\Http\Request;
use OpenTelemetry\Contrib\Otlp\MetricExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Http\PsrTransportFactory;
use OpenTelemetry\SDK\Metrics\Data\Temporality;
use OpenTelemetry\SDK\Metrics\MeterProvider;
use OpenTelemetry\SDK\Metrics\MetricReader\ExportingReader;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use Symfony\Component\HttpFoundation\Response;
use Throwable;

final class OpenTelemetryMetrics
{
    private const DURATION = '_otel_demo_duration_seconds';

    public function handle(Request $request, Closure $next): Response
    {
        $started = hrtime(true);
        try {
            return $next($request);
        } finally {
            $request->attributes->set(self::DURATION, (hrtime(true) - $started) / 1e9);
        }
    }

    public function terminate(Request $request, Response $response): void
    {
        $duration = $request->attributes->get(self::DURATION);
        if (!is_float($duration)) {
            return;
        }

        $method = $request->method();
        $knownMethods = ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE', 'PATCH'];
        $attributes = [
            'http.request.method' => in_array($method, $knownMethods, true) ? $method : '_OTHER',
            'http.response.status_code' => $response->getStatusCode(),
        ];
        if ($route = $request->route()) {
            $attributes['http.route'] = '/' . ltrim($route->uri(), '/');
        }

        try {
            $factory = new HttpFactory();
            $client = new Client(['timeout' => 0.25]);
            $transport = (new PsrTransportFactory($client, $factory, $factory))->create(
                getenv('OTEL_EXPORTER_OTLP_METRICS_ENDPOINT') ?: 'http://127.0.0.1:14318/v1/metrics',
                'application/x-protobuf',
                maxRetries: 0,
            );
            $reader = new ExportingReader(new MetricExporter($transport, Temporality::DELTA));
            $provider = MeterProvider::builder()
                ->setResource(ResourceInfo::create(Attributes::create(['service.name' => 'checkout-php'])))
                ->addReader($reader)
                ->build();

            try {
                $meter = $provider->getMeter('example.checkout');
                $requests = $meter->createCounter('app.http.server.requests', '{request}');
                $latency = $meter->createHistogram('app.http.server.duration', 's', advisory: [
                    'ExplicitBucketBoundaries' => [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5],
                ]);
                $requests->add(1, $attributes);
                $latency->record($duration, $attributes);
            } finally {
                if (!$provider->shutdown()) {
                    error_log('OpenTelemetry metrics export did not complete');
                }
            }
        } catch (Throwable $error) {
            error_log('OpenTelemetry metrics export failed: ' . $error::class);
        }
    }
}

bootstrap/app.php에 이미 있는 withMiddleware 콜백에 아래 등록 코드를 합친다.

->withMiddleware(function (\Illuminate\Foundation\Configuration\Middleware $middleware): void {
    $middleware->prepend(\App\Http\Middleware\OpenTelemetryMetrics::class);
})

이 예제는 자동 계측이 내보낼 수 있는 표준 HTTP 메트릭과 구분하기 위해 이름을 따로 정했다. http.route에는 /otel-probe/{order}처럼 일치한 라우트 템플릿만 넣는다. 일치하는 라우트가 없으면 이 속성을 생략한다. 실제 경로, 쿼리 문자열이나 고객 ID를 넣으면 트래픽에 따라 시계열 수가 계속 늘어난다. HTTP 메트릭 시맨틱 규약(영어)

정상 응답과 503이 어떻게 기록되는지 비교하기

초기화된 실습용 Laravel 프로젝트를 사용한다. 로컬 앱 키가 없다면 php artisan key:generate로 만들고, routes/web.php에 아래 라우트를 추가한다. SESSION_DRIVER=array php artisan serve --host=127.0.0.1 --port=8000으로 서버를 띄우고 두 URL에 요청을 보낸다.

\Illuminate\Support\Facades\Route::get('/otel-probe/{order}', function (string $order) {
    abort_if($order === 'fail', 503);
    return response()->noContent();
});
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/otel-probe/alpha
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/otel-probe/fail

응답은 204와 503이다. Collector에서 각각 요청 카운터 증가량 1과 히스토그램 관측값 한 건을 찾는다. 상태 코드는 다르고 라우트 템플릿은 같아야 한다. 5xx 비율은 같은 시간과 집계 범위에서 5xx 증가량 합계를 전체 요청 증가량 합계로 나누면 된다. 예제는 5 ms부터 2.5초까지 버킷 경계를 지정했다. 실제로 확인할 지연 시간 기준에 맞춘다. P95를 추정하려면 지연 시간 분포와 버킷별 건수가 필요하다. 요청 카운터만으로는 알 수 없다.

Guance로 보낼 때도 같은 두 요청으로 저장된 값을 확인한다. 이 코드는 프로세스 환경 변수 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT에 지정한 전체 URL을 읽는다. DataKit 기본 HTTP 포트는 9529, 메트릭 경로는 /otel/v1/metrics이며 전송 형식은 Protobuf다. 실제 배포에서 사설 연결, TLS와 인증을 맞춘다. 대시보드를 만들기 전에 수신 측의 델타 집계와 히스토그램 버킷 보존 여부를 살핀다. DataKit OpenTelemetry 연동

메트릭을 어디에서 모을지 정하기

PHP-FPM은 워커 프로세스를 재사용하지만 일반 요청에서 만든 SDK 객체는 요청이 끝나면 사라진다. 이 ExportingReader에는 자체 타이머가 없다. 예제는 shutdown()에서 델타 값을 모으고 동기 전송을 한 번 시도한다. 여러 PHP 요청에 걸친 누적 카운터로 해석하면 안 된다. 고정 버전의 PHP ExportingReader

FastCGI에서는 Laravel이 응답을 보낸 뒤 종료 작업을 실행할 수 있다. 그래도 내보내기가 끝날 때까지 워커는 사용 중이다. 예제는 HTTP 클라이언트 타임아웃을 250 ms로 두고 익스포터 재시도를 끈다. 트래픽이 많다면 수신기가 정상일 때와 응답하지 않을 때 각각 워커 점유를 측정한다. 가까운 Collector에서 후속 전송을 묶어도 이 요청 단위 PHP 코드가 보내는 횟수는 줄지 않는다. 전송 성공도 보장하지 않는다.

상주 큐 워커는 여러 작업에 하나의 프로바이더를 재사용할 수 있다. 리더 참조를 보관해 작업 루프나 타이머에서 $reader->collect()를 실행한다. 정상 종료 시에는 $provider->shutdown()을 한 번 호출한다. 큐 깊이 같은 Gauge는 공유 상태를 읽을 수 있는 곳에서 수집한다. 서로 격리된 요청마다 UpDownCounter를 올렸다 내리는 방식으로는 FPM 풀 전체의 동시 처리량을 알 수 없다.

풀 방식의 /metrics가 필요하면 PHP와 Prometheus 가이드(중국어 간체)를 참고한다. 계측기 종류와 집계는 OpenTelemetry 메트릭(영어)에서 다룬다.

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소