Pomiar zużycia

W skrócie

NextPDF Enterprise zbiera pomiary zużycia — operacje, przetworzone strony, czasy trwania — w warstwie orkiestracji PHP na potrzeby rozliczeń i audytu. Wpisy są buforowane w pamięci, zrzucane do jednego lub wielu backendów w paczkach, a niepowodzenie backendu nigdy nie blokuje przetwarzania. Ta strona opisuje obserwowalne zachowanie pomiarów oraz publiczny kontrakt.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez takiego uprawnienia nie ładuje klas tej możliwości. Pomiary są podstawową możliwością Enterprise bez osobnej flagi dla poszczególnych funkcji. Porównaj edycje i uzyskaj licencję.

Przegląd koncepcyjny

Kolektor pomiarów rejestruje jeden niemutowalny wpis na operację: typ operacji, liczbę jednostek, znacznik czasu, identyfikatory najemcy i licencji, przetworzone strony, czas trwania operacji oraz metadane w dowolnej formie. Wpisy gromadzą się w buforze w pamięci. Gdy bufor osiągnie skonfigurowany rozmiar, jest automatycznie zrzucany; można też zrzucić go jawnie, a procedurę obsługi zamknięcia (shutdown handler) można zarejestrować tak, aby pracownik PHP-FPM zrzucał pozostałość na końcu żądania. Długo działający pracownik (na przykład pracownik Octane lub Symfony) powinien zamiast tego zrzucać dane na podstawie okresowego licznika czasu.

Reporter rozprowadza paczkę do jednego lub wielu backendów. Backendy są izolowane: niepowodzenie w jednym backendzie nie powstrzymuje pozostałych od otrzymania paczki. Każde dostarczenie do backendu jest ponawiane do skonfigurowanej liczby prób; jeśli wszystkie próby zawiodą, paczka dla tego backendu jest logowana i porzucana — pomiary są z założenia realizowane na zasadzie najlepszego możliwego wyniku i nie są krytyczne, więc awaria pomiarów nigdy nie pogarsza przetwarzania dokumentów. Backend to dowolna implementacja interfejsu backendu pomiarów — cel push Prometheus, API rozliczeń, baza danych lub kolejka — a implementacje muszą być idempotentne, tak aby zduplikowana paczka była obsłużona w sposób bezproblemowy.

Te pomiary na poziomie orkiestracji służą widoczności na potrzeby rozliczeń i audytu. Celowo nie są miarodajnym źródłem egzekwowania limitów; decyzje o limitach są podejmowane gdzie indziej we wdrożeniu na podstawie miarodajnej wartości zużycia.

Dlaczego działa to w ten sposób

Pomiary znajdują się na ścieżce rozliczeń i audytu, a nie na ścieżce przetwarzania dokumentów, i to rozdzielenie jest zamierzone. Każde wywołanie record dopisuje jeden niemutowalny MeterEntry do bufora w pamięci, dzięki czemu przechwytywanie zużycia pozostaje operacją O(1). Zrzucanie odbywa się w paczkach, rozprowadzanych do izolowanych backendów za kontraktem MeteringBackendInterface. Wolny lub martwy punkt końcowy rozliczeń degraduje się wtedy łagodnie, a wyczerpana paczka jest logowana i porzucana, a nie rzucana. Dzięki temu awaria pomiarów nigdy nie zatrzymuje pracy o dużym wolumenie ani nie konkuruje z przepustowością dokumentów. Kompromis polega na tym, że pomiary orkiestracji są realizowane na zasadzie najlepszego możliwego wyniku i nie są miarodajne — więc egzekwowanie limitów jest rozstrzygane gdzie indziej na podstawie miarodajnej wartości.

Tło projektowe: Generowanie dokumentów o dużym wolumenie.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Wspierane punkty integracji to kolektor pomiarów (record, flush, bufferCount, registerShutdownFlush), reporter pomiarów (report), interfejs backendu pomiarów (report, isHealthy, backendName) oraz niemutowalny obiekt wartości wpisu pomiarowego. Dostarczenie bezpiecznej dla braku ponowień, idempotentnej implementacji backendu na potrzeby trwałości produkcyjnej jest Twoją odpowiedzialnością.

Przykład kodu — szybki start

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,
);

Przykład kodu — produkcja

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);

Przypadki brzegowe i pułapki

• Zrzut jest idempotentny. Wywołanie flush na pustym buforze nie ma efektu; podwójny zrzut jest bezpieczny.
• Niepowodzenie backendu nie jest krytyczne. Wyczerpane ponowienia logują błąd i porzucają paczkę tego backendu; wywołanie i tak zwraca się normalnie. Nie polegaj na pomiarach w twardym egzekwowaniu limitów.
• Wymagany jest co najmniej jeden backend. Skonstruowanie reportera z pustą listą backendów jest odrzucane.
• Idempotencja to zadanie backendu. Kontrakt interfejsu wymaga, aby backendy deduplikowały (po znaczniku czasu, operacji i najemcy) — ponowiona lub zduplikowana paczka nie może liczyć podwójnie.
• Model pracownika ma znaczenie. Użyj procedury obsługi zamknięcia dla PHP-FPM; użyj zrzutu na okresowym liczniku czasu dla długo działających pracowników, w przeciwnym razie wpisy buforują się aż do zakończenia pracownika.

