Enterprise 에디션

사용량 측정

한눈에 보기

NextPDF Enterprise는 사용량 측정 — 작업, 처리된 페이지, 소요 시간 — 을 청구 및 감사를 위해 PHP 오케스트레이션 계층에서 수집합니다. 항목은 메모리에 버퍼링되어 하나 이상의 백엔드로 일괄 플러시되며, 백엔드 실패는 처리를 절대 차단하지 않습니다. 이 페이지는 관찰 가능한 측정 동작과 공개 계약을 설명합니다.

가용성 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에서 제공되며, Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 측정은 기본 Enterprise 기능이며 별도의 기능별 플래그가 없습니다. 에디션 비교 및 라이선스 받기.

개념 개요

측정 수집기는 작업당 하나의 불변 항목을 기록합니다. 작업 유형, 단위 수, 타임스탬프, 테넌트 및 라이선스 식별자, 처리된 페이지, 작업 소요 시간, 그리고 자유 형식 메타데이터입니다. 항목은 인메모리 버퍼에 누적됩니다. 버퍼가 구성된 크기에 도달하면 자동 플러시됩니다. 명시적으로 플러시할 수도 있으며, PHP-FPM 워커가 요청 종료 시 나머지를 플러시하도록 종료 핸들러를 등록할 수 있습니다. 장시간 실행되는 워커(예: Octane 또는 Symfony 워커)는 대신 주기적 타이머로 플러시해야 합니다.

리포터는 배치를 하나 이상의 백엔드로 팬아웃합니다. 백엔드는 격리되어 있습니다. 한 백엔드의 실패가 다른 백엔드의 배치 수신을 막지 않습니다. 각 백엔드 전달은 구성된 시도 횟수까지 재시도됩니다. 모든 시도가 실패하면 해당 백엔드의 배치는 로깅되고 폐기됩니다 — 측정은 설계상 최선 노력이며 치명적이지 않으므로, 측정 중단이 문서 처리를 절대 저하시키지 않습니다. 백엔드는 측정 백엔드 인터페이스의 모든 구현입니다 — Prometheus 푸시 대상, 청구 API, 데이터베이스, 또는 큐 — 이며, 중복된 배치가 우아하게 처리되도록 구현은 멱등이어야 합니다.

이 오케스트레이션 수준 측정은 청구 및 감사 가시성을 위한 것입니다. 의도적으로 할당량 강제의 권위 있는 출처가 아닙니다. 할당량 결정은 권위 있는 사용량 수치로부터 배포 환경의 다른 곳에서 이루어집니다.

이렇게 작동하는 이유

측정은 문서 처리 경로가 아니라 청구 및 감사 경로에 위치하며, 그 분리는 의도적입니다. 각 record 호출은 하나의 불변 MeterEntry를 인메모리 버퍼에 추가하므로, 사용량 포착은 O(1) 작업으로 유지됩니다. 플러시는 배치로 이루어지며, MeteringBackendInterface 계약 뒤의 격리된 백엔드로 팬아웃됩니다. 그러면 느리거나 죽은 청구 엔드포인트가 우아하게 저하되고, 소진된 배치는 던져지지 않고 로깅되어 폐기됩니다. 따라서 측정 중단이 대용량 작업을 절대 정지시키거나 문서 처리량과 경쟁하지 않습니다. 그 절충은 오케스트레이션 측정이 최선 노력이며 권위가 없다는 점입니다 — 그래서 할당량 강제는 권위 있는 수치로부터 다른 곳에서 결정됩니다.

설계 배경: 대용량 문서 생성.

공개 API 표면

composer require nextpdf/enterprise:^3

지원되는 통합 지점은 측정 수집기(record, flush, bufferCount, registerShutdownFlush), 측정 리포터(report), 측정 백엔드 인터페이스(report, isHealthy, backendName), 그리고 불변 측정 항목 값 객체입니다. 프로덕션 지속성을 위한 재시도 안전하고 멱등인 백엔드 구현을 제공하는 것은 귀하의 책임입니다.

코드 샘플 — 빠른 시작

use NextPDF\Enterprise\Metering\MeterCollector;
use NextPDF\Enterprise\Metering\MeteringReporter;

$collector = new MeterCollector(new MeteringReporter([$backend]), bufferSize: 100);
$collector->registerShutdownFlush(); // PHP-FPM: flush remainder at request end

$collector->record(
    operation: 'parse',
    count: 1,
    tenantId: $tenantId,
    licenseId: $licenseId,
    pagesProcessed: 12,
    durationMs: 84.0,
);

코드 샘플 — 프로덕션

use NextPDF\Enterprise\Metering\MeteringReporter;

// Multi-backend fan-out with retry and failure isolation.
$reporter = new MeteringReporter(
    backends: [$prometheusBackend, $billingApiBackend],
    maxRetries: 3,
    logger: $logger,
);

// A failing billing API does not stop Prometheus from receiving the batch;
// exhausted retries are logged and the batch is dropped — never thrown.
$collector = new MeterCollector($reporter, bufferSize: 500);

엣지 케이스 및 함정

