Enterprise phiên bản

Metering — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Namespace NextPDF\Enterprise\Metering cung cấp việc đo lường sử dụng ở mức điều phối phục vụ khả năng quan sát tính phí và kiểm toán. Bề mặt công khai gồm sáu ký hiệu: MeterCollector, MeterEntry, MeteringReporter, MeteringBackendInterface, PrometheusMeteringBackend, và PrometheusPushgatewayException. Collector đệm các entry bất biến trong bộ nhớ và flush chúng theo từng batch. Reporter phân phối mỗi batch tới một hoặc nhiều backend với thử lại theo từng backend và cô lập lỗi. Metering là best-effort và không gây tử vong: một sự cố backend metering làm suy giảm khả năng quan sát, không bao giờ làm suy giảm việc xử lý tài liệu. Luồng này không phải là nguồn có thẩm quyền cho việc thực thi quota. Để xem hướng dẫn ở mức quy trình, hãy xem Metering.

Khả dụng và cấp phép

Khả năng này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của khả năng này. So sánh các phiên bản và lấy giấy phép.

Metering là một khả năng nền tảng của Enterprise, khả dụng một khi gói Enterprise được cài đặt; không có cờ riêng theo từng tính năng. NextPDF Core (Apache-2.0) và NextPDF Pro không có bề mặt collector, reporter, hay backend nào; hợp đồng chỉ đi kèm trong nextpdf/enterprise.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`MeterCollector::__construct`	`MeteringReporter $reporter`, `int $bufferSize = 100`	Tạo một collector với buffer rỗng trong bộ nhớ	`MeterCollector` mới	Không ném	`$bufferSize` được tài liệu hóa là `positive-int`
`MeterCollector::record`	`string $operation`, `int $count`, `string $tenantId`, `string $licenseId`, `int $pagesProcessed = 0`, `float $durationMs = 0.0`, `array $metadata = []`	Nối thêm một `MeterEntry` bất biến được đóng dấu thời gian hiện tại; tự động flush khi buffer đạt `$bufferSize`	`void`	Không ném; một auto-flush ủy thác cho reporter, vốn không bao giờ ném	Timestamp được lấy tại thời điểm ghi
`MeterCollector::flush`	—	Trao tất cả các entry đã đệm cho reporter; buffer rỗng là một no-op	`void`	Không ném; các lỗi backend được reporter hấp thụ	Buffer được hoán đổi ra trước khi trao đi; an toàn khi tái nhập
`MeterCollector::bufferCount`	—	Trả về số lượng entry đã đệm	`int<0, max>`	Không ném	Chẩn đoán và quyết định back-pressure
`MeterCollector::registerShutdownFlush`	—	Đăng ký `flush()` qua `register_shutdown_function`	`void`	Không ném	Gọi một lần tại bootstrap trong các triển khai PHP-FPM
`MeterEntry::__construct`	`string $operation`, `int $count`, `DateTimeImmutable $timestamp`, `string $tenantId`, `string $licenseId`, `int $pagesProcessed = 0`, `float $durationMs = 0.0`, `array $metadata = []`	Lưu các giá trị được cung cấp nguyên văn	`MeterEntry` mới	Không khai báo `@throws`; PHP phát sinh `TypeError` khi kiểu đối số không khớp dưới `strict_types`	`final readonly`; cả tám thuộc tính được promote đều public
`MeteringReporter::__construct`	`list<MeteringBackendInterface> $backends`, `int $maxRetries = 2`, `LoggerInterface $logger = new NullLogger()`	Kiểm tra và lưu danh sách backend	`MeteringReporter` mới	`InvalidArgumentException` khi `$backends` rỗng	`$maxRetries` đếm tổng số lần thử giao theo từng backend
`MeteringReporter::report`	`list<MeterEntry> $entries`	Giao batch tới mọi backend một cách độc lập, với thử lại theo từng backend	`void`	Không ném; khi cạn số lần thử thì ghi log ở mức error và bỏ batch của backend đó	Danh sách rỗng là một no-op
`MeteringBackendInterface::report`	`list<MeterEntry> $entries`	Giao một batch tới backend	`void`	`RuntimeException` khi không thể tiếp cận backend	Các hiện thực PHẢI là idempotent (khử trùng lặp theo timestamp + operation + tenantId)
`MeteringBackendInterface::isHealthy`	—	Thăm dò khả năng tiếp cận	`bool`	Không khai báo `@throws`	Chỉ để chẩn đoán; reporter không dựa vào nó
`MeteringBackendInterface::backendName`	—	Tên backend để chẩn đoán	`non-empty-string`	Không khai báo `@throws`	Ví dụ `"prometheus"`, `"billing-api"`, `"null"`
`PrometheusMeteringBackend::__construct`	`ClientInterface $httpClient`, `RequestFactoryInterface $requestFactory`, `StreamFactoryInterface $streamFactory`, `string $pushgatewayUrl`, `string $jobName = 'nextpdf_metering'`	Cấu hình một push target Pushgateway	`PrometheusMeteringBackend` mới	Không ném	Client PSR-18 và các factory PSR-17 được inject
`PrometheusMeteringBackend::report`	`list<MeterEntry> $entries`	Tổng hợp batch theo chuỗi operation-và-tenant và POST văn bản exposition tới `<pushgatewayUrl>/metrics/job/<jobName>`	`void`	`PrometheusPushgatewayException` khi trạng thái không phải 2xx hoặc khi lỗi vận chuyển PSR-18	Danh sách rỗng là một no-op
`PrometheusMeteringBackend::isHealthy`	—	Thăm dò health endpoint của Pushgateway; `true` chỉ khi HTTP 200	`bool`	Không ném; bất kỳ thất bại nào cũng trả về `false`	Thăm dò GET chỉ đọc
`PrometheusMeteringBackend::backendName`	—	Trả về `"prometheus"`	`non-empty-string`	Không ném	Hằng số
`PrometheusPushgatewayException`	—	Báo hiệu một lần giao Pushgateway thất bại	—	Là throwable	`final`; kế thừa `RuntimeException`

