Enterprise Edition

Verbrauchsmessung

Auf einen Blick

NextPDF Enterprise erfasst die Verbrauchsmessung — Operationen, verarbeitete Seiten, Dauern — auf der PHP-Orchestrierungsebene für Abrechnung und Audit. Einträge werden im Arbeitsspeicher gepuffert, in Batches an ein oder mehrere Backends geleert, und ein Backend-Fehler blockiert niemals die Verarbeitung. Diese Seite beschreibt das beobachtbare Metering-Verhalten und den öffentlichen Vertrag.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird mit NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einem Lizenzumschlag der Enterprise-Stufe. Ein Deployment ohne diese Berechtigung lädt die Klassen dieser Fähigkeit nicht. Metering ist eine grundlegende Enterprise-Fähigkeit ohne separates Flag pro Feature. Editionen vergleichen und eine Lizenz erwerben.

Konzeptioneller Überblick

Der Metering-Collector erfasst einen unveränderlichen Eintrag pro Operation: einen Operationstyp, eine Einheitenanzahl, einen Zeitstempel, die Mandanten- und Lizenz-Identifikatoren, verarbeitete Seiten, die Operationsdauer und freiformatige Metadaten. Einträge sammeln sich in einem speicherinternen Puffer an. Wenn der Puffer seine konfigurierte Größe erreicht, leert er sich automatisch; Sie können auch explizit leeren, und ein Shutdown-Handler kann registriert werden, sodass ein PHP-FPM-Worker jeden Rest am Anfrageende leert. Ein langlaufender Worker (zum Beispiel ein Octane- oder Symfony-Worker) sollte stattdessen über einen periodischen Timer leeren.

Der Reporter fächert einen Batch an ein oder mehrere Backends auf. Backends sind isoliert: Ein Fehler in einem Backend hindert die anderen nicht daran, den Batch zu empfangen. Jede Backend-Zustellung wird bis zu einer konfigurierten Versuchsanzahl wiederholt; scheitern alle Versuche, wird der Batch für dieses Backend protokolliert und verworfen — Metering ist per Design Best-Effort und nicht fatal, sodass ein Metering-Ausfall niemals die Dokumentverarbeitung beeinträchtigt. Ein Backend ist jede Implementierung des Metering-Backend-Interface — ein Prometheus-Push-Target, eine Billing-API, eine Datenbank oder eine Queue —, und Implementierungen müssen idempotent sein, sodass ein duplizierter Batch sauber behandelt wird.

Diese Metering-Erfassung auf Orchestrierungsebene dient der Sichtbarkeit für Abrechnung und Audit. Sie ist absichtlich nicht die maßgebliche Quelle für die Kontingentdurchsetzung; Kontingententscheidungen werden anderswo im Deployment aus einer maßgeblichen Nutzungszahl getroffen.

Warum es so funktioniert

Metering liegt auf dem Abrechnungs- und Audit-Pfad, nicht auf dem Dokumentverarbeitungs-Pfad, und diese Trennung ist bewusst gewählt. Jeder record-Aufruf hängt einen unveränderlichen MeterEntry an einen speicherinternen Puffer an, sodass das Erfassen der Nutzung eine O(1)-Operation bleibt. Das Leeren erfolgt in Batches, aufgefächert an isolierte Backends hinter dem Vertrag MeteringBackendInterface. Ein langsamer oder toter Billing-Endpunkt verschlechtert sich dann graziös, und ein erschöpfter Batch wird protokolliert und verworfen statt geworfen. So bremst ein Metering-Ausfall niemals Arbeit mit hohem Volumen aus und konkurriert nicht mit dem Dokumentdurchsatz. Der Kompromiss besteht darin, dass die Orchestrierungs-Verbrauchsmessung Best-Effort und nicht maßgeblich ist — die Kontingentdurchsetzung wird daher anderswo aus einer maßgeblichen Zahl entschieden.

Design-Hintergrund: Dokumentgenerierung mit hohem Volumen.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Die unterstützten Integrationspunkte sind der Meter-Collector (record, flush, bufferCount, registerShutdownFlush), der Metering-Reporter (report), das Metering-Backend-Interface (report, isHealthy, backendName) und das unveränderliche Meter-Entry-Value-Object. Eine No-Retry-sichere, idempotente Backend-Implementierung für die Produktionshaltbarkeit bereitzustellen, liegt in Ihrer Verantwortung.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Sonderfälle & Fallstricke

Das Leeren ist idempotent. Ein Aufruf von flush auf einem leeren Puffer ist ein No-op; ein doppeltes Leeren ist sicher.
Ein Backend-Fehler ist nicht fatal. Erschöpfte Wiederholungen protokollieren einen Fehler und verwerfen den Batch dieses Backends; der Aufruf kehrt dennoch normal zurück. Verlassen Sie sich für eine harte Kontingentdurchsetzung nicht auf Metering.
Mindestens ein Backend ist erforderlich. Das Konstruieren eines Reporters mit einer leeren Backend-Liste wird abgelehnt.
Idempotenz ist Aufgabe des Backends. Der Interface-Vertrag verlangt, dass Backends deduplizieren (nach Zeitstempel, Operation und Mandant) — ein wiederholter oder duplizierter Batch darf nicht doppelt zählen.
Das Worker-Modell ist entscheidend. Verwenden Sie den Shutdown-Handler für PHP-FPM; verwenden Sie ein periodisches Timer-Leeren für langlaufende Worker, sonst puffern Einträge, bis der Worker beendet wird.

Performance

record ist ein O(1)-Puffer-Append. Die Leerungskosten sind proportional zur Batch-Größe und zur Anzahl der Backends; sie werden durch Pufferung und durch den Shutdown-Handler vom Request-Pfad entfernt. Wiederholungen gelten pro Backend, begrenzt durch die konfigurierte Versuchsanzahl.

Sicherheitshinweise

Metering-Einträge tragen Mandanten- und Lizenz-Identifikatoren und Operations-Metadaten. Behandeln Sie Metadaten als potenziell sensibel und begrenzen Sie die Speicherung und Aufbewahrung Ihres Backends auf Ihre Compliance-Anforderungen. Die Mandanten- und Lizenz-Identifikatoren müssen aus einem authentifizierten Kontext stammen.

Konformität

Metering definiert an der öffentlichen Grenze kein eigenes Wire-Format — das Backend-Interface delegiert die Serialisierung an jede Backend-Implementierung (zum Beispiel folgt ein Prometheus-Push-Target den Prometheus-Exposition-Konventionen). An dieser Oberfläche wird kein externer Standard beansprucht; für diese Seite gibt es keine RAG-Zitation, weil keine normative Spezifikation den In-process-Collector-Vertrag regelt.

Verhaltensvertrag

Der Collector erfasst einen unveränderlichen Eintrag pro Operation und sammelt Einträge in einem speicherinternen Puffer, der sich bei seiner konfigurierten Größe automatisch leert; ein explizites Leeren und ein Shutdown-Flush-Handler sind ebenfalls verfügbar.
Das Leeren ist idempotent: Das Leeren eines leeren Puffers ist ein No-op, und ein doppeltes Leeren ist sicher.
Der Reporter fächert einen Batch an ein oder mehrere Backends mit Isolierung pro Backend auf; der Fehler eines Backends hält die anderen nicht auf.
Jede Backend-Zustellung wird bis zur konfigurierten Versuchsanzahl wiederholt; erschöpfte Wiederholungen werden protokolliert und verworfen — Metering ist Best-Effort und wirft niemals in den Verarbeitungspfad.
Das Konstruieren eines Reporters mit einer leeren Backend-Liste wird abgelehnt; Backends müssen idempotent sein, sodass ein duplizierter Batch nicht doppelt zählt.
record ist ein O(1)-Puffer-Append; die Leerungskosten sind proportional zur Batch-Größe und zur Backend-Anzahl und werden vom Request-Pfad ferngehalten.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Core-Fallback

NextPDF Core (Apache-2.0) hat keinen Metering-Collector, keinen Reporter und keine Backend-Oberfläche — keine; diese Fähigkeit hat kein Äquivalent in der Core-Stufe. Die Core-Verarbeitung wird von NextPDF nicht gemessen.

Pro-Fallback

NextPDF Pro hat keine Metering-Oberfläche — keine; diese Fähigkeit hat kein Äquivalent in der Pro-Stufe. Der Meter-Collector, der Reporter und das Backend-Interface werden ausschließlich im Paket nextpdf/enterprise ausgeliefert.

Hinweis zur Enterprise-Grenze

Der Pufferlebenszyklus, das Fan-out, die Wiederholung und die Isolierung werden auf Verhaltensebene beschrieben. Das Backend-Interface delegiert die Serialisierung an jede Backend-Implementierung; interne Pufferungs-Interna und jegliches interne Fan-out-Detail liegen außerhalb des Umfangs der öffentlichen Oberfläche.

Deployment-Grenze

Der Betreiber besitzt die Backend-Implementierungen, deren Haltbarkeit und Idempotenz, den Aufbewahrungs- und Speicherumfang der Metering-Metadaten und die Flush-Strategie des Worker-Modells (Shutdown-Handler für PHP-FPM, periodischer Timer für langlaufende Worker). Ein Metering-Backend-Ausfall beeinträchtigt niemals die Dokumentverarbeitung. Mandanten- und Lizenz-Identifikatoren müssen aus einem authentifizierten Kontext stammen, den der Betreiber konfiguriert.

Grenze der rechtlichen Compliance

Auf die Metering-Oberfläche findet keine exportkontrollrechtliche Beschränkung Anwendung. Metering-Metadaten können sensibel sein; Aufbewahrungs- und Speicherumfang liegen in der Compliance-Verantwortung des Betreibers. Diese Dokumentation ist kein Rechtsgutachten; konsultieren Sie Ihre eigenen Compliance- und Rechtsberater.