Metering — Derinlemesine başvuru

Bir bakışta

NextPDF\Enterprise\Metering ad alanı, faturalama görünürlüğü ve denetim için düzenleme düzeyinde kullanım ölçümlemesi sunar. Genel yüzey altı simgeden oluşur: MeterCollector, MeterEntry, MeteringReporter, MeteringBackendInterface, PrometheusMeteringBackend ve PrometheusPushgatewayException. Toplayıcı, değişmez girdileri bellekte arabelleğe alır ve toplu işler hâlinde boşaltır. Raportör, her toplu işi arka uç başına yeniden deneme ve arıza yalıtımıyla bir veya daha fazla arka uca yayar. Ölçümleme en iyi çabadır ve ölümcül değildir: bir ölçümleme arka ucu kesintisi gözlemlenebilirliği düşürür, asla belge işlemeyi değil. Bu akış, kota zorlaması için yetkili kaynak değildir. İş akışı düzeyindeki rehber için bkz. Metering.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkilendirme olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Ölçümleme, Enterprise paketi kurulduğunda kullanılabilen temel bir Enterprise yeteneğidir; özellik başına ayrı bir bayrak yoktur. NextPDF Core (Apache-2.0) ve NextPDF Pro hiçbir toplayıcı, raportör veya arka uç yüzeyine sahip değildir; sözleşme yalnızca nextpdf/enterprise içinde sunulur.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
MeterCollector::__construct	MeteringReporter $reporter, int $bufferSize = 100	Boş bir bellek içi arabelleğe sahip bir toplayıcı oluşturur	Yeni MeterCollector	Fırlatmaz	$bufferSize belgelenmiş bir positive-int değeridir
MeterCollector::record	string $operation, int $count, string $tenantId, string $licenseId, int $pagesProcessed = 0, float $durationMs = 0.0, array $metadata = []	Geçerli zamanla damgalanmış bir değişmez MeterEntry ekler; arabellek $bufferSize değerine ulaştığında otomatik olarak boşaltır	void	Fırlatmaz; otomatik boşaltma, asla fırlatmayan raportöre devreder	Zaman damgası, kayıt anında alınır
MeterCollector::flush	—	Arabelleğe alınan tüm girdileri raportöre teslim eder; boş arabellek bir işlemsizliktir	void	Fırlatmaz; arka uç arızaları raportör tarafından soğurulur	Arabellek, teslimden önce dışarı takas edilir; yeniden girişe güvenlidir
MeterCollector::bufferCount	—	Arabelleğe alınan girdilerin sayısını döndürür	int<0, max>	Fırlatmaz	Tanılama ve geri basınç kararları
MeterCollector::registerShutdownFlush	—	flush() işlevini register_shutdown_function aracılığıyla kaydeder	void	Fırlatmaz	PHP-FPM dağıtımlarında önyüklemede bir kez çağırın
MeterEntry::__construct	string $operation, int $count, DateTimeImmutable $timestamp, string $tenantId, string $licenseId, int $pagesProcessed = 0, float $durationMs = 0.0, array $metadata = []	Verilen değerleri olduğu gibi saklar	Yeni MeterEntry	Bildirilmiş bir @throws yoktur; PHP, strict_types altında uyumsuz argüman türlerinde TypeError yükseltir	final readonly; sekiz yükseltilmiş özelliğin tümü public’tir
MeteringReporter::__construct	list<MeteringBackendInterface> $backends, int $maxRetries = 2, LoggerInterface $logger = new NullLogger()	Arka uç listesini doğrular ve saklar	Yeni MeteringReporter	$backends boş olduğunda InvalidArgumentException	$maxRetries, arka uç başına toplam teslim denemesini sayar
MeteringReporter::report	list<MeterEntry> $entries	Toplu işi her arka uca bağımsız olarak, arka uç başına yeniden denemeyle teslim eder	void	Fırlatmaz; tükenmiş denemeler hata düzeyinde günlüğe kaydedilir ve o arka ucun toplu işini bırakır	Boş liste bir işlemsizliktir
MeteringBackendInterface::report	list<MeterEntry> $entries	Bir toplu işi arka uca teslim eder	void	Arka uca erişilemediğinde RuntimeException	Uygulamalar etkileşimsiz OLMALIDIR (zaman damgası + işlem + tenantId ile yinelenmiş kayıt giderme)
MeteringBackendInterface::isHealthy	—	Erişilebilirlik yoklaması	bool	Bildirilmiş bir @throws yoktur	Yalnızca tanılama; raportör buna göre kapılamaz
MeteringBackendInterface::backendName	—	Tanılama arka uç adı	non-empty-string	Bildirilmiş bir @throws yoktur	Örneğin "prometheus", "billing-api", "null"
PrometheusMeteringBackend::__construct	ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, string $pushgatewayUrl, string $jobName = 'nextpdf_metering'	Bir Pushgateway push hedefi yapılandırır	Yeni PrometheusMeteringBackend	Fırlatmaz	PSR-18 istemcisi ve PSR-17 fabrikaları enjekte edilir
PrometheusMeteringBackend::report	list<MeterEntry> $entries	Toplu işi işlem ve kiracı serisine göre toplar ve sunum metnini <pushgatewayUrl>/metrics/job/<jobName> adresine POST eder	void	2xx olmayan bir durumda veya bir PSR-18 aktarım arızasında PrometheusPushgatewayException	Boş liste bir işlemsizliktir
PrometheusMeteringBackend::isHealthy	—	Pushgateway sağlık uç noktasını yoklar; yalnızca HTTP 200’de true	bool	Fırlatmaz; herhangi bir arıza false döndürür	Salt okunur GET yoklaması
PrometheusMeteringBackend::backendName	—	"prometheus" döndürür	non-empty-string	Fırlatmaz	Sabit
PrometheusPushgatewayException	—	Başarısız bir Pushgateway teslimini bildirir	—	Fırlatılabilir olanın kendisidir	final; RuntimeException sınıfını genişletir

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 {}

MeterEntry public salt okunur özellikleri

Özellik	Tür	Anlam
$operation	non-empty-string	İşlem türü, örneğin "parse", "compress", "embed", "rag_query"
$count	positive-int	Tüketilen birim sayısı
$timestamp	DateTimeImmutable	İşlemin gerçekleştiği zaman; toplayıcı bunu kayıt anında damgalar
$tenantId	non-empty-string	Kiracı tanımlayıcısı
$licenseId	non-empty-string	Lisans tanımlayıcısı
$pagesProcessed	int<0, max>	İşlenen PDF sayfaları; PDF olmayan işlemler için 0
$durationMs	float	Milisaniye cinsinden işlem süresi
$metadata	array<string, mixed>	Serbest biçimli, işleme özgü meta veri

Davranış sözleşmesi

• MeterCollector::record(), bir değişmez MeterEntry oluşturur, geçerli zamanla damgalar ve bellek içi arabelleğe ekler. Arabellek $bufferSize girdiye ulaştığında toplayıcı otomatik olarak boşaltır.
• flush() etkileşimsiz ve yeniden girişe güvenlidir. Boş bir arabellek bir işlemsizliktir. Arabellek, toplu iş raportöre teslim edilmeden önce dışarı takas edilir; böylece yeniden girişli bir boşaltma çifte gönderim yapamaz.
• MeteringReporter, boş bir arka uç listesiyle yapımı reddeder. Bu InvalidArgumentException, toplayıcı/raportör yolundaki tek istisnadır.
• MeteringReporter::report(), her toplu işi her arka uca bağımsız olarak teslim eder. Başarısız olan bir arka uç, başka bir arka ucun aynı toplu işi almasını asla engellemez.
• $maxRetries, arka uç başına toplam teslim denemesini sayar; varsayılan 2, bir ilk deneme artı bir yeniden deneme anlamına gelir. Başarısız olan her deneme; arka uç adı, deneme numarası ve girdi sayısıyla bir uyarı günlüğe kaydeder.
• Bir arka uca yönelik son deneme başarısız olduğunda, raportör ek olarak bırakılan girdi sayısıyla hata düzeyinde günlüğe kaydeder ve devam eder. report() işlevinden asla fırlatmaz; bu nedenle çağıranlar, normal bir dönüşten teslimat çıkarımı yapmamalıdır.
• Arka uçlar etkileşimsiz OLMALIDIR. Arabirim sözleşmesi, zaman damgası, işlem ve kiracı tanımlayıcısı üzerinden anahtarlanan yinelenmiş kayıt gidermeyi gerektirir. Raportörün kendisi yinelenmiş kayıt gidermez.
• PrometheusMeteringBackend::report(), toplu işi işlem başına, kiracı başına serilere toplar ve Content-Type text/plain; version=0.0.4 ile Prometheus metin sunumunu <pushgatewayUrl>/metrics/job/<jobName> adresine POST eder. Varsayılan iş adı nextpdf_metering değeridir.
• İtilen yük üç sayaç taşır — nextpdf_operations_total, nextpdf_pages_processed_total ve nextpdf_operation_duration_ms_total — her biri işlem ve kiracıya göre etiketlenir.
• Bu ölçümleme akışı yetkili değildir. Kota zorlaması ve yetkili işlem ölçümlemesi, bu arabelleği değil, dağıtımın ayrı yetkili kullanım rakamını tüketir. Düzenleme ölçümlemesindeki bir boşluk, bir faturalama doğruluğu boşluğu değil, bir gözlemlenebilirlik boşluğudur.

Uç durumlar ve arıza modları

• Yinelenmiş veya yeniden oynatılmış toplu iş. Arka uç etkileşimsizliğiyle soğurulur; raportör yinelenmiş kayıt gidermez. Tam olarak bir kez teslime güvenmeyin.
• Tükenmiş yeniden denemeler. O arka uca yönelik toplu iş bırakılır ve hata düzeyinde günlüğe kaydedilir. report() veya flush() işlevinden gelen normal bir dönüş, asla teslimat anlamına gelmez.
• Boşaltmadan önce süreç çıkışı. Arabellek yalnızca bellektedir. Bir çökme veya kayıtlı bir kapatma işleyicisi olmadan bir çıkış, arabelleğe alınan girdileri kaybeder.
• Çalışan modeli uyuşmazlığı. PHP-FPM dağıtımları, kalan kısmın istek sonunda boşalması için önyüklemede bir kez registerShutdownFlush() çağırır. Uzun süre çalışan çalışanlar (Octane, Symfony çalışanı, kuyruk çalışanı) bunun yerine düzenli bir zamanlayıcı üzerinde boşaltmalıdır; aksi hâlde girdiler, çalışan süreci çıkana kadar birikir.
• $bufferSize değerinin 1 altında olması. Belgelenen positive-int sözleşmesini ihlal eder; gözlemlenebilir sonuç, her record() çağrısında bir boşaltmadır.
• Hassas meta veri. $metadata serbest biçimlidir ve hassas işlem bağlamı taşıyabilir. Depolama, saklama ve erişim denetimi, arka uç operatörünün sorumluluğundadır.
• Pushgateway teslim arızası. 2xx olmayan bir yanıt, HTTP durumunu ve yanıt gövdesini taşıyan PrometheusPushgatewayException yükseltir; bir PSR-18 aktarım arızası aynı istisna türüne sarılır. Raportörün yeniden deneme ve yalıtım döngüsü her ikisini de soğurur.
• Sağlık yoklaması. PrometheusMeteringBackend::isHealthy(), <pushgatewayUrl>/-/healthy adresine bir GET gönderir ve yalnızca HTTP 200’de true döndürür. Herhangi bir aktarım hatası false döndürür; yoklama asla fırlatmaz.
• Düşmanca etiket değerleri. İşlem veya kiracı değerlerindeki ters eğik çizgi, çift tırnak ve satır besleme karakterleri yayım sırasında kaçışlanır; böylece bir etiket değeri, ek sunum satırları enjekte edemez veya etiket bloğunu bozamaz.
• FIPS modu. Toplayıcı ve raportör hiçbir kriptografik işlem gerçekleştirmez ve FIPS’e özgü davranışa sahip değildir. Aktarımda imzalayan veya şifreleyen bir arka uç, ana makine kripto sağlayıcısının FIPS duruşunu devralır.

Uygunluk

Hiçbir harici standart, süreç içi toplayıcı, raportör veya arka uç sözleşmesini yönetmez; atıfta bulunulacak normatif bir belirtim yoktur, bu nedenle bu sayfa tasarım gereği hiçbir RAG atıfı taşımaz. Prometheus arka ucu, Prometheus metin sunum biçimini yayar ve Content-Type text/plain; version=0.0.4 ile iter; bu biçim, bir ISO veya IETF standardından ziyade bir ekosistem kuralıdır ve iddia, ürün kaynağına dayanır. NextPDF, bu yüzey için hiçbir uygunluk veya sertifikasyon iddiasında bulunmaz.

Geliştirme notları

• Tüm sınıflar strict_types=1 bildirir ve final’dir; MeterEntry, yükseltilmiş public özelliklere sahip final readonly sınıfıdır. Uyumsuz argüman türleri, çağıranda bir PHP TypeError yükseltir.
• Modül sınıfları 2.1.0 paket @since ek açıklaması taşır; PrometheusPushgatewayException, @since 3.2.0 taşır.
• Raportörün günlükçüsü varsayılan olarak bir PSR-3 NullLogger değerindedir. Üretimde gerçek bir günlükçü enjekte edin, aksi hâlde bırakılan toplu işler hiçbir iz bırakmaz.
• Birim testi: sahte bir MeteringBackendInterface uygulayın ve MeterEntry değerlerini doğrudan oluşturun. Prometheus arka ucu PSR-18/PSR-17 soyutlamalarını aldığından, bir sahte HTTP istemcisi tam push yolunu çevrimdışı olarak çalıştırır.
• Önerilen sınır testleri: tam olarak $bufferSize değerinde arabellek, yeniden girişli boşaltma, boş arabellek boşaltması, ikincisi başarılı olurken bir arka ucun başarısız olması ve yeniden deneme tükenmesi günlüklemesi.
• Arka uç uygulayıcıları, teslim arızasında RuntimeException (veya bir alt sınıf) fırlatır; raportör bunu soğurur. Yukarı akışta ek yeniden denemeler eklemeden önce etkileşimsizlik gereksinimine uyun.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Metering — NextPDF Enterprise — yetenek sayfası: iş akışı, yapılandırma ve işlenmiş dağıtım örnekleri.
• Billing — Derinlemesine başvuru — plan katmanları, aşım anlamları ve uyarı merdiveni.
• SaaS — Derinlemesine başvuru — çok kiracılı düzenleme yüzeyi.
• Licensing — Derinlemesine başvuru — Enterprise yeteneklerini etkinleştiren lisans zarfı.