Enterprise الإصدار

القياس

لمحة سريعة

يجمع ⁨NextPDF Enterprise⁩ قياس الاستخدام — العمليات، والصفحات المُعالَجة، والمُدد — على طبقة تنسيق ⁨PHP⁩ لأغراض الفوترة والتدقيق. تُخزَّن المُدخَلات مؤقتًا في الذاكرة، وتُدفَع إلى خلفية واحدة أو أكثر على دفعات، ولا يحجب إخفاق خلفية المعالجة أبدًا. تصف هذه الصفحة سلوك القياس القابل للملاحظة والعقد العام.

التوفّر والترخيص

تُشحَن هذه القدرة في ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. والنشر الذي لا يملك ذلك الاستحقاق لا يُحمِّل فئات القدرة. والقياس قدرة أساسية في ⁨Enterprise⁩ بلا علم منفصل لكل ميزة. قارن الإصدارات واحصل على ترخيص.

نظرة مفاهيمية عامة

يُسجِّل مُجمِّع القياس مُدخَلًا واحدًا غير قابل للتغيير لكل عملية: نوع العملية، وعدد الوحدات، وطابعًا زمنيًا، ومُعرِّفي المستأجر والترخيص، والصفحات المُعالَجة، ومدة العملية، وبيانات وصفية حرّة الشكل. وتتراكم المُدخَلات في مخزن مؤقت في الذاكرة. وحين يبلغ المخزن المؤقت حجمه المُهيّأ يُدفَع تلقائيًا؛ ويمكنك أيضًا الدفع صراحةً، ويمكن تسجيل مُعالِج إغلاق بحيث يدفع عامل ⁨PHP-FPM⁩ أي بقية عند نهاية الطلب. أما العامل طويل التشغيل (مثل عامل ⁨Octane⁩ أو ⁨Symfony⁩) فينبغي أن يدفع على مُؤقِّت دوري بدلًا من ذلك.

يُوزِّع المُبلِّغ دفعةً على خلفية واحدة أو أكثر. والخلفيات معزولة: لا يمنع إخفاق في خلفية واحدة الخلفيات الأخرى من تلقّي الدفعة. ويُعاد تسليم كل خلفية حتى عدد محاولات مُهيّأ؛ وإذا أخفقت كل المحاولات تُسجَّل دفعة تلك الخلفية وتُسقَط — القياس أفضل-جهد وغير قاتل بحكم التصميم، فلا يؤدّي انقطاع القياس أبدًا إلى تدهور معالجة المستندات. والخلفية أي تنفيذ لواجهة خلفية القياس — هدف دفع ⁨Prometheus⁩، أو واجهة فوترة، أو قاعدة بيانات، أو طابور — ويُشترَط أن تكون التنفيذات مُتساوية الأثر (idempotent) حتى تُعالَج الدفعة المُكرَّرة بأمان.

قياس طبقة التنسيق هذا لرؤية الفوترة والتدقيق. وهو عمدًا ليس المصدر المُعتمَد لإنفاذ الحصص؛ فقرارات الحصص تُتَّخذ في مكان آخر من النشر من رقم استخدام مُعتمَد.

لماذا يعمل بهذه الطريقة

يقع القياس على مسار الفوترة والتدقيق، لا على مسار معالجة المستندات، وهذا الفصل مقصود. فكل استدعاء record يُلحِق MeterEntry واحدًا غير قابل للتغيير بمخزن مؤقت في الذاكرة، فيبقى التقاط الاستخدام عملية بزمن ⁨O(1)⁩. ويحدث الدفع على دفعات، مُوزَّعة على خلفيات معزولة خلف عقد MeteringBackendInterface. وعندئذٍ تتدهور نقطة نهاية فوترة بطيئة أو ميتة بلطف، وتُسجَّل الدفعة المُستنفَدة وتُسقَط بدلًا من إثارة استثناء. فلا يوقف انقطاع القياس أبدًا العمل عالي الحجم ولا ينافس إنتاجية المستندات. والمقايضة أن قياس التنسيق أفضل-جهد وغير مُعتمَد — فيُقرَّر إنفاذ الحصص في مكان آخر من رقم مُعتمَد.

خلفية التصميم: توليد المستندات عالي الحجم.

سطح الـ ⁨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 على مخزن مؤقت فارغ عملية لا أثر لها؛ والدفع المزدوج آمن.
إخفاق الخلفية غير قاتل. تُسجِّل المحاولات المُستنفَدة خطأً وتُسقِط دفعة تلك الخلفية؛ ويعود الاستدعاء طبيعيًا مع ذلك. لا تعتمد على القياس لإنفاذ حصص صارم.
يلزم خلفية واحدة على الأقل. يُرفَض بناء مُبلِّغ بقائمة خلفيات فارغة.
تساوي الأثر مهمة الخلفية. يتطلّب عقد الواجهة من الخلفيات إزالة التكرار (حسب الطابع الزمني والعملية والمستأجر) — فالدفعة المُعاد محاولتها أو المُكرَّرة يجب ألّا تُحتسَب مرتين.
نموذج العامل مهمّ. استخدم مُعالِج الإغلاق لـ ⁨PHP-FPM⁩؛ واستخدم دفعَ مُؤقِّت دوري للعمّال طويلي التشغيل، وإلا تراكمت المُدخَلات في المخزن المؤقت حتى يخرج العامل.

الأداء

record إلحاق بالمخزن المؤقت بزمن ⁨O(1)⁩. وتتناسب تكلفة الدفع مع حجم الدفعة وعدد الخلفيات؛ وتُنقَل عن مسار الطلب بالتخزين المؤقت وبمُعالِج الإغلاق. وتنطبق إعادة المحاولات لكل خلفية، محدودةً بعدد المحاولات المُهيّأ.

ملاحظات أمنية

تحمل مُدخَلات القياس مُعرِّفي المستأجر والترخيص وبيانات العملية الوصفية. عامِل البيانات الوصفية على أنها قد تكون حسّاسة، واقصُر تخزين خلفيتك والاحتفاظ بها على متطلبات امتثالك. ويجب أن ينشأ مُعرِّفا المستأجر والترخيص من سياق موثَّق.

المطابقة

لا يُعرِّف القياس أي صيغة نقلية خاصة به عند الحدود العامة — تُفوِّض واجهة الخلفية المُسلسَلة إلى كل تنفيذ خلفية (مثلًا، يتبع هدف دفع ⁨Prometheus⁩ اصطلاحات عرض ⁨Prometheus⁩). ولا يُؤكَّد أي معيار خارجي عند هذا السطح؛ ولا يوجد استشهاد ⁨RAG⁩ لهذه الصفحة لأنه لا توجد مواصفة معيارية تحكم عقد المُجمِّع داخل العملية.

عقد السلوك

يُسجِّل المُجمِّع مُدخَلًا واحدًا غير قابل للتغيير لكل عملية ويُراكِم المُدخَلات في مخزن مؤقت في الذاكرة يُدفَع تلقائيًا عند حجمه المُهيّأ؛ كما يتوفّر دفع صريح ومُعالِج دفع عند الإغلاق.
الدفع مُتساوي الأثر: دفع مخزن مؤقت فارغ عملية لا أثر لها والدفع المزدوج آمن.
يُوزِّع المُبلِّغ دفعةً على خلفية واحدة أو أكثر مع عزل لكل خلفية؛ ولا يمنع إخفاق خلفية واحدة الأخريات.
يُعاد تسليم كل خلفية حتى عدد المحاولات المُهيّأ؛ وتُسجَّل المحاولات المُستنفَدة وتُسقَط — القياس أفضل-جهد ولا يُثير أبدًا استثناءً في مسار المعالجة.
يُرفَض بناء مُبلِّغ بقائمة خلفيات فارغة؛ ويُشترَط أن تكون الخلفيات مُتساوية الأثر حتى لا تُحتسَب دفعة مُكرَّرة مرتين.
record إلحاق بالمخزن المؤقت بزمن ⁨O(1)⁩؛ وتتناسب تكلفة الدفع مع حجم الدفعة وعدد الخلفيات وتُبقى عن مسار الطلب.

حدود النشر

تُوثِّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح الـ ⁨API⁩ العام المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والفئات المساعِدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر فخارج النطاق.

بديل ⁨Core⁩

لا يملك ⁨NextPDF Core⁩ (⁨Apache-2.0⁩) أي مُجمِّع قياس أو مُبلِّغ أو سطح خلفية — لا شيء؛ فهذه القدرة بلا مكافئ على مستوى ⁨Core⁩. ولا يُقيس ⁨NextPDF⁩ معالجة ⁨Core⁩.

بديل ⁨Pro⁩

لا يملك ⁨NextPDF Pro⁩ أي سطح قياس — لا شيء؛ فهذه القدرة بلا مكافئ على مستوى ⁨Pro⁩. ويُشحَن مُجمِّع المقياس والمُبلِّغ وواجهة الخلفية في حزمة nextpdf/enterprise فقط.

ملاحظة حدود ⁨Enterprise⁩

تُوصَف دورة حياة المخزن المؤقت والتوزيع وإعادة المحاولة والعزل على مستوى السلوك. وتُفوِّض واجهة الخلفية المُسلسَلة إلى كل تنفيذ خلفية؛ وأجزاء التخزين المؤقت الداخلية وأي تفصيل توزيع داخلي خارج نطاق السطح العام.

حدود بيئة النشر

يملك المُشغِّل تنفيذات الخلفية، ومتانتها وتساوي أثرها، ونطاق الاحتفاظ والتخزين لبيانات القياس الوصفية، واستراتيجية الدفع لنموذج العامل (مُعالِج الإغلاق لـ ⁨PHP-FPM⁩، ومُؤقِّت دوري للعمّال طويلي التشغيل). ولا يؤدّي انقطاع خلفية القياس أبدًا إلى تدهور معالجة المستندات. ويجب أن ينشأ مُعرِّفا المستأجر والترخيص من سياق موثَّق يُهيّئه المُشغِّل.

حدود الامتثال القانوني

لا ينطبق أي قيد لمراقبة التصدير على سطح القياس. وقد تكون بيانات القياس الوصفية حسّاسة؛ ونطاق الاحتفاظ والتخزين مسؤولية امتثال المُشغِّل. وهذه الوثائق ليست رأيًا قانونيًا؛ استشر مستشاري الامتثال والشؤون القانونية لديك.