مراقبة NextPDF Connect باستخدام OpenTelemetry
مراقبة NextPDF Connect باستخدام OpenTelemetry
قسم بعنوان «مراقبة NextPDF Connect باستخدام OpenTelemetry»لمحة سريعة
قسم بعنوان «لمحة سريعة»يتضمّن NextPDF أدوات OpenTelemetry مدمجة تُصدِر مقاطع التتبع (trace spans) والمقاييس طوال دورة حياة توليد ملفات PDF. عند عدم وجود أي حزمة تطوير برمجيات OpenTelemetry (SDK) على مسار الفئات (class path)، تبقى الأدوات غير نشطة: لا توجد تكلفة أداء، ولا يحدث فشل في التحميل التلقائي، ولا يوجد ما يحتاج إلى تهيئة. هذه الصفحة مستقلة عن وسيلة النقل، لذلك تنطبق الأدوات نفسها أيًا كانت طريقة توليدك لملف PDF: عبر استدعاء داخل العملية، أو استدعاء tools/call ضمن بروتوكول سياق النموذج (MCP)، أو طلب نقل الحالة التمثيلية (REST)، أو استدعاء gRPC موجَّه إلى NextPDF Connect.
تعامل مع هذه الصفحة بوصفها شرحًا، لا وصفة قابلة للتشغيل. يوفّر التطبيق المُضيف حزمة OpenTelemetry SDK ومُصدِّرًا؛ ولا يوفّرهما NextPDF. وبما أنه لا يوجد مثال مكتفٍ ذاتيًا، لا تثبّت هذه الصفحة تجزئة قابلة لإعادة الإنتاج.
التثبيت
قسم بعنوان «التثبيت»يختار التطبيق المُضيف حزمة OpenTelemetry SDK ومُصدِّرًا واحدًا ويثبّتهما. يقرأ NextPDF مزوّد تتبع مُسجَّلًا عالميًا، ولا يُضمِّن حزمة SDK خاصة به. قبل الاعتماد على عمليات التتبع، شغّل مِسبار التوافر المُضمَّن للتأكد من أن NextPDF يستطيع رؤية حزمة SDK. لا يُعيد المِسبار القيمة true إلا عندما تكون واجهة برمجة تطبيقات OpenTelemetry (API) موجودة على مسار الفئات (class path).
نظرة عامة مفاهيمية
قسم بعنوان «نظرة عامة مفاهيمية»يُصدِر NextPDF مقاطع (spans) تغطي دورة حياة بناء المستند، مع مجموعة صغيرة من العدّادات والرسوم البيانية التكرارية (histograms). تشمل المقاطع مقطع بناء جذريًا، وتحليل الخطوط، وتحليل لغة ترميز النص الفائق (HTML)، والتخطيط، وفك ترميز الصور، والتسلسل (serialization)، إضافة إلى المراحل الاختيارية للرمز الشريطي، والنماذج، والتنقل، والمرفقات. وتشمل المقاييس مدة العرض، وعدد الصفحات، والتحذيرات، وذروة الذاكرة، وحجم المُخرَج، وعدد الخطوط، وعدد الصور. يعتمد الجرد الدقيق للمقاطع والمقاييس على إصدار NextPDF المُثبَّت، لذلك تعامل مع أي عدد ثابت في النصوص الأقدم على أنه مرتبط بالإصدار. تحقّق منه مقابل البناء قيد التشغيل بدلًا من حفظ رقم.
عندما يعمل NextPDF Connect خلف إطار عمل ويب، يظهر استدعاء Connect بوصفه مقطعًا فرعيًا ضمن تتبع طلب بروتوكول نقل النص الفائق (HTTP) الوارد. عندئذٍ يمتدّ تتبع موزَّع واحد ليشمل نقطة الدخول عبر HTTP، والتطبيق، وبناء ملف PDF.
سطح واجهة برمجة التطبيقات (API)
قسم بعنوان «سطح واجهة برمجة التطبيقات (API)»لا تحدّد هذه الصفحة أداة محدّدة من أدوات Connect. بل تصف أدوات قياس شاملة (cross-cutting). للاطّلاع على سطح الأدوات، راجع /connect/tool-catalog/. وللاطّلاع على وسائل النقل، راجع /transports/mcp/ و/transports/rest/ و/transports/grpc/.
عيّنة برمجية — بداية سريعة
قسم بعنوان «عيّنة برمجية — بداية سريعة»أنشئ مزوّد تتبع وسجّله عالميًا قبل توليد أي ملف PDF، ثم ولّد كالمعتاد. تُصدِر أدوات القياس الداخلية في NextPDF المقاطع والمقاييس تلقائيًا، من دون أي شيفرة لكل استدعاء. أفرِغ المزوّد عند إيقاف العملية كي لا تُفقَد المقاطع المُخزَّنة مؤقتًا. يتولّى التطبيق المُضيف توصيل المزوّد والمُصدِّر الفعليين. يوثّق مشروع OpenTelemetry PHP هذا التوصيل، ولا تعيد هذه الصفحة ذكره حرفيًا.
عيّنة برمجية — بيئة الإنتاج
قسم بعنوان «عيّنة برمجية — بيئة الإنتاج»بالنسبة إلى مُجمِّع يُصدِّر عبر HTTP، يوفّر المُضيف عميل HTTP متوافقًا مع PSR-18. تعامل مع فشل النقل واستجابة HTTP غير الناجحة كحالتين منفصلتين. لا يُطلِق عميل PSR-18 استثناء عميل مُصنَّفًا إلا عندما يتعذّر عليه إرسال الطلب على الإطلاق (PSR-18 §4). أما استجابة 4xx/5xx، في المقابل، فتعود إلى المُستدعِي بصورة طبيعية ولا تُعدّ استثناءً (PSR-18 §4). مسار تصدير المُجمِّع ووسيلة نقل أداة Connect مستقلّان، لذا يجب ألّا يؤدي فشل تصدير المُجمِّع أبدًا إلى فشل توليد ملف PDF نفسه.
الحالات الحدّية والمزالق
قسم بعنوان «الحالات الحدّية والمزالق»- تسجيل المزوّد بعد عملية التوليد الأولى. أي مقطع يُنشأ قبل التسجيل يستخدم متتبعًا عديم الأثر (no-op) ولا يصل أبدًا إلى الواجهة الخلفية. سجّل المزوّد أثناء إقلاع التطبيق.
- عدم الإفراغ عند الإيقاف. يخزّن مُعالِج الدُّفعات المقاطع مؤقتًا، وتُفقَد هذه المقاطع إذا خرجت العملية دون إيقاف المزوّد. وصّل إيقاف المزوّد ضمن العامل (worker) أو خطّاف إنهاء النواة (kernel terminate hook).
- يحتاج التصدير عبر gRPC إلى امتداد gRPC الخاص بـ PHP. أما التصدير عبر HTTP فلا يحتاج إلى أي امتداد، لذا اختر HTTP عندما لا يكون الامتداد متوفّرًا.
- نشر سياق التتبع W3C Trace Context. عندما يحمل الطلب الوارد
traceparent/tracestate، تنشر حزمة SDK ذلك السياق تلقائيًا إلى مقاطع NextPDF، وينضمّ استدعاء Connect إلى تتبع المُستدعِي.
الأداء
قسم بعنوان «الأداء»تكلفة أدوات القياس ضئيلة مقارنةً بزمن توليد ملف PDF. ميزانية المقدّمة الأمامية (front-matter) حدّ توثيقي، لا ضمانة. عند معدّلات الطلبات العالية، استخدم أخذ العيّنات المُستنِد إلى الرأس (head-based) أو أخذ العيّنات على جانب المُجمِّع للحدّ من حجم المُصدِّر وتكلفته.
ملاحظات أمنية
قسم بعنوان «ملاحظات أمنية»القياس عن بُعد الآمن وتنقية السجلّات
قسم بعنوان «القياس عن بُعد الآمن وتنقية السجلّات»يفرض NextPDF سياسة صارمة لبيانات القياس عن بُعد لا يمكن تجاوزها. لا تُصدِّر قائمة السماح الثابتة للسمات إلا البيانات الوصفية البنيوية ومقاييس الأداء: أعداد الصفحات والخطوط والصور، وأحجام الملفات، وأسماء ملفات تعريف المُخرَجات، والأعلام المنطقية (boolean)، والمُدد، والذاكرة، ومعرّفات الإصدار والمستوى. لا يصدّر NextPDF أبدًا محتوى المستندات، أو مسارات الملفات، أو بايتات الدفق الخام، أو حمولات base64، أو البيانات الشخصية، أو بيانات الاعتماد. ويُسقِط أي سمة خارج قائمة السماح. كما يُسقِط أي قيمة تطابق نمط حمولة، حتى عندما يكون المفتاح نفسه مسموحًا به. يتيح هذا السلوك تدفّق عمليات التتبع إلى مسار مراقبة مُشترَك من دون تسريب بيانات المستندات. وهو سلوك على مستوى المكتبة، وليس ضمانة على مستوى النشر بشأن الواجهة الخلفية التي تتلقّى عمليات التتبع.
المطابقة
قسم بعنوان «المطابقة»| الادّعاء | البند | reference_id |
|---|---|---|
| فشل النقل هو الحالة الوحيدة لاستثناء عميل PSR-18 | PSR-18 §4 | |
| استجابة 4xx/5xx هي عودة طبيعية، لا استثناء | PSR-18 §4 |
بروتوكول OpenTelemetry وتنسيق سياق التتبع التابع لاتحاد الشبكة العالمية (W3C) مواصفتان خارجيتان، وتتولّى كل هيئة صيانة مواصفتها. لا تُقرِّر هذه الصفحة المطابقة لهما ولا تعيد إنتاج نصّيهما. توجد التعريفات الموثوقة في مواصفة OpenTelemetry المنشورة (https://opentelemetry.io/docs/specs/otel/) وفي توصية سياق التتبع الصادرة عن W3C (https://www.w3.org/TR/trace-context/).
السياق التجاري
قسم بعنوان «السياق التجاري»غير قابل للتطبيق — أدوات القياس قدرة أساسية، ولا تخضع لبوابة.
تفاصيل خاصة بـ Connect
قسم بعنوان «تفاصيل خاصة بـ Connect»توافر وسائل النقل (MCP / REST / gRPC)
قسم بعنوان «توافر وسائل النقل (MCP / REST / gRPC)»أدوات القياس مستقلة عن وسيلة النقل. يُنتِج استدعاء Connect عبر أي وسيلة نقل مقاطع دورة حياة البناء نفسها. وتضيف وسيلة النقل مقطعها المحيط الخاص بها عندما يُجهّز المُضيف طبقة النقل بأدوات القياس.
مستوى مخاطر التدخّل البشري (HITL)
قسم بعنوان «مستوى مخاطر التدخّل البشري (HITL)»المراقبة منفصلة عن نموذج المخاطر. لا يغيّر إصدار القياس عن بُعد مستوى مخاطر الأداة، ولا يخضع أبدًا لبوابة التأكيد ConfirmationGate.
غلاف JSON لبوابة التأكيد
قسم بعنوان «غلاف JSON لبوابة التأكيد»غير قابل للتطبيق — إصدار القياس عن بُعد ليس استدعاءً لأداة، لذلك لا يمرّ عبر البوابة.
انظر أيضًا
قسم بعنوان «انظر أيضًا»- /connect/tool-catalog/ — سطح الأدوات المُراقَب.
- /transports/mcp/ / /transports/rest/ / /transports/grpc/ — وسائل النقل التي يمكنها استقبال استدعاء Connect مُتتبَّعًا.