Учёт потребления

Краткий обзор

NextPDF Enterprise собирает учёт потребления — операции, обработанные страницы, длительности — на уровне оркестрации PHP для биллинга и аудита. Записи буферизуются в памяти, сбрасываются в один или несколько бэкендов пакетами, а сбой бэкенда никогда не блокирует обработку. На этой странице описано наблюдаемое поведение учёта и публичный контракт.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется с лицензионным конвертом уровня Enterprise. Развёртывание без такого права не загружает классы этой возможности. Учёт — базовая возможность Enterprise без отдельного флага для каждой функции. Сравните редакции и получите лицензию.

Концептуальный обзор

Сборщик учёта записывает по одной неизменяемой записи на операцию: тип операции, число единиц, метку времени, идентификаторы арендатора и лицензии, число обработанных страниц, длительность операции и произвольные метаданные. Записи накапливаются во внутрипамятном буфере. Когда буфер достигает настроенного размера, он сбрасывается автоматически; вы также можете сбросить его явно, а обработчик завершения можно зарегистрировать так, чтобы воркер PHP-FPM сбрасывал остаток в конце запроса. Долгоживущему воркеру (например, воркеру Octane или Symfony) следует вместо этого сбрасывать по периодическому таймеру.

Репортер раздаёт пакет в один или несколько бэкендов. Бэкенды изолированы: сбой в одном бэкенде не мешает остальным получить пакет. Доставка в каждый бэкенд повторяется до настроенного числа попыток; если все попытки терпят неудачу, пакет для этого бэкенда логируется и отбрасывается — учёт по замыслу выполняется по принципу best-effort и некритичен, поэтому сбой учёта никогда не ухудшает обработку документов. Бэкенд — это любая реализация интерфейса бэкенда учёта: push-цель Prometheus, биллинговый API, база данных или очередь, — а реализации обязаны быть идемпотентными, чтобы дублированный пакет обрабатывался корректно.

Этот учёт на уровне оркестрации предназначен для биллинга и видимости в аудите. Он намеренно не является авторитетным источником для принудительного контроля квот; решения по квотам принимаются в другом месте развёртывания на основе авторитетного показателя потребления.

Почему это устроено именно так

Учёт находится на пути биллинга и аудита, а не на пути обработки документов, и это разделение сделано намеренно. Каждый вызов record добавляет одну неизменяемую MeterEntry во внутрипамятный буфер, поэтому фиксация потребления остаётся операцией за O(1). Сброс происходит пакетами, раздаваемыми в изолированные бэкенды за контрактом MeteringBackendInterface. Медленная или мёртвая биллинговая конечная точка тогда деградирует плавно, а исчерпанный пакет логируется и отбрасывается, а не выбрасывается. Поэтому сбой учёта никогда не тормозит работу с большими объёмами и не конкурирует с пропускной способностью обработки документов. Компромисс в том, что учёт на уровне оркестрации выполняется по принципу best-effort и не является авторитетным — поэтому принудительный контроль квот решается в другом месте на основе авторитетного показателя.

Проектный контекст: Генерация документов в больших объёмах.

Публичная поверхность API

composer require nextpdf/enterprise:^3

Поддерживаемые точки интеграции — это сборщик показателей (record, flush, bufferCount, registerShutdownFlush), репортер учёта (report), интерфейс бэкенда учёта (report, isHealthy, backendName) и неизменяемый объект-значение записи учёта. Предоставить безопасную к отсутствию повторов, идемпотентную реализацию бэкенда для надёжности в продакшене — ваша обязанность.

Пример кода — быстрый старт

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

Пример кода — рабочая среда

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

Граничные случаи и подводные камни

• Сброс идемпотентен. Вызов flush на пустом буфере — это no-op; двойной сброс безопасен.
• Сбой бэкенда некритичен. Исчерпанные повторы логируют ошибку и отбрасывают пакет этого бэкенда; вызов всё равно возвращается нормально. Не полагайтесь на учёт для жёсткого принудительного контроля квот.
• Требуется хотя бы один бэкенд. Создание репортера с пустым списком бэкендов отклоняется.
• Идемпотентность — задача бэкенда. Контракт интерфейса требует, чтобы бэкенды устраняли дубликаты (по метке времени, операции и арендатору) — повторённый или дублированный пакет не должен учитываться дважды.
• Модель воркера имеет значение. Используйте обработчик завершения для PHP-FPM; используйте сброс по периодическому таймеру для долгоживущих воркеров, иначе записи буферизуются, пока воркер не завершится.

Производительность

record — это добавление в буфер за O(1). Стоимость сброса пропорциональна размеру пакета и числу бэкендов; она убрана с пути запроса за счёт буферизации и обработчика завершения. Повторы применяются для каждого бэкенда и ограничены настроенным числом попыток.

Замечания по безопасности

Записи учёта несут идентификаторы арендатора и лицензии и метаданные операции. Относитесь к метаданным как к потенциально конфиденциальным и ограничивайте хранение и удержание в бэкенде вашими требованиями соответствия. Идентификаторы арендатора и лицензии должны исходить из аутентифицированного контекста.

Соответствие

Учёт не определяет собственного формата передачи на публичной границе — интерфейс бэкенда делегирует сериализацию каждой реализации бэкенда (например, push-цель Prometheus следует соглашениям экспозиции Prometheus). На этой поверхности не утверждается ни одного внешнего стандарта; для этой страницы нет цитаты RAG, потому что контракт внутрипроцессного сборщика не регулируется никакой нормативной спецификацией.

Контракт поведения

• Сборщик записывает по одной неизменяемой записи на операцию и накапливает записи во внутрипамятном буфере, который сбрасывается автоматически при настроенном размере; доступны также явный сброс и обработчик сброса при завершении.
• Сброс идемпотентен: сброс пустого буфера — это no-op, а двойной сброс безопасен.
• Репортер раздаёт пакет в один или несколько бэкендов с изоляцией по каждому бэкенду; сбой одного бэкенда не останавливает остальные.
• Доставка в каждый бэкенд повторяется до настроенного числа попыток; исчерпанные повторы логируются и отбрасываются — учёт выполняется по принципу best-effort и никогда не выбрасывает исключение на путь обработки.
• Создание репортера с пустым списком бэкендов отклоняется; бэкенды обязаны быть идемпотентными, чтобы дублированный пакет не учитывался дважды.
• record — это добавление в буфер за O(1); стоимость сброса пропорциональна размеру пакета и числу бэкендов и держится вне пути запроса.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы заявок находятся вне области рассмотрения.

Резервный режим Core

У NextPDF Core (Apache-2.0) нет сборщика, репортера или поверхности бэкенда учёта — никаких; у этой возможности нет эквивалента уровня Core. Обработка в Core не учитывается NextPDF.

Резервный режим Pro

У NextPDF Pro нет поверхности учёта — никакой; у этой возможности нет эквивалента уровня Pro. Сборщик показателей, репортер и интерфейс бэкенда поставляются только в пакете nextpdf/enterprise.

Замечание о границе Enterprise

Жизненный цикл буфера, раздача, повторы и изоляция описаны на уровне поведения. Интерфейс бэкенда делегирует сериализацию каждой реализации бэкенда; внутренние детали буферизации и любые внутренние детали раздачи находятся вне публичной поверхности.

Граница развёртывания

Оператор владеет реализациями бэкендов, их надёжностью и идемпотентностью, областью удержания и хранения метаданных учёта и стратегией сброса в модели воркера (обработчик завершения для PHP-FPM, периодический таймер для долгоживущих воркеров). Сбой бэкенда учёта никогда не ухудшает обработку документов. Идентификаторы арендатора и лицензии должны исходить из аутентифицированного контекста, настраиваемого оператором.

Граница правового соответствия

К поверхности учёта не применяется никакого ограничения экспортного контроля. Метаданные учёта могут быть конфиденциальными; область удержания и хранения — это обязанность оператора по соответствию. Эта документация не является юридическим заключением; обращайтесь к собственным консультантам по комплаенсу и праву.

См. также

• Справочник по учёту — NextPDF Enterprise
• Биллинг — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Лицензирование — NextPDF Enterprise