Metering

Sekilas pandang

NextPDF Enterprise mengumpulkan metering penggunaan — operasi, halaman yang diproses, durasi — pada lapisan orkestrasi PHP untuk penagihan dan audit. Entri di-buffer dalam memori, di-flush ke satu atau lebih backend secara batch, dan kegagalan backend tidak pernah memblokir pemrosesan. Halaman ini mendeskripsikan perilaku metering yang dapat diamati dan kontrak publiknya.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tingkat Enterprise. Penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Metering adalah kapabilitas dasar Enterprise tanpa bendera per-fitur tersendiri. Bandingkan edisi dan dapatkan lisensi.

Tinjauan konseptual

Collector metering merekam satu entri yang tidak dapat diubah per operasi: tipe operasi, jumlah unit, stempel waktu, pengidentifikasi tenant dan lisensi, halaman yang diproses, durasi operasi, dan metadata bebas-bentuk. Entri terakumulasi dalam buffer dalam-memori. Ketika buffer mencapai ukuran yang dikonfigurasi, ia melakukan auto-flush; Anda juga dapat melakukan flush secara eksplisit, dan handler shutdown dapat didaftarkan sehingga worker PHP-FPM mem-flush sisa apa pun di akhir permintaan. Worker yang berjalan lama (misalnya worker Octane atau Symfony) sebaiknya melakukan flush pada timer periodik.

Reporter menyebarkan satu batch ke satu atau lebih backend. Backend diisolasi: kegagalan pada satu backend tidak menghentikan backend lain menerima batch tersebut. Setiap pengiriman backend dicoba ulang hingga jumlah percobaan yang dikonfigurasi; jika semua percobaan gagal, batch untuk backend tersebut dicatat dan dibuang — metering bersifat best-effort dan tidak fatal secara desain, sehingga gangguan metering tidak pernah menurunkan kualitas pemrosesan dokumen. Backend adalah implementasi apa pun dari antarmuka backend metering — target push Prometheus, API penagihan, basis data, atau antrean — dan implementasi diwajibkan bersifat idempoten sehingga batch terduplikasi ditangani dengan baik.

Metering tingkat-orkestrasi ini ditujukan untuk visibilitas penagihan dan audit. Metering ini sengaja bukan sumber otoritatif untuk penegakan kuota; keputusan kuota dibuat di tempat lain dalam penerapan dari angka penggunaan otoritatif.

Mengapa ia bekerja seperti ini

Metering berada pada jalur penagihan-dan-audit, bukan jalur pemrosesan dokumen, dan pemisahan itu disengaja. Setiap panggilan record menambahkan satu MeterEntry yang tidak dapat diubah ke buffer dalam-memori, sehingga penangkapan penggunaan tetap menjadi operasi O(1). Flush terjadi secara batch, disebarkan ke backend yang terisolasi di balik kontrak MeteringBackendInterface. Endpoint penagihan yang lambat atau mati kemudian menurun kualitasnya secara anggun, dan batch yang percobaannya habis dicatat serta dibuang alih-alih dilemparkan. Jadi gangguan metering tidak pernah menghambat pekerjaan bervolume tinggi atau bersaing dengan throughput dokumen. Trade-off-nya adalah metering orkestrasi bersifat best-effort dan non-otoritatif — sehingga penegakan kuota diputuskan di tempat lain dari angka otoritatif.

Latar belakang desain: High-volume document generation.

Permukaan API publik

composer require nextpdf/enterprise:^3

Titik integrasi yang didukung adalah meter collector (record, flush, bufferCount, registerShutdownFlush), reporter metering (report), antarmuka backend metering (report, isHealthy, backendName), dan value object meter entry yang tidak dapat diubah. Implementasi backend yang idempoten dan aman-tanpa-percobaan-ulang adalah tanggung jawab Anda untuk disediakan demi durabilitas produksi.

Contoh kode — mulai cepat

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

Contoh kode — produksi

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

Kasus tepi & jebakan

• Flush bersifat idempoten. Memanggil flush pada buffer kosong adalah no-op; flush ganda aman.
• Kegagalan backend tidak fatal. Percobaan ulang yang habis mencatat error dan membuang batch backend tersebut; panggilan tetap kembali secara normal. Jangan mengandalkan metering untuk penegakan kuota keras.
• Setidaknya satu backend diperlukan. Membuat reporter dengan daftar backend kosong ditolak.
• Idempotensi adalah tugas backend. Kontrak antarmuka mewajibkan backend melakukan dedupe (berdasarkan stempel waktu, operasi, dan tenant) — batch yang dicoba ulang atau terduplikasi tidak boleh dihitung ganda.
• Model worker penting. Gunakan handler shutdown untuk PHP-FPM; gunakan flush timer periodik untuk worker yang berjalan lama, atau entri akan ter-buffer hingga worker keluar.

