Enterprise editie

Verbruiksmeting

In het kort

NextPDF Enterprise verzamelt verbruiksmetering — operaties, verwerkte pagina’s, duur — op de PHP-orkestratielaag voor facturering en audit. Entries worden in het geheugen gebufferd, in batches naar een of meer backends geflusht, en een backend-fout blokkeert de verwerking nooit. Deze pagina beschrijft het waarneembare meteringgedrag en het openbare contract.

Beschikbaarheid en licentiëring

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een implementatie zonder die entitlement laadt de klassen van de mogelijkheid niet. Metering is een basis-Enterprise-mogelijkheid zonder aparte vlag per functie. Vergelijk edities en verkrijg een licentie.

Conceptueel overzicht

De meteringcollector registreert één onveranderlijke entry per operatie: een operatietype, een aantal eenheden, een tijdstempel, de tenant- en licentie-identificaties, verwerkte pagina’s, de operatieduur en vrije-vorm-metadata. Entries stapelen zich op in een in-memory buffer. Wanneer de buffer de geconfigureerde grootte bereikt, flusht hij automatisch; je kunt ook expliciet flushen, en een shutdown-handler kan worden geregistreerd zodat een PHP-FPM-worker de rest aan het einde van het request flusht. Een langlopende worker (bijvoorbeeld een Octane- of Symfony-worker) moet in plaats daarvan op een periodieke timer flushen.

De reporter waaiert een batch uit naar een of meer backends. Backends zijn geïsoleerd: een fout in één backend belet de andere niet om de batch te ontvangen. Elke backend-levering wordt tot een geconfigureerd aantal pogingen opnieuw geprobeerd; als alle pogingen mislukken, wordt de batch voor die backend gelogd en verworpen — metering is best-effort en per ontwerp niet-fataal, zodat een meteringstoring de documentverwerking nooit degradeert. Een backend is elke implementatie van de metering-backend-interface — een Prometheus-pushtarget, een facturerings-API, een database of een queue — en implementaties moeten idempotent zijn, zodat een gedupliceerde batch correct wordt afgehandeld.

Deze metering op orkestratieniveau is voor zichtbaarheid van facturering en audit. Het is opzettelijk niet de gezaghebbende bron voor quota-afdwinging; quotabeslissingen worden elders in de implementatie genomen op basis van een gezaghebbend verbruikscijfer.

Waarom het zo werkt

Metering zit op het facturerings-en-auditpad, niet op het documentverwerkingspad, en die scheiding is bewust. Elke record-aanroep voegt één onveranderlijke MeterEntry toe aan een in-memory buffer, zodat het vastleggen van verbruik een O(1)-operatie blijft. Flushen gebeurt in batches, uitgewaaierd naar geïsoleerde backends achter het MeteringBackendInterface-contract. Een traag of dood facturerings-endpoint degradeert dan gracieus, en een uitgeputte batch wordt gelogd en verworpen in plaats van gegooid. Zo laat een meteringstoring werk met hoog volume nooit stokken en concurreert ze niet met de documentdoorvoer. De afweging is dat orkestratiemetering best-effort en niet-gezaghebbend is — dus quota-afdwinging wordt elders beslist op basis van een gezaghebbend cijfer.

Ontwerpachtergrond: Documentgeneratie op hoog volume.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

De ondersteunde integratiepunten zijn de meter-collector (record, flush, bufferCount, registerShutdownFlush), de metering-reporter (report), de metering-backend-interface (report, isHealthy, backendName) en het onveranderlijke meter-entry value object. Een no-retry-veilige, idempotente backend-implementatie aanleveren voor productiedurability is jouw verantwoordelijkheid.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

