Enterprise edición

Medición de uso

De un vistazo

NextPDF Enterprise recopila la medición de uso —operaciones, páginas procesadas, duraciones— en la capa de orquestación de PHP para facturación y auditoría. Las entradas se almacenan en búfer en memoria, se vuelcan a uno o más backends por lotes, y el fallo de un backend nunca bloquea el procesamiento. Esta página describe el comportamiento observable de la medición y el contrato público.

Disponibilidad y licenciamiento

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin esa titularidad no carga las clases de la capacidad. La medición es una capacidad base de Enterprise sin ningún indicador por característica independiente. Comparar ediciones y obtener una licencia.

Descripción conceptual

El recopilador de medición registra una entrada inmutable por operación: un tipo de operación, un recuento de unidades, una marca de tiempo, los identificadores de inquilino y de licencia, las páginas procesadas, la duración de la operación y metadatos de formato libre. Las entradas se acumulan en un búfer en memoria. Cuando el búfer alcanza su tamaño configurado, se vuelca automáticamente; también se puede volcar de forma explícita, y se puede registrar un manejador de cierre para que un worker de PHP-FPM vuelque cualquier resto al final de la petición. Un worker de larga duración (por ejemplo, un worker de Octane o de Symfony) debería volcar mediante un temporizador periódico en su lugar.

El reportador reparte un lote entre uno o más backends. Los backends están aislados: un fallo en un backend no impide que los demás reciban el lote. Cada entrega a un backend se reintenta hasta un número de intentos configurado; si todos los intentos fallan, el lote para ese backend se registra y se descarta —la medición es de mejor esfuerzo y no fatal por diseño, de modo que una interrupción de la medición nunca degrada el procesamiento de documentos—. Un backend es cualquier implementación de la interfaz de backend de medición —un destino de push de Prometheus, una API de facturación, una base de datos o una cola— y se exige que las implementaciones sean idempotentes para que un lote duplicado se gestione con elegancia.

Esta medición a nivel de orquestación es para la visibilidad de facturación y auditoría. No es, deliberadamente, la fuente autorizada para la aplicación de cuotas; las decisiones de cuota se toman en otro lugar del despliegue a partir de una cifra de uso autorizada.

Por qué funciona así

La medición se sitúa en la ruta de facturación y auditoría, no en la ruta de procesamiento de documentos, y esa separación es deliberada. Cada llamada a record añade una MeterEntry inmutable a un búfer en memoria, de modo que capturar el uso sigue siendo una operación O(1). El volcado ocurre por lotes, repartidos entre backends aislados tras el contrato MeteringBackendInterface. Un endpoint de facturación lento o inactivo se degrada entonces con elegancia, y un lote agotado se registra y se descarta en lugar de lanzarse. Así, una interrupción de la medición nunca detiene el trabajo de gran volumen ni compite con el rendimiento del procesamiento de documentos. La contrapartida es que la medición de orquestación es de mejor esfuerzo y no autorizada, por lo que la aplicación de cuotas se decide en otro lugar a partir de una cifra autorizada.

Contexto de diseño: Generación de documentos de gran volumen.

Superficie pública de la API

composer require nextpdf/enterprise:^3

Los puntos de integración admitidos son el recopilador de medición (record, flush, bufferCount, registerShutdownFlush), el reportador de medición (report), la interfaz de backend de medición (report, isHealthy, backendName) y el objeto de valor inmutable de entrada de medición. Proporcionar una implementación de backend idempotente y segura ante reintentos para la durabilidad en producción es su responsabilidad.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

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

Casos límite y aspectos a tener en cuenta