Kinerja

record adalah penambahan buffer O(1). Biaya flush sebanding dengan ukuran batch dan jumlah backend; biaya tersebut dipindahkan dari jalur permintaan melalui buffering dan handler shutdown. Percobaan ulang berlaku per backend, dibatasi oleh jumlah percobaan yang dikonfigurasi.

Catatan keamanan

Entri metering membawa pengidentifikasi tenant dan lisensi serta metadata operasi. Perlakukan metadata sebagai berpotensi sensitif dan batasi penyimpanan serta retensi backend Anda sesuai persyaratan kepatuhan Anda. Pengidentifikasi tenant dan lisensi harus berasal dari konteks yang terautentikasi.

Konformitas

Metering tidak mendefinisikan format wire-nya sendiri pada batas publik — antarmuka backend mendelegasikan serialisasi ke setiap implementasi backend (misalnya, target push Prometheus mengikuti konvensi exposition Prometheus). Tidak ada standar eksternal yang dinyatakan pada permukaan ini; tidak ada sitasi RAG untuk halaman ini karena tidak ada spesifikasi normatif yang mengatur kontrak collector in-process.

Kontrak perilaku

• Collector merekam satu entri yang tidak dapat diubah per operasi dan mengakumulasi entri dalam buffer dalam-memori yang melakukan auto-flush pada ukuran yang dikonfigurasi; flush eksplisit dan handler shutdown-flush juga tersedia.
• Flush bersifat idempoten: mem-flush buffer kosong adalah no-op dan flush ganda aman.
• Reporter menyebarkan satu batch ke satu atau lebih backend dengan isolasi per-backend; kegagalan satu backend tidak menghentikan yang lain.
• Setiap pengiriman backend dicoba ulang hingga jumlah percobaan yang dikonfigurasi; percobaan ulang yang habis dicatat dan dibuang — metering bersifat best-effort dan tidak pernah melempar ke jalur pemrosesan.
• Membuat reporter dengan daftar backend kosong ditolak; backend diwajibkan idempoten sehingga batch terduplikasi tidak dihitung ganda.
• record adalah penambahan buffer O(1); biaya flush sebanding dengan ukuran batch dan jumlah backend serta dijaga tetap di luar jalur permintaan.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati dari luar dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Fallback Core

NextPDF Core (Apache-2.0) tidak memiliki collector, reporter, atau permukaan backend metering — tidak ada sama sekali; kapabilitas ini tidak memiliki padanan tingkat-Core. Pemrosesan Core tidak di-meter oleh NextPDF.

Fallback Pro

NextPDF Pro tidak memiliki permukaan metering — tidak ada sama sekali; kapabilitas ini tidak memiliki padanan tingkat-Pro. Meter collector, reporter, dan antarmuka backend hanya tersedia dalam paket nextpdf/enterprise.

Catatan batas Enterprise

Siklus hidup buffer, fan-out, percobaan ulang, dan isolasi dideskripsikan pada tingkat perilaku. Antarmuka backend mendelegasikan serialisasi ke setiap implementasi backend; internal buffering internal dan detail fan-out internal apa pun berada di luar cakupan permukaan publik.

Batas penyebaran

Operator memiliki implementasi backend, durabilitas dan idempotensinya, cakupan retensi dan penyimpanan metadata metering, serta strategi flush model-worker (handler shutdown untuk PHP-FPM, timer periodik untuk worker yang berjalan lama). Gangguan backend metering tidak pernah menurunkan kualitas pemrosesan dokumen. Pengidentifikasi tenant dan lisensi harus berasal dari konteks terautentikasi yang dikonfigurasi operator.

Batas kepatuhan hukum

Tidak ada pembatasan kontrol ekspor yang berlaku untuk permukaan metering. Metadata metering dapat bersifat sensitif; cakupan retensi dan penyimpanan adalah tanggung jawab kepatuhan operator. Dokumentasi ini bukan opini hukum; konsultasikan dengan penasihat kepatuhan dan hukum Anda sendiri.

Lihat juga

• Rujukan metering — NextPDF Enterprise
• Billing — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Licensing — NextPDF Enterprise