المراقبة
يوفّر Libre WebUI مسارين للمراقبة موجّهين إلى المشغّلين:
- سجلات تطبيق منظّمة تُكتب محليًا إلى المخرج والخطأ القياسيين؛
- ومصدّر OpenTelemetry اختياري لطلبات HTTP والمهام الدائمة والعدادات وسجلات التحذيرات والأخطاء.
لا يرسل أي من المسارين قياسًا إلى مشروع Libre WebUI. يبقى OpenTelemetry معطّلًا إلى أن يضبط المشغّل نقطة نهاية لأداة تجميع. وتنفصل صفحتا المسؤول النظام والاستخدام: فهما تقرآن التشخيص واستخدام النماذج والموفّرين من النشر نفسه، لا من أداة تجميع OpenTelemetry.
السجلات المنظّمة
تحافظ القيمة الافتراضية LOG_FORMAT=text على إخراج وحدة التحكم المعتاد والمقسّم
حسب النطاق. عيّن LOG_FORMAT=json للحصول على كائن JSON واحد في كل سطر:
LOG_LEVEL=info
LOG_FORMAT=json
يحمل كل سطر منظّم:
- طابعًا زمنيًا بصيغة ISO؛
- المستوى ونطاق المسجل؛
- رسالة؛
- معرّف ربط الطلب أو المهمة الدائمة الحالية عند وجوده؛ و
- تفاصيل منظّمة ومحدودة يقدمها المستدعي.
يتلقى كل طلب HTTP قيمة X-Request-Id. لا يقبل Libre معرّفًا واردًا إلا إذا كان
طوله 8–64 حرفًا من الحروف أو الأرقام أو . أو _ أو -؛ وإلا ينشئ UUID. يعود
المعرّف في الاستجابة ويتبع العمل غير المتزامن ضمن سياق التسجيل. تسجل سجلات الوصول
طريقة HTTP والمسار والحالة والمدة، مع إزالة سلسلة الاستعلام لأنها قد تحتوي على
محتوى المستخدم أو بيانات اعتماد قصيرة العمر.
يقبل LOG_LEVEL القيم silent أو error أو warn أو info أو debug. قد يكشف
تسجيل التصحيح تفاصيل تشغيلية أكثر؛ فلا تفعّله إلا أثناء تشخيص مشكلة، واحمِ السجلات
الناتجة مثل سائر بيانات النشر.
حدود الحجب
تمر التفاصيل المنظّمة والقياسات المصدّرة عبر أداة الحجب المحدود نفسها:
- تُحذف الحقول التي تشبه أسماؤها كلمات مرور أو أسرارًا أو رموزًا أو مفاتيح أو تفويضًا أو ملفات تعريف ارتباط أو بيانات اعتماد أو قيم bearer أو JWT؛
- تُحد السلاسل عند 512 حرفًا؛
- تُقيّد المصفوفات وعمق التداخل وعدد السمات المصدّرة؛ و
- تحتفظ كائنات الخطأ باسمها ورسالة محدودة، لا برسم كائنات اعتباطي.
هذا دفاع متعدد الطبقات، وليس إذنًا لتسجيل المطالبات أو الأسرار. قد تظل سلسلة قصيرة يوفرها المستخدم ولا يحمل حقلها اسمًا يوحي بسر نصًا عاديًا في السجل. ينبغي لامتدادات التطبيق تسجيل المعرّفات والنتائج بدل أجسام الطلبات أو المطالبات أو نص المستندات أو نتائج الأدوات أو حمولات الموفّرين. قيّد الوصول إلى السجلات وطبّق سياسة احتفاظ يديرها المشغّل.
تفعيل OpenTelemetry
يصدّر Libre بيانات OTLP/HTTP JSON مباشرة، من دون إضافة اعتماد على OpenTelemetry SDK. وجّهه إلى عنوان HTTP الأساسي لأداة تجميع تقبل مسارات الإشارات القياسية:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
يضيف المصدّر /v1/traces و/v1/metrics و/v1/logs إلى العنوان الأساسي.
OTEL_EXPORTER_OTLP_HEADERS قائمة من أزواج key=value تفصل بينها فواصل. خزّن
بيانات اعتماد أداة التجميع كأسرار للنشر، ولا تودعها في المستودع. القيمة الافتراضية
لـOTEL_SERVICE_NAME هي libre-webui.
عند غياب متغير نقطة النهاية، لا تسجل spans والمقاييس والسجلات شيئًا، ولا يغادر شيء العملية. في نشر الفريق، تصدّر عمليات التطبيق والعمال الخارجيين بصورة مستقلة؛ لذا امنح كل عملية إعداد أداة التجميع الذي ينبغي أن تستخدمه. وقد يجعل اسم خدمة مستقل لكل دور لوحات المعلومات أوضح.
الإشارات المصدّرة
| الإشارة | ما يسجله Libre |
|---|---|
| spans خادم HTTP | الطريقة والمسار من دون سلسلة الاستعلام، وحالة الاستجابة، والمدة، وحالة النجاح أو الفشل، ومعرّف الطلب |
| عدادات HTTP | عدد طلبات متزايد رتيبًا بحسب الطريقة وفئة حالة الاستجابة |
| spans المهام الدائمة | نوع المهمة ورقم المحاولة والمدة وحالة النجاح أو الفشل |
| عدادات المهام الدائمة | عدد عمليات تنفيذ متزايد رتيبًا بحسب نوع المهمة والنتيجة |
| سجلات الأحداث | رسائل تحذير وخطأ محجوبة مع نطاق المسجل ومعرّفات ربط الطلب أو المهمة |
تكون spans منتهية ومحلية. لا ينشر Libre حاليًا أصل تتبع OpenTelemetry واردًا، ولا ينشئ أشجار spans أب/ابن بين الخدمات، ولا يضيف أدوات قياس إلى عرض المتصفح وكل استدعاء موفّر. وينتمي استخدام رموز النماذج والوسائط بدلًا من ذلك إلى سجلي تحليلات الاستخدام وحوكمة التكلفة المحليين.
سلوك التسليم
القياس قائم عمدًا على أفضل جهد:
- تحتفظ المخازن المؤقتة بحد أقصى 2,048 spans و2,048 سجلًا، وتحذف أقدم عنصر تحت الضغط؛
- يُحتفظ بحد أقصى 512 سلسلة عدادات؛
- يفرغ المصدّر بياناته كل خمس ثوانٍ تقريبًا؛
- لكل تصدير HTTP مهلة ثلاث ثوانٍ؛ و
- يؤدي خطأ أداة التجميع إلى إسقاط الدفعة، ولا يحجب أو يفشل طلب تطبيق أو مهمة دائمة.
لذلك لا يُعد المصدّر سجل تدقيق أو نظام محاسبة دائمًا. استخدم سجل التدقيق الأمني المخصص للإلحاق فقط للأحداث الأمنية، وسجل استخدام SQL للتكاليف، واحتفاظ أداة التجميع وتنبيهاتها للقياس.
استكشاف الأخطاء وإصلاحها
لا تصل أي قياسات. تأكد من وجود OTEL_EXPORTER_OTLP_ENDPOINT في بيئة عملية
التطبيق أو العامل المحددة، وأنه لا يشمل إلا العنوان الأساسي لأداة التجميع، وأن
الأداة تقبل OTLP/HTTP JSON على المسارات القياسية الثلاثة.
تعيد أداة التجميع خطأ عدم تصريح. تحقق من صيغة الترويسات المفصولة بفواصل، وما
إذا كانت أداة التجميع تتوقع authorization=Bearer ... أو ترويسة أخرى. أعد تشغيل
العملية بعد تغيير متغيرات البيئة.
تظل الطلبات ناجحة عند تعطل أداة التجميع. هذا متوقع. يفشل مسار التصدير بطريقة مفتوحة حفاظًا على توفر التطبيق، ولا يحتفظ بالدفعات الفاشلة لإعادة المحاولة.
حقل سجل مفقود أو مختصر. تُحذف المفاتيح التي تشبه الأسرار، وتُحد القيم الطويلة أو شديدة التداخل عمدًا. سجّل معرّفًا آمنًا أو ملخصًا بدل إضعاف حدود الحجب.