Enterprise édition

Comptage de l'usage

En bref

NextPDF Enterprise collecte la mesure d’utilisation — opérations, pages traitées, durées — au niveau de la couche d’orchestration PHP, à des fins de facturation et d’audit. Les entrées sont mises en tampon en mémoire, vidées vers un ou plusieurs backends par lots, et un échec de backend ne bloque jamais le traitement. Cette page décrit le comportement observable de la mesure d’utilisation et le contrat public.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de palier Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. La mesure d’utilisation est une capacité Enterprise de base, sans indicateur distinct par fonctionnalité. Compare les éditions et obtiens une licence.

Aperçu conceptuel

Le collecteur de mesure enregistre une entrée immuable par opération : un type d’opération, un nombre d’unités, un horodatage, les identifiants de locataire et de licence, les pages traitées, la durée de l’opération et des métadonnées libres. Les entrées s’accumulent dans un tampon en mémoire. Quand le tampon atteint sa taille configurée, il se vide automatiquement ; tu peux aussi le vider explicitement, et un gestionnaire d’arrêt peut être enregistré pour qu’un worker PHP-FPM vide tout reliquat à la fin de la requête. Un worker de longue durée (par exemple un worker Octane ou Symfony) devrait plutôt vider sur un minuteur périodique.

Le rapporteur répartit un lot vers un ou plusieurs backends. Les backends sont isolés : un échec dans un backend n’empêche pas les autres de recevoir le lot. Chaque livraison de backend est retentée jusqu’à un nombre de tentatives configuré ; si toutes les tentatives échouent, le lot de ce backend est journalisé puis abandonné — la mesure est au mieux et non fatale par conception, de sorte qu’une panne de mesure ne dégrade jamais le traitement des documents. Un backend est toute implémentation de l’interface de backend de mesure — une cible de push Prometheus, une API de facturation, une base de données ou une file — et les implémentations doivent être idempotentes pour qu’un lot dupliqué soit géré sans heurt.

Cette mesure au niveau de l’orchestration sert la visibilité de facturation et d’audit. Elle n’est intentionnellement pas la source faisant autorité pour l’application des quotas ; les décisions de quota sont prises ailleurs dans le déploiement, à partir d’un chiffre d’utilisation faisant autorité.

Pourquoi ça fonctionne ainsi

La mesure se situe sur le chemin de facturation et d’audit, pas sur le chemin de traitement des documents, et cette séparation est délibérée. Chaque appel à record ajoute une MeterEntry immuable à un tampon en mémoire, si bien que capturer l’usage reste une opération O(1). Le vidage se fait par lots, répartis vers des backends isolés derrière le contrat MeteringBackendInterface. Un point de terminaison de facturation lent ou mort se dégrade alors avec élégance, et un lot épuisé est journalisé puis abandonné plutôt que lancé en exception. Ainsi, une panne de mesure ne bloque jamais un travail à haut volume ni ne concurrence le débit documentaire. Le compromis, c’est que la mesure d’orchestration est au mieux et non faisant autorité — l’application des quotas est donc décidée ailleurs à partir d’un chiffre faisant autorité.

Contexte de conception : Génération de documents à haut volume.

Surface d’API publique

composer require nextpdf/enterprise:^3

Les points d’intégration pris en charge sont le collecteur de mesure (record, flush, bufferCount, registerShutdownFlush), le rapporteur de mesure (report), l’interface de backend de mesure (report, isHealthy, backendName) et l’objet-valeur immuable d’entrée de mesure. Fournir une implémentation de backend idempotente et sûre face aux re-tentatives, pour la durabilité en production, relève de ta responsabilité.

Exemple de code — démarrage rapide

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

Exemple de code — production

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

Cas limites et pièges

Le vidage est idempotent. Appeler flush sur un tampon vide est sans effet ; un double vidage est sûr.
Un échec de backend est non fatal. Des re-tentatives épuisées journalisent une erreur et abandonnent le lot de ce backend ; l’appel revient quand même normalement. Ne te repose pas sur la mesure pour une application stricte des quotas.
Au moins un backend est requis. Construire un rapporteur avec une liste de backends vide est rejeté.
L’idempotence est l’affaire du backend. Le contrat d’interface exige des backends qu’ils déduplent (par horodatage, opération et locataire) — un lot retenté ou dupliqué ne doit pas compter deux fois.
Le modèle de worker compte. Utilise le gestionnaire d’arrêt pour PHP-FPM ; utilise un vidage sur minuteur périodique pour les workers de longue durée, sinon les entrées restent en tampon jusqu’à la sortie du worker.