Wydajność

record to dopisanie do bufora w czasie O(1). Koszt zrzutu jest proporcjonalny do rozmiaru paczki oraz liczby backendów; jest przenoszony poza ścieżkę żądania przez buforowanie oraz przez procedurę obsługi zamknięcia. Ponowienia stosują się per backend, ograniczone skonfigurowaną liczbą prób.

Uwagi dotyczące bezpieczeństwa

Wpisy pomiarowe niosą identyfikatory najemcy i licencji oraz metadane operacji. Traktuj metadane jako potencjalnie wrażliwe i zakreśl przechowywanie i retencję backendu zgodnie z Twoimi wymaganiami zgodności. Identyfikatory najemcy i licencji muszą pochodzić z uwierzytelnionego kontekstu.

Zgodność ze standardami

Pomiary nie definiują własnego formatu przewodowego na granicy publicznej — interfejs backendu deleguje serializację do każdej implementacji backendu (na przykład cel push Prometheus jest zgodny z konwencjami ekspozycji Prometheus). Na tej powierzchni nie jest twierdzony żaden standard zewnętrzny; dla tej strony nie ma cytatu RAG, ponieważ kontraktu kolektora w obrębie procesu nie reguluje żadna specyfikacja normatywna.

Kontrakt zachowania

• Kolektor rejestruje jeden niemutowalny wpis na operację i gromadzi wpisy w buforze w pamięci, który automatycznie zrzuca się przy skonfigurowanym rozmiarze; dostępne są też jawny zrzut oraz procedura zrzutu przy zamknięciu.
• Zrzut jest idempotentny: zrzucenie pustego bufora nie ma efektu, a podwójny zrzut jest bezpieczny.
• Reporter rozprowadza paczkę do jednego lub wielu backendów z izolacją per backend; niepowodzenie jednego backendu nie powstrzymuje pozostałych.
• Każde dostarczenie do backendu jest ponawiane do skonfigurowanej liczby prób; wyczerpane ponowienia są logowane i porzucane — pomiary są realizowane na zasadzie najlepszego możliwego wyniku i nigdy nie rzucają wyjątku na ścieżkę przetwarzania.
• Skonstruowanie reportera z pustą listą backendów jest odrzucane; backendy muszą być idempotentne, tak aby zduplikowana paczka nie liczyła podwójnie.
• record to dopisanie do bufora w czasie O(1); koszt zrzutu jest proporcjonalny do rozmiaru paczki i liczby backendów oraz jest utrzymywany poza ścieżką żądania.

Granica publikacji

Ta strona dokumentuje wyłącznie obserwowalne z zewnątrz zachowanie oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie awaryjne w Core

NextPDF Core (Apache-2.0) nie ma kolektora pomiarów, reportera ani powierzchni backendu — żadnej; ta możliwość nie ma odpowiednika na poziomie Core. Przetwarzanie w Core nie jest mierzone przez NextPDF.

Rozwiązanie awaryjne w Pro

NextPDF Pro nie ma powierzchni pomiarów — żadnej; ta możliwość nie ma odpowiednika na poziomie Pro. Kolektor pomiarów, reporter oraz interfejs backendu są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Cykl życia bufora, rozprowadzanie, ponowienia oraz izolacja są opisane na poziomie zachowania. Interfejs backendu deleguje serializację do każdej implementacji backendu; wewnętrzne mechanizmy buforowania oraz wszelkie szczegóły wewnętrznego rozprowadzania są poza zakresem powierzchni publicznej.

Granica wdrożenia

Operator jest właścicielem implementacji backendów, ich trwałości i idempotencji, zakresu retencji i przechowywania metadanych pomiarowych oraz strategii zrzutu zależnej od modelu pracownika (procedura obsługi zamknięcia dla PHP-FPM, okresowy licznik czasu dla długo działających pracowników). Awaria backendu pomiarów nigdy nie pogarsza przetwarzania dokumentów. Identyfikatory najemcy i licencji muszą pochodzić z uwierzytelnionego kontekstu, który konfiguruje operator.

Granica zgodności prawnej

Do powierzchni pomiarów nie ma zastosowania żadna prawna brama kontroli eksportu. Metadane pomiarowe mogą być wrażliwe; zakres retencji i przechowywania jest odpowiedzialnością operatora w zakresie zgodności. Niniejsza dokumentacja nie stanowi opinii prawnej; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz także

• Referencja pomiarów — NextPDF Enterprise
• Billing — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Licensing — NextPDF Enterprise