Flush is idempotent. flush aanroepen op een lege buffer is een no-op; dubbel flushen is veilig.
Backend-fout is niet-fataal. Uitgeputte pogingen loggen een fout en verwerpen de batch van die backend; de aanroep keert nog steeds normaal terug. Vertrouw niet op metering voor harde quota-afdwinging.
Ten minste één backend is vereist. Een reporter construeren met een lege backend-lijst wordt geweigerd.
Idempotentie is de taak van de backend. Het interfacecontract vereist dat backends ontdubbelen (op tijdstempel, operatie en tenant) — een opnieuw geprobeerde of gedupliceerde batch mag niet dubbel tellen.
Het workermodel doet ertoe. Gebruik de shutdown-handler voor PHP-FPM; gebruik een periodieke timer-flush voor langlopende workers, anders bufferen entries totdat de worker afsluit.

Prestaties

record is een O(1) buffer-append. De flushkosten zijn evenredig aan de batchgrootte en het aantal backends; ze worden van het requestpad afgehaald door buffering en door de shutdown-handler. Pogingen gelden per backend, begrensd door het geconfigureerde aantal pogingen.

Beveiligingsnotities

Meteringentries dragen tenant- en licentie-identificaties en operatiemetadata. Behandel metadata als potentieel gevoelig en stem je backend-opslag en bewaring af op je compliancevereisten. De tenant- en licentie-identificaties moeten afkomstig zijn uit geauthenticeerde context.

Conformiteit

Metering definieert op de openbare grens geen eigen wireformat — de backend-interface delegeert de serialisatie aan elke backend-implementatie (bijvoorbeeld volgt een Prometheus-pushtarget de Prometheus-expositieconventies). Op dit oppervlak wordt geen externe standaard geclaimd; er is geen RAG-citatie voor deze pagina omdat geen normatieve specificatie het in-process collectorcontract regelt.

Gedragscontract

De collector registreert één onveranderlijke entry per operatie en stapelt entries op in een in-memory buffer die automatisch flusht bij zijn geconfigureerde grootte; expliciete flush en een shutdown-flush-handler zijn ook beschikbaar.
Flush is idempotent: een lege buffer flushen is een no-op en dubbel flushen is veilig.
De reporter waaiert een batch uit naar een of meer backends met isolatie per backend; de fout van één backend belet de andere niet.
Elke backend-levering wordt tot het geconfigureerde aantal pogingen opnieuw geprobeerd; uitgeputte pogingen worden gelogd en verworpen — metering is best-effort en gooit nooit in het verwerkingspad.
Een reporter construeren met een lege backend-lijst wordt geweigerd; backends moeten idempotent zijn, zodat een gedupliceerde batch niet dubbel telt.
record is een O(1) buffer-append; de flushkosten zijn evenredig aan de batchgrootte en het aantal backends en worden van het requestpad gehouden.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde openbare API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Core-terugval

NextPDF Core (Apache-2.0) heeft geen meteringcollector, -reporter of -backendoppervlak — niets; deze mogelijkheid heeft geen equivalent op Core-niveau. Core-verwerking wordt niet door NextPDF gemeten.

Pro-terugval

NextPDF Pro heeft geen meteringoppervlak — niets; deze mogelijkheid heeft geen equivalent op Pro-niveau. De meter-collector, -reporter en backend-interface worden uitsluitend geleverd in het nextpdf/enterprise-pakket.

Opmerking over de Enterprise-grens

De buffer-levenscyclus, de fan-out, de pogingen en de isolatie worden op gedragsniveau beschreven. De backend-interface delegeert de serialisatie aan elke backend-implementatie; interne buffering-internals en elk intern fan-out-detail vallen buiten de scope van het openbare oppervlak.

Implementatiegrens

De operator is eigenaar van de backend-implementaties, hun durability en idempotentie, de bewaar- en opslagscope van meteringmetadata, en de flushstrategie van het workermodel (shutdown-handler voor PHP-FPM, periodieke timer voor langlopende workers). Een storing van een meteringbackend degradeert de documentverwerking nooit. Tenant- en licentie-identificaties moeten afkomstig zijn uit een geauthenticeerde context die de operator configureert.

Juridische-compliancegrens

Op het meteringoppervlak geldt geen exportcontrolebeperking. Meteringmetadata kan gevoelig zijn; de bewaar- en opslagscope is de compliance-verantwoordelijkheid van de operator. Deze documentatie is geen juridisch advies; raadpleeg je eigen compliance- en juridische adviseurs.