Performance

record est un ajout O(1) au tampon. Le coût de vidage est proportionnel à la taille du lot et au nombre de backends ; il est déplacé hors du chemin de requête par la mise en tampon et par le gestionnaire d’arrêt. Les re-tentatives s’appliquent par backend, bornées par le nombre de tentatives configuré.

Notes de sécurité

Les entrées de mesure portent les identifiants de locataire et de licence ainsi que des métadonnées d’opération. Traite les métadonnées comme potentiellement sensibles et délimite le stockage et la rétention de ton backend selon tes exigences de conformité. Les identifiants de locataire et de licence doivent provenir d’un contexte authentifié.

Conformité

La mesure ne définit aucun format de transmission qui lui soit propre à la frontière publique — l’interface de backend délègue la sérialisation à chaque implémentation de backend (par exemple, une cible de push Prometheus suit les conventions d’exposition Prometheus). Aucune norme externe n’est affirmée à cette surface ; il n’y a pas de citation RAG pour cette page, car aucune spécification normative ne régit le contrat du collecteur en cours de processus.

Contrat de comportement

Le collecteur enregistre une entrée immuable par opération et accumule les entrées dans un tampon en mémoire qui se vide automatiquement à sa taille configurée ; un vidage explicite et un gestionnaire de vidage à l’arrêt sont également disponibles.
Le vidage est idempotent : vider un tampon vide est sans effet et un double vidage est sûr.
Le rapporteur répartit un lot vers un ou plusieurs backends avec une isolation par backend ; l’échec d’un backend n’arrête pas les autres.
Chaque livraison de backend est retentée jusqu’au nombre de tentatives configuré ; les re-tentatives épuisées sont journalisées puis abandonnées — la mesure est au mieux et ne lance jamais d’exception dans le chemin de traitement.
Construire un rapporteur avec une liste de backends vide est rejeté ; les backends doivent être idempotents pour qu’un lot dupliqué ne compte pas deux fois.
record est un ajout O(1) au tampon ; le coût de vidage est proportionnel à la taille du lot et au nombre de backends et reste hors du chemin de requête.

Frontière de publication

Cette page documente uniquement un comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Repli Core

NextPDF Core (Apache-2.0) n’a aucun collecteur, rapporteur ni surface de backend de mesure — aucun ; cette capacité n’a pas d’équivalent de palier Core. Le traitement Core n’est pas mesuré par NextPDF.

Repli Pro

NextPDF Pro n’a aucune surface de mesure — aucune ; cette capacité n’a pas d’équivalent de palier Pro. Le collecteur de mesure, le rapporteur et l’interface de backend sont livrés dans le seul paquet nextpdf/enterprise.

Note sur la frontière Enterprise

Le cycle de vie du tampon, la répartition, les re-tentatives et l’isolation sont décrits au niveau du comportement. L’interface de backend délègue la sérialisation à chaque implémentation de backend ; les détails internes de la mise en tampon et tout détail interne de répartition sont hors du périmètre de la surface publique.

Frontière de déploiement

L’opérateur possède les implémentations de backend, leur durabilité et leur idempotence, l’étendue de rétention et de stockage des métadonnées de mesure, et la stratégie de vidage selon le modèle de worker (gestionnaire d’arrêt pour PHP-FPM, minuteur périodique pour les workers de longue durée). Une panne de backend de mesure ne dégrade jamais le traitement des documents. Les identifiants de locataire et de licence doivent provenir d’un contexte authentifié que l’opérateur configure.

Frontière de conformité légale

Aucune restriction de contrôle des exportations ne s’applique à la surface de mesure. Les métadonnées de mesure peuvent être sensibles ; l’étendue de rétention et de stockage relève de la responsabilité de conformité de l’opérateur. Cette documentation n’est pas un avis juridique ; consulte tes propres conseillers en conformité et juridiques.