플러시는 멱등입니다. 빈 버퍼에 flush를 호출하는 것은 무연산입니다. 이중 플러시는 안전합니다.
백엔드 실패는 치명적이지 않습니다. 소진된 재시도는 오류를 로깅하고 해당 백엔드의 배치를 폐기합니다. 호출은 여전히 정상적으로 반환됩니다. 엄격한 할당량 강제를 위해 측정에 의존하지 마십시오.
최소 하나의 백엔드가 필요합니다. 빈 백엔드 목록으로 리포터를 구성하는 것은 거부됩니다.
멱등성은 백엔드의 임무입니다. 인터페이스 계약은 백엔드가 (타임스탬프, 작업, 테넌트별로) 중복을 제거하도록 요구합니다 — 재시도되거나 중복된 배치가 이중 집계되어서는 안 됩니다.
워커 모델이 중요합니다. PHP-FPM에는 종료 핸들러를 사용하고, 장시간 실행되는 워커에는 주기적 타이머 플러시를 사용하십시오. 그렇지 않으면 항목이 워커가 종료될 때까지 버퍼링됩니다.

성능

record는 O(1) 버퍼 추가입니다. 플러시 비용은 배치 크기와 백엔드 수에 비례합니다. 버퍼링과 종료 핸들러를 통해 요청 경로 밖으로 옮겨집니다. 재시도는 백엔드별로 적용되며, 구성된 시도 횟수로 한정됩니다.

보안 참고

측정 항목은 테넌트 및 라이선스 식별자와 작업 메타데이터를 담습니다. 메타데이터를 잠재적으로 민감한 것으로 취급하고, 백엔드 저장소 및 보존을 귀하의 준수 요건에 맞게 범위 지정하십시오. 테넌트 및 라이선스 식별자는 인증된 컨텍스트에서 비롯되어야 합니다.

적합성

측정은 공개 경계에서 자체 와이어 형식을 정의하지 않습니다 — 백엔드 인터페이스는 직렬화를 각 백엔드 구현에 위임합니다(예를 들어, Prometheus 푸시 대상은 Prometheus 노출 규약을 따릅니다). 이 표면에서는 어떤 외부 표준도 단언하지 않습니다. 어떤 규범적 사양도 인프로세스 수집기 계약을 규율하지 않으므로 이 페이지에 대한 RAG 인용은 없습니다.

동작 계약

수집기는 작업당 하나의 불변 항목을 기록하고, 구성된 크기에서 자동 플러시되는 인메모리 버퍼에 항목을 누적합니다. 명시적 플러시와 종료 플러시 핸들러도 사용할 수 있습니다.
플러시는 멱등입니다. 빈 버퍼를 플러시하는 것은 무연산이며 이중 플러시는 안전합니다.
리포터는 백엔드별 격리와 함께 배치를 하나 이상의 백엔드로 팬아웃합니다. 한 백엔드의 실패가 다른 백엔드를 막지 않습니다.
각 백엔드 전달은 구성된 시도 횟수까지 재시도됩니다. 소진된 재시도는 로깅되고 폐기됩니다 — 측정은 최선 노력이며 처리 경로로 절대 던지지 않습니다.
빈 백엔드 목록으로 리포터를 구성하는 것은 거부됩니다. 중복된 배치가 이중 집계되지 않도록 백엔드는 멱등이어야 합니다.
record는 O(1) 버퍼 추가입니다. 플러시 비용은 배치 크기와 백엔드 수에 비례하며 요청 경로 밖으로 유지됩니다.

공개 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 설명합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.

Core 폴백

NextPDF Core(Apache-2.0)에는 측정 수집기, 리포터, 또는 백엔드 표면이 없습니다 — 전혀 없습니다. 이 기능에는 Core 등급 등가물이 없습니다. Core 처리는 NextPDF에 의해 측정되지 않습니다.

Pro 폴백

NextPDF Pro에는 측정 표면이 없습니다 — 전혀 없습니다. 이 기능에는 Pro 등급 등가물이 없습니다. 측정 수집기, 리포터, 백엔드 인터페이스는 nextpdf/enterprise 패키지에서만 제공됩니다.

Enterprise 경계 참고

버퍼 라이프사이클, 팬아웃, 재시도, 격리는 동작 수준에서 설명됩니다. 백엔드 인터페이스는 직렬화를 각 백엔드 구현에 위임합니다. 내부 버퍼링 내부와 모든 내부 팬아웃 세부 사항은 공개 표면의 범위 밖입니다.

배포 경계

운영자는 백엔드 구현, 그 지속성과 멱등성, 측정 메타데이터의 보존 및 저장 범위, 그리고 워커 모델 플러시 전략(PHP-FPM에는 종료 핸들러, 장시간 실행되는 워커에는 주기적 타이머)을 소유합니다. 측정 백엔드 중단은 문서 처리를 절대 저하시키지 않습니다. 테넌트 및 라이선스 식별자는 운영자가 구성하는 인증된 컨텍스트에서 비롯되어야 합니다.

법률 준수 경계

측정 표면에는 어떤 수출 통제 제한도 적용되지 않습니다. 측정 메타데이터는 민감할 수 있습니다. 보존 및 저장 범위는 운영자의 준수 책임입니다. 이 문서는 법률 의견이 아닙니다. 자체 준수 및 법률 자문에게 문의하십시오.