El volcado es idempotente. Llamar a flush sobre un búfer vacío es una operación sin efecto; un doble volcado es seguro.
El fallo de un backend no es fatal. Los reintentos agotados registran un error y descartan el lote de ese backend; la llamada aun así devuelve con normalidad. No confíe en la medición para una aplicación estricta de cuotas.
Se requiere al menos un backend. Construir un reportador con una lista de backends vacía se rechaza.
La idempotencia es tarea del backend. El contrato de la interfaz exige que los backends deduplican (por marca de tiempo, operación e inquilino): un lote reintentado o duplicado no debe contar dos veces.
El modelo de worker importa. Use el manejador de cierre para PHP-FPM; use un volcado por temporizador periódico para los workers de larga duración, o las entradas se acumulan en el búfer hasta que el worker termina.

Rendimiento

record es una adición al búfer O(1). El coste del volcado es proporcional al tamaño del lote y al número de backends; se saca de la ruta de la petición mediante el almacenamiento en búfer y el manejador de cierre. Los reintentos se aplican por backend, acotados por el número de intentos configurado.

Notas de seguridad

Las entradas de medición llevan identificadores de inquilino y de licencia y metadatos de operación. Trate los metadatos como potencialmente sensibles y limite el almacenamiento y la conservación de su backend según sus requisitos de cumplimiento. Los identificadores de inquilino y de licencia deben proceder de un contexto autenticado.

Conformidad

La medición no define ningún formato de transmisión propio en la frontera pública: la interfaz de backend delega la serialización en cada implementación de backend (por ejemplo, un destino de push de Prometheus sigue las convenciones de exposición de Prometheus). No se afirma ningún estándar externo en esta superficie; no hay ninguna citación RAG para esta página porque ninguna especificación normativa rige el contrato del recopilador en proceso.

Contrato de comportamiento

El recopilador registra una entrada inmutable por operación y acumula las entradas en un búfer en memoria que se vuelca automáticamente al alcanzar su tamaño configurado; también están disponibles el volcado explícito y un manejador de volcado en el cierre.
El volcado es idempotente: volcar un búfer vacío es una operación sin efecto y un doble volcado es seguro.
El reportador reparte un lote entre uno o más backends con aislamiento por backend; el fallo de un backend no detiene a los demás.
Cada entrega a un backend se reintenta hasta el número de intentos configurado; los reintentos agotados se registran y se descartan —la medición es de mejor esfuerzo y nunca lanza una excepción en la ruta de procesamiento—.
Construir un reportador con una lista de backends vacía se rechaza; se exige que los backends sean idempotentes para que un lote duplicado no cuente dos veces.
record es una adición al búfer O(1); el coste del volcado es proporcional al tamaño del lote y al número de backends y se mantiene fuera de la ruta de la petición.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie pública de la API admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene ninguna superficie de recopilador, reportador ni backend de medición —ninguna; esta capacidad no tiene equivalente en el nivel Core—. NextPDF no mide el procesamiento de Core.

Alternativa de Pro

NextPDF Pro no tiene ninguna superficie de medición —ninguna; esta capacidad no tiene equivalente en el nivel Pro—. El recopilador de medición, el reportador y la interfaz de backend se incluyen únicamente en el paquete nextpdf/enterprise.

Nota sobre la frontera de Enterprise

El ciclo de vida del búfer, el reparto, el reintento y el aislamiento se describen a nivel de comportamiento. La interfaz de backend delega la serialización en cada implementación de backend; los detalles internos del almacenamiento en búfer y cualquier detalle interno del reparto quedan fuera del alcance de la superficie pública.

Frontera de despliegue

El operador es dueño de las implementaciones de backend, de su durabilidad e idempotencia, del alcance de conservación y almacenamiento de los metadatos de medición y de la estrategia de volcado del modelo de worker (manejador de cierre para PHP-FPM, temporizador periódico para los workers de larga duración). Una interrupción de un backend de medición nunca degrada el procesamiento de documentos. Los identificadores de inquilino y de licencia deben proceder de un contexto autenticado que el operador configura.

Frontera de cumplimiento legal

No se aplica ninguna restricción de control de exportaciones a la superficie de medición. Los metadatos de medición pueden ser sensibles; el alcance de conservación y almacenamiento es responsabilidad de cumplimiento del operador. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.