public function __construct(
    private readonly MeteringReporter $reporter,
    private readonly int $bufferSize = 100,
) {}

public function record(
    string $operation,
    int $count,
    string $tenantId,
    string $licenseId,
    int $pagesProcessed = 0,
    float $durationMs = 0.0,
    array $metadata = [],
): void

public function flush(): void

public function bufferCount(): int

public function registerShutdownFlush(): void

public function __construct(
    public string $operation,
    public int $count,
    public DateTimeImmutable $timestamp,
    public string $tenantId,
    public string $licenseId,
    public int $pagesProcessed = 0,
    public float $durationMs = 0.0,
    public array $metadata = [],
) {}

public function report(array $entries): void;

public function isHealthy(): bool;

public function backendName(): string;

public function __construct(
    array $backends,
    private readonly int $maxRetries = 2,
    private readonly LoggerInterface $logger = new NullLogger(),
)

public function report(array $entries): void

public function __construct(
    private readonly ClientInterface $httpClient,
    private readonly RequestFactoryInterface $requestFactory,
    private readonly StreamFactoryInterface $streamFactory,
    private readonly string $pushgatewayUrl,
    private readonly string $jobName = self::DEFAULT_JOB_NAME,
) {}

final class PrometheusPushgatewayException extends RuntimeException {}

Các thuộc tính public readonly của MeterEntry

Thuộc tính	Kiểu	Ý nghĩa
`$operation`	`non-empty-string`	Loại thao tác, ví dụ `"parse"`, `"compress"`, `"embed"`, `"rag_query"`
`$count`	`positive-int`	Số đơn vị đã tiêu thụ
`$timestamp`	`DateTimeImmutable`	Thời điểm thao tác diễn ra; collector đóng dấu tại thời điểm ghi
`$tenantId`	`non-empty-string`	Định danh tenant
`$licenseId`	`non-empty-string`	Định danh giấy phép
`$pagesProcessed`	`int<0, max>`	Số trang PDF đã xử lý; `0` cho các thao tác không phải PDF
`$durationMs`	`float`	Thời lượng thao tác tính bằng mili-giây
`$metadata`	`array<string, mixed>`	Metadata tự do định dạng đặc thù cho thao tác

