Medição

Em resumo

O NextPDF Enterprise coleta a medição de uso — operações, páginas processadas, durações — na camada de orquestração PHP para fins de cobrança e auditoria. As entradas são armazenadas em buffer na memória, descarregadas (flush) para um ou mais backends em lotes, e uma falha de backend nunca bloqueia o processamento. Esta página descreve o comportamento de medição observável e o contrato público.

Disponibilidade e licenciamento

Esta capacidade é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem essa habilitação não carrega as classes da capacidade. A medição é uma capacidade base do Enterprise, sem uma flag por recurso separada. Compare as edições e obtenha uma licença.

Visão conceitual

O coletor de medição registra uma entrada imutável por operação: um tipo de operação, uma contagem de unidades, um timestamp, os identificadores de tenant e de licença, as páginas processadas, a duração da operação e metadados de formato livre. As entradas se acumulam em um buffer em memória. Quando o buffer atinge seu tamanho configurado, ele faz auto-flush; você também pode descarregar explicitamente, e um manipulador de shutdown pode ser registrado para que um worker PHP-FPM descarregue qualquer remanescente ao fim da requisição. Um worker de longa duração (por exemplo, um worker Octane ou Symfony) deve descarregar em um temporizador periódico.

O reporter distribui (fan-out) um lote para um ou mais backends. Os backends são isolados: uma falha em um backend não impede que os demais recebam o lote. Cada entrega de backend é repetida até uma contagem de tentativas configurada; se todas as tentativas falharem, o lote para aquele backend é registrado em log e descartado — a medição é de melhor esforço e não fatal por design, de modo que uma indisponibilidade de medição nunca degrada o processamento de documentos. Um backend é qualquer implementação da interface de backend de medição — um destino de push do Prometheus, uma API de cobrança, um banco de dados ou uma fila — e as implementações são obrigadas a ser idempotentes, de modo que um lote duplicado seja tratado de forma adequada.

Esta medição em nível de orquestração serve à visibilidade de cobrança e auditoria. Ela intencionalmente não é a fonte autoritativa para a imposição de cotas; as decisões de cota são tomadas em outro lugar da implantação, a partir de um valor de uso autoritativo.

Por que funciona assim

A medição fica no caminho de cobrança e auditoria, não no caminho de processamento de documentos, e essa separação é deliberada. Cada chamada record anexa uma entrada MeterEntry imutável a um buffer em memória, de modo que a captura de uso permanece uma operação O(1). O flush acontece em lotes, distribuídos para backends isolados por trás do contrato MeteringBackendInterface. Um endpoint de cobrança lento ou morto então degrada de forma controlada, e um lote esgotado é registrado em log e descartado em vez de lançar uma exceção. Assim, uma indisponibilidade de medição nunca trava um trabalho de alto volume nem compete pela vazão de documentos. O trade-off é que a medição de orquestração é de melhor esforço e não autoritativa — portanto, a imposição de cotas é decidida em outro lugar a partir de um valor autoritativo.

Contexto de design: Geração de documentos em alto volume.

Superfície pública de API

composer require nextpdf/enterprise:^3

Os pontos de integração suportados são o coletor de medição (record, flush, bufferCount, registerShutdownFlush), o reporter de medição (report), a interface de backend de medição (report, isHealthy, backendName) e o objeto de valor de entrada de medição imutável. É sua responsabilidade fornecer uma implementação de backend idempotente e segura sem repetições para a durabilidade em produção.

Exemplo de código — início 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,
);

Exemplo de código — produção

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 extremos e pegadinhas

• O flush é idempotente. Chamar flush em um buffer vazio é um no-op; um flush duplo é seguro.
• A falha de backend não é fatal. Tentativas esgotadas registram um erro em log e descartam o lote daquele backend; a chamada ainda retorna normalmente. Não dependa da medição para a imposição rígida de cotas.
• É necessário pelo menos um backend. Construir um reporter com uma lista de backends vazia é rejeitado.
• A idempotência é tarefa do backend. O contrato da interface exige que os backends façam deduplicação (por timestamp, operação e tenant) — um lote repetido ou duplicado não deve contar em dobro.
• O modelo de worker importa. Use o manipulador de shutdown para PHP-FPM; use um flush em temporizador periódico para workers de longa duração, ou as entradas ficarão em buffer até o worker encerrar.

Desempenho

record é um append de buffer O(1). O custo do flush é proporcional ao tamanho do lote e ao número de backends; ele é retirado do caminho da requisição pelo buffering e pelo manipulador de shutdown. As tentativas se aplicam por backend, limitadas pela contagem de tentativas configurada.

Notas de segurança

As entradas de medição carregam identificadores de tenant e de licença e metadados de operação. Trate os metadados como potencialmente sensíveis e ajuste o armazenamento e a retenção do seu backend aos seus requisitos de conformidade. Os identificadores de tenant e de licença devem originar-se de um contexto autenticado.

Conformidade

A medição não define nenhum formato de transmissão (wire format) próprio no limite público — a interface de backend delega a serialização a cada implementação de backend (por exemplo, um destino de push do Prometheus segue as convenções de exposição do Prometheus). Nenhum padrão externo é afirmado nesta superfície; não há citação de RAG para esta página porque nenhuma especificação normativa rege o contrato do coletor em processo.

Contrato de comportamento

• O coletor registra uma entrada imutável por operação e acumula as entradas em um buffer em memória que faz auto-flush no seu tamanho configurado; o flush explícito e um manipulador de flush no shutdown também estão disponíveis.
• O flush é idempotente: descarregar um buffer vazio é um no-op e o flush duplo é seguro.
• O reporter distribui um lote para um ou mais backends com isolamento por backend; a falha de um backend não impede os demais.
• Cada entrega de backend é repetida até a contagem de tentativas configurada; tentativas esgotadas são registradas em log e descartadas — a medição é de melhor esforço e nunca lança exceção no caminho de processamento.
• Construir um reporter com uma lista de backends vazia é rejeitado; os backends são obrigados a ser idempotentes, de modo que um lote duplicado não conte em dobro.
• record é um append de buffer O(1); o custo do flush é proporcional ao tamanho do lote e à contagem de backends e é mantido fora do caminho da requisição.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.

Fallback no Core

O NextPDF Core (Apache-2.0) não tem coletor, reporter ou superfície de backend de medição — nenhum; essa capacidade não tem equivalente no nível Core. O processamento do Core não é medido pelo NextPDF.

Fallback no Pro

O NextPDF Pro não tem superfície de medição — nenhuma; essa capacidade não tem equivalente no nível Pro. O coletor de medição, o reporter e a interface de backend são entregues apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

O ciclo de vida do buffer, o fan-out, as tentativas e o isolamento são descritos no nível de comportamento. A interface de backend delega a serialização a cada implementação de backend; os detalhes internos de buffering e qualquer detalhe interno de fan-out estão fora do escopo da superfície pública.

Limite de implantação

O operador é dono das implementações de backend, da sua durabilidade e idempotência, do escopo de retenção e armazenamento dos metadados de medição, e da estratégia de flush do modelo de worker (manipulador de shutdown para PHP-FPM, temporizador periódico para workers de longa duração). Uma indisponibilidade de backend de medição nunca degrada o processamento de documentos. Os identificadores de tenant e de licença devem originar-se de um contexto autenticado que o operador configura.

Limite legal e de conformidade

Nenhuma restrição de controle de exportação se aplica à superfície de medição. Os metadados de medição podem ser sensíveis; o escopo de retenção e armazenamento é responsabilidade de conformidade do operador. Esta documentação não é uma opinião jurídica; consulte seus próprios assessores de conformidade e jurídicos.

Veja também

• Referência de medição — NextPDF Enterprise
• Billing — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Licensing — NextPDF Enterprise