Misurazione

In sintesi

NextPDF Enterprise raccoglie la misurazione dell’utilizzo — operazioni, pagine elaborate, durate — a livello del layer di orchestrazione PHP per fatturazione e audit. Le voci sono bufferizzate in memoria, scaricate a uno o più backend in batch e il fallimento di un backend non blocca mai l’elaborazione. Questa pagina descrive il comportamento di misurazione osservabile e il contratto pubblico.

Disponibilità e licenza

Questa capability è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale entitlement non carica le classi della capability. La misurazione è una capability Enterprise di base, senza un flag per-feature separato. Confronta le edizioni e ottieni una licenza.

Panoramica concettuale

Il collector di misurazione registra una voce immutabile per ciascuna operazione: un tipo di operazione, un conteggio di unità, un timestamp, gli identificatori del tenant e della licenza, le pagine elaborate, la durata dell’operazione e metadati in forma libera. Le voci si accumulano in un buffer in memoria. Quando il buffer raggiunge la sua dimensione configurata si scarica automaticamente; è inoltre possibile scaricarlo esplicitamente, e può essere registrato un handler di shutdown affinché un worker PHP-FPM scarichi qualsiasi rimanenza alla fine della richiesta. Un worker a lunga durata (per esempio un worker Octane o Symfony) dovrebbe invece scaricare su un timer periodico.

Il reporter distribuisce un batch a uno o più backend. I backend sono isolati: il fallimento di un backend non impedisce agli altri di ricevere il batch. Ciascuna consegna al backend viene ritentata fino a un numero di tentativi configurato; se tutti i tentativi falliscono, il batch per quel backend viene registrato e scartato — la misurazione è best-effort e non fatale per progettazione, perciò un’interruzione della misurazione non degrada mai l’elaborazione dei documenti. Un backend è una qualsiasi implementazione dell’interfaccia di backend di misurazione — un target di push Prometheus, un’API di fatturazione, un database o una coda — e si richiede che le implementazioni siano idempotenti, in modo che un batch duplicato venga gestito con eleganza.

Questa misurazione a livello di orchestrazione è destinata alla visibilità per fatturazione e audit. Per progettazione non è la fonte autorevole per l’applicazione delle quote; le decisioni sulle quote vengono prese altrove nella distribuzione a partire da un dato di utilizzo autorevole.

Perché funziona così

La misurazione si colloca sul percorso di fatturazione e audit, non su quello di elaborazione dei documenti, e questa separazione è deliberata. Ogni chiamata a record aggiunge una MeterEntry immutabile a un buffer in memoria, così la cattura dell’utilizzo resta un’operazione O(1). Lo scarico avviene in batch, distribuiti a backend isolati dietro il contratto MeteringBackendInterface. Un endpoint di fatturazione lento o morto degrada quindi con eleganza, e un batch esaurito viene registrato e scartato anziché sollevare un’eccezione. Così un’interruzione della misurazione non blocca mai il lavoro ad alto volume né compete con il throughput dei documenti. Il compromesso è che la misurazione di orchestrazione è best-effort e non autorevole — perciò l’applicazione delle quote viene decisa altrove a partire da un dato autorevole.

Contesto di progettazione: Generazione di documenti ad alto volume.

Superficie API pubblica

composer require nextpdf/enterprise:^3

I punti di integrazione supportati sono il meter collector (record, flush, bufferCount, registerShutdownFlush), il reporter di misurazione (report), l’interfaccia di backend di misurazione (report, isHealthy, backendName) e il value object della voce di misurazione immutabile. È vostra responsabilità fornire un’implementazione di backend idempotente e sicura rispetto ai ritentativi per la durabilità in produzione.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e insidie

• Lo scarico è idempotente. Chiamare flush su un buffer vuoto è un no-op; il doppio scarico è sicuro.
• Il fallimento di un backend non è fatale. I ritentativi esauriti registrano un errore e scartano il batch di quel backend; la chiamata ritorna comunque normalmente. Non fare affidamento sulla misurazione per l’applicazione rigida delle quote.
• È richiesto almeno un backend. Costruire un reporter con un elenco di backend vuoto viene rifiutato.
• L’idempotenza è compito del backend. Il contratto dell’interfaccia richiede che i backend deduplichino (per timestamp, operazione e tenant) — un batch ritentato o duplicato non deve generare un doppio conteggio.
• Il modello di worker conta. Usare l’handler di shutdown per PHP-FPM; usare uno scarico su timer periodico per i worker a lunga durata, altrimenti le voci si bufferizzano fino all’uscita del worker.

Prestazioni

record è un append al buffer O(1). Il costo dello scarico è proporzionale alla dimensione del batch e al numero di backend; viene spostato fuori dal percorso della richiesta dalla bufferizzazione e dall’handler di shutdown. I ritentativi si applicano per ciascun backend, limitati dal numero di tentativi configurato.

Note di sicurezza

Le voci di misurazione portano gli identificatori del tenant e della licenza e i metadati dell’operazione. Trattare i metadati come potenzialmente sensibili e limitare l’archiviazione e la conservazione del proprio backend ai propri requisiti di conformità. Gli identificatori del tenant e della licenza devono provenire da un contesto autenticato.

Conformità

La misurazione non definisce alcun formato di trasmissione proprio al confine pubblico — l’interfaccia di backend delega la serializzazione a ciascuna implementazione di backend (per esempio, un target di push Prometheus segue le convenzioni di esposizione Prometheus). A questa superficie non viene asserito alcuno standard esterno; non esiste alcuna citazione RAG per questa pagina perché nessuna specifica normativa regola il contratto del collector in-process.

Contratto di comportamento

• Il collector registra una voce immutabile per ciascuna operazione e accumula le voci in un buffer in memoria che si scarica automaticamente alla sua dimensione configurata; sono inoltre disponibili lo scarico esplicito e un handler di scarico allo shutdown.
• Lo scarico è idempotente: scaricare un buffer vuoto è un no-op e il doppio scarico è sicuro.
• Il reporter distribuisce un batch a uno o più backend con isolamento per ciascun backend; il fallimento di un backend non blocca gli altri.
• Ciascuna consegna al backend viene ritentata fino al numero di tentativi configurato; i ritentativi esauriti vengono registrati e scartati — la misurazione è best-effort e non solleva mai eccezioni nel percorso di elaborazione.
• Costruire un reporter con un elenco di backend vuoto viene rifiutato; si richiede che i backend siano idempotenti, in modo che un batch duplicato non generi un doppio conteggio.
• record è un append al buffer O(1); il costo dello scarico è proporzionale alla dimensione del batch e al numero di backend ed è tenuto fuori dal percorso della richiesta.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Fallback di Core

NextPDF Core (Apache-2.0) non dispone di alcun collector, reporter o superficie di backend di misurazione — nessuno; questa capability non ha un equivalente di livello Core. L’elaborazione di Core non viene misurata da NextPDF.

Fallback di Pro

NextPDF Pro non dispone di alcuna superficie di misurazione — nessuna; questa capability non ha un equivalente di livello Pro. Il meter collector, il reporter e l’interfaccia di backend sono inclusi esclusivamente nel pacchetto nextpdf/enterprise.

Nota sul confine Enterprise

Il ciclo di vita del buffer, il fan-out, il ritentativo e l’isolamento sono descritti a livello di comportamento. L’interfaccia di backend delega la serializzazione a ciascuna implementazione di backend; le componenti interne di bufferizzazione e qualsiasi dettaglio interno di fan-out sono fuori ambito per la superficie pubblica.

Confine di distribuzione

L’operatore possiede le implementazioni dei backend, la loro durabilità e idempotenza, l’ambito di conservazione e archiviazione dei metadati di misurazione e la strategia di scarico in base al modello di worker (handler di shutdown per PHP-FPM, timer periodico per i worker a lunga durata). Un’interruzione di un backend di misurazione non degrada mai l’elaborazione dei documenti. Gli identificatori del tenant e della licenza devono provenire da un contesto autenticato configurato dall’operatore.

Confine di conformità legale

Nessuna restrizione di controllo delle esportazioni si applica alla superficie di misurazione. I metadati di misurazione possono essere sensibili; l’ambito di conservazione e archiviazione è una responsabilità di conformità dell’operatore. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.

Vedere anche

• Riferimento sulla misurazione — NextPDF Enterprise
• Billing — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Licensing — NextPDF Enterprise