Hợp đồng hành vi

MeterCollector::record() khởi tạo một MeterEntry bất biến, đóng dấu thời gian hiện tại, và nối thêm vào buffer trong bộ nhớ. Khi buffer đạt $bufferSize entry, collector tự động flush.
flush() là idempotent và an toàn khi tái nhập. Một buffer rỗng là một no-op. Buffer được hoán đổi ra trước khi batch được trao cho reporter, nên một flush tái nhập không thể gửi đôi.
MeteringReporter từ chối khởi tạo với một danh sách backend rỗng. InvalidArgumentException đó là exception duy nhất trên đường collector/reporter.
MeteringReporter::report() giao mỗi batch tới mọi backend một cách độc lập. Một backend thất bại không bao giờ ngăn một backend khác nhận cùng batch đó.
$maxRetries đếm tổng số lần thử giao theo từng backend; mặc định 2 nghĩa là một lần thử ban đầu cộng một lần thử lại. Mỗi lần thử thất bại ghi một warning kèm tên backend, số thứ tự lần thử, và số lượng entry.
Khi lần thử cuối cùng cho một backend thất bại, reporter ghi log thêm ở mức error kèm số entry bị bỏ, rồi chuyển tiếp. Nó không bao giờ ném từ report(), nên bên gọi không được suy ra việc giao thành công từ một lần trả về bình thường.
Các backend PHẢI là idempotent. Hợp đồng interface yêu cầu khử trùng lặp theo khóa timestamp, operation, và định danh tenant. Bản thân reporter không khử trùng lặp.
PrometheusMeteringBackend::report() tổng hợp batch thành các chuỗi theo từng operation, từng tenant và POST văn bản exposition Prometheus tới <pushgatewayUrl>/metrics/job/<jobName> với Content-Type text/plain; version=0.0.4. Tên job mặc định là nextpdf_metering.
Payload được đẩy mang ba counter — nextpdf_operations_total, nextpdf_pages_processed_total, và nextpdf_operation_duration_ms_total — mỗi cái được gắn nhãn theo operation và tenant.
Luồng metering này không có thẩm quyền. Việc thực thi quota và metering tính toán có thẩm quyền tiêu thụ con số sử dụng có thẩm quyền riêng của triển khai, không bao giờ tiêu thụ buffer này. Một khoảng trống trong metering điều phối là một khoảng trống về khả năng quan sát, không phải một khoảng trống về tính đúng đắn của việc tính phí.

Trường hợp biên và chế độ lỗi

Batch bị trùng hoặc bị phát lại. Được idempotency của backend hấp thụ; reporter không khử trùng lặp. Đừng dựa vào việc giao đúng một lần.
Cạn số lần thử lại. Batch của backend đó bị bỏ và được ghi log ở mức error. Một lần trả về bình thường từ report() hoặc flush() không bao giờ hàm ý việc giao thành công.
Tiến trình thoát trước khi flush. Buffer chỉ nằm trong bộ nhớ. Một sự cố sập, hoặc một lần thoát mà không có shutdown handler đã đăng ký, sẽ mất các entry đã đệm.
Không khớp mô hình worker. Các triển khai PHP-FPM gọi registerShutdownFlush() một lần tại bootstrap để phần còn lại flush khi kết thúc request. Các worker chạy lâu dài (Octane, Symfony worker, queue worker) phải flush trên một timer định kỳ thay vào đó; nếu không các entry sẽ tích lũy cho tới khi tiến trình worker thoát.
$bufferSize dưới 1. Vi phạm hợp đồng positive-int đã tài liệu hóa; kết quả quan sát được là một flush trên mỗi lần gọi record().
Metadata nhạy cảm. $metadata là tự do định dạng và có thể mang theo bối cảnh thao tác nhạy cảm. Việc lưu trữ, lưu giữ, và kiểm soát truy cập là trách nhiệm của người vận hành backend.
Lỗi giao Pushgateway. Một phản hồi không phải 2xx phát sinh PrometheusPushgatewayException mang theo trạng thái HTTP và thân phản hồi; một lỗi vận chuyển PSR-18 được bọc trong cùng loại exception đó. Vòng lặp thử-lại-và-cô-lập của reporter hấp thụ cả hai.
Health probe. PrometheusMeteringBackend::isHealthy() phát một GET tới <pushgatewayUrl>/-/healthy và chỉ trả về true khi HTTP 200. Bất kỳ lỗi vận chuyển nào cũng trả về false; probe không bao giờ ném.
Giá trị nhãn thù địch. Các ký tự backslash, dấu nháy kép, và line-feed trong giá trị operation hoặc tenant được escape khi phát ra, nên một giá trị nhãn không thể tiêm thêm dòng exposition hoặc làm hỏng khối nhãn.
Chế độ FIPS. Collector và reporter không thực hiện thao tác mật mã nào và không có hành vi đặc thù theo FIPS. Một backend ký hoặc mã hóa trong khi truyền sẽ kế thừa tư thế FIPS của host crypto provider của nó.

Phù hợp tiêu chuẩn

Không có tiêu chuẩn bên ngoài nào quản lý hợp đồng collector, reporter, hay backend trong tiến trình; không có đặc tả quy phạm nào để dẫn chiếu, nên trang này không mang dẫn chiếu RAG nào theo thiết kế. Backend Prometheus phát ra định dạng Prometheus text exposition và đẩy với Content-Type text/plain; version=0.0.4; định dạng đó là một quy ước hệ sinh thái chứ không phải một tiêu chuẩn ISO hay IETF, và tuyên bố này được đặt nền trên mã nguồn sản phẩm. NextPDF không đưa ra tuyên bố về phù hợp hay chứng nhận nào cho bề mặt này.

Ghi chú phát triển

Tất cả các lớp khai báo strict_types=1 và là final; MeterEntry là final readonly với các thuộc tính public được promote. Kiểu đối số không khớp phát sinh một TypeError PHP ở bên gọi.
Các lớp của module mang chú thích gói @since là 2.1.0; PrometheusPushgatewayException mang @since 3.2.0.
Logger của reporter mặc định là một NullLogger PSR-3. Hãy inject một logger thật trong môi trường production, nếu không các batch bị bỏ sẽ không để lại dấu vết.
Kiểm thử đơn vị: hiện thực một MeteringBackendInterface giả và khởi tạo trực tiếp các giá trị MeterEntry. Backend Prometheus nhận các abstraction PSR-18/PSR-17, nên một HTTP client giả lập có thể chạy toàn bộ đường push ngoại tuyến.
Các test biên được khuyến nghị: buffer đúng bằng $bufferSize, flush tái nhập, flush buffer rỗng, một backend thất bại trong khi một backend thứ hai thành công, và ghi log khi cạn số lần thử lại.
Người hiện thực backend ném RuntimeException (hoặc một lớp con) khi giao thất bại; reporter hấp thụ nó. Hãy tôn trọng yêu cầu idempotency trước khi thêm các lần thử lại khác ở phía trên.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.

Xem thêm

Metering — NextPDF Enterprise — trang khả năng: quy trình, cấu hình, và các ví dụ triển khai đã thực hiện.
Billing — tài liệu tham chiếu chuyên sâu — các bậc gói, ngữ nghĩa vượt hạn mức, và thang cảnh báo.
SaaS — Tài liệu tham chiếu chuyên sâu — bề mặt điều phối đa tenant.
Licensing — Tài liệu tham chiếu chuyên sâu — license envelope kích hoạt các khả năng Enterprise.