الانتقال إلى المحتوى الرئيسي
الخلاصةاجمع سجلات خادم PostgreSQL واعرضها بصريًا في ClickStack باستخدام مستقبِل OTel ‏filelog‏ (بتنسيق CSV). يتضمن ذلك مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.

التكامل مع PostgreSQL الحالي

يتناول هذا القسم كيفية تهيئة تثبيت PostgreSQL الحالي لديك لإرسال السجلات إلى ClickStack من خلال تعديل إعدادات ClickStack OTel collector. إذا كنت ترغب في اختبار تكامل سجلات PostgreSQL قبل تهيئة إعدادك الحالي، فيمكنك تجربة الإعداد المُعَدّ مسبقًا وبياناتنا النموذجية في قسم “مجموعة البيانات التجريبية”.
المتطلبات الأساسية
  • مثيل ClickStack قيد التشغيل
  • تثبيت PostgreSQL حالي (الإصدار 9.6 أو أحدث)
  • إمكانية تعديل ملفات تكوين PostgreSQL
  • مساحة قرص كافية لملفات السجل
1

تهيئة تسجيل PostgreSQL

يدعم PostgreSQL عدة تنسيقات للسجلات. ولإجراء parsing منظَّم باستخدام OpenTelemetry، نوصي باستخدام تنسيق CSV لأنه يوفّر مخرجات متسقة وقابلة للمعالجة.يوجد ملف postgresql.conf عادةً في:
  • Linux (apt/yum): /etc/postgresql/{version}/main/postgresql.conf
  • macOS (Homebrew): /usr/local/var/postgres/postgresql.conf أو /opt/homebrew/var/postgres/postgresql.conf
  • Docker: عادةً ما يُضبط الإعداد عبر متغيرات البيئة أو من خلال ملف config مُركّب
أضف هذه الإعدادات إلى postgresql.conf أو عدّلها فيه:
يستخدم هذا الدليل تنسيق csvlog في PostgreSQL لإجراء تحليل منظَّم وموثوق. إذا كنت تستخدم التنسيقين stderr أو jsonlog، فستحتاج إلى تعديل إعدادات OpenTelemetry Collector وفقًا لذلك.
بعد إجراء هذه التغييرات، أعد تشغيل PostgreSQL:
تحقّق من أن السجلات تُكتب:
2

إنشاء تهيئة مخصصة لـ OTel collector

يتيح لك ClickStack توسيع التهيئة الأساسية لـ OpenTelemetry Collector من خلال تحميل ملف تهيئة مخصص وتعيين متغير بيئة. وتُدمج التهيئة المخصصة مع التهيئة الأساسية التي يديرها HyperDX عبر OpAMP.أنشئ ملفًا باسم postgres-logs-monitoring.yaml يتضمن التهيئة التالية:
هذا الإعداد:
  • يقرأ سجلات PostgreSQL بتنسيق CSV من موقعها القياسي
  • يتعامل مع مُدخلات السجل متعددة الأسطر (فغالبًا ما تمتد الأخطاء عبر عدة أسطر)
  • يحلّل تنسيق CSV مع جميع حقول سجل PostgreSQL القياسية
  • يستخرج الطوابع الزمنية للحفاظ على التوقيت الأصلي للسجل
  • يضيف السمة source: postgresql للتصفية في HyperDX
  • يوجّه السجلات إلى مُصدِّر ClickHouse عبر مسار معالجة مخصّص
  • لا تُعرِّف في الإعداد المخصّص سوى receivers وpipelines الجديدة
  • إن processors (memory_limiter, transform, batch) وexporters (clickhouse) معرّفة مسبقًا في إعداد ClickStack الأساسي — ما عليك إلا الإشارة إليها بالاسم
  • يستخرج العامل csv_parser جميع حقول سجل PostgreSQL القياسية بتنسيق CSV إلى سمات منظَّمة
  • يستخدم هذا الإعداد start_at: end لتجنّب إدخال السجلات مجددًا عند إعادة تشغيل المجمّع. ولأغراض الاختبار، غيّره إلى start_at: beginning لعرض السجلات التاريخية فورًا.
  • عدّل المسار include ليتوافق مع موقع دليل سجلات PostgreSQL لديك
3

هيّئ ClickStack لتحميل إعدادات مخصّصة

لتمكين إعدادات مخصّصة للمجمّع في عملية نشر ClickStack الحالية، يجب عليك:
  1. ربط ملف الإعدادات المخصّص عند /etc/otelcol-contrib/custom.config.yaml
  2. تعيين متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. ربط دليل سجلات PostgreSQL لكي يتمكن المجمّع من قراءتها
الخيار 1: Docker Compose
حدّث إعدادات نشر ClickStack:
الخيار 2: Docker Run (الصورة المتكاملة)
إذا كنت تستخدم الصورة المتكاملة مع docker run:
تأكد من أن جامع ClickStack يملك الأذونات المناسبة لقراءة ملفات سجلات PostgreSQL. في بيئة الإنتاج، استخدم نقاط تحميل للقراءة فقط (:ro) والتزم بمبدأ أقل الصلاحيات اللازمة.
4

التحقق من السجلات في HyperDX

بعد إتمام الإعداد، سجّل الدخول إلى HyperDX وتأكد من أن السجلات تتدفق:
  1. انتقل إلى عرض البحث
  2. اضبط المصدر على السجلات
  3. صفِّ باستخدام source:postgresql لعرض السجلات الخاصة بـ PostgreSQL
  4. ينبغي أن ترى سجلات منظَّمة تتضمن حقولًا مثل user_name وdatabase_name وerror_severity وmessage وquery وغيرها.

مجموعة بيانات تجريبية

للمستخدمين الذين يريدون اختبار تكامل سجلات PostgreSQL قبل تهيئة أنظمتهم في بيئة الإنتاج، نوفر مجموعة بيانات نموذجية لسجلات PostgreSQL مُولَّدة مسبقًا بأنماط واقعية.
1

تنزيل مجموعة البيانات النموذجية

نزّل ملف السجل النموذجي:
2

إنشاء إعداد collector للاختبار

أنشئ ملفًا باسم postgres-logs-demo.yaml بالإعداد التالي:
3

تشغيل ClickStack باستخدام الإعداد التجريبي

شغّل ClickStack باستخدام السجلات والإعداد التجريبيين:
4

التحقق من السجلات في HyperDX

بعد تشغيل ClickStack:
  1. افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
  2. انتقل إلى عرض Search واضبط source على Logs
  3. اضبط النطاق الزمني على 2025-11-09 00:00:00 - 2025-11-12 00:00:00
عرض المنطقة الزمنيةيعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية في متصفحك. تغطي البيانات التجريبية الفترة 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). يضمن اتساع النطاق الزمني ظهور السجلات التجريبية لك بغض النظر عن موقعك. وبعد ظهور السجلات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.

لوحات المعلومات والتصورات المرئية

لمساعدتك على بدء مراقبة PostgreSQL باستخدام ClickStack، نوفر تصورات أساسية لسجلات PostgreSQL.
1

إعدادات لوحة المعلومات

2

استيراد لوحة المعلومات الجاهزة مسبقًا

  1. افتح HyperDX وانتقل إلى قسم Dashboards
  2. انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث
  1. ارفع ملف postgresql-logs-dashboard.json وانقر على Finish Import
3

عرض لوحة المعلومات

سيتم إنشاء لوحة المعلومات مع ضبط جميع التصورات مسبقًا:
بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (عدّله وفقًا لمنطقتك الزمنية المحلية). لن تتضمن لوحة المعلومات المستوردة نطاقًا زمنيًا محددًا افتراضيًا.

استكشاف الأخطاء وإصلاحها

تعذّر تحميل الإعدادات المخصّصة

تحقّق من ضبط متغير البيئة:
تحقق من أن ملف الإعدادات المخصّص مُركَّب ويمكن قراءته:

عدم ظهور سجلات في HyperDX

تحقق من أن التهيئة الفعّالة تتضمن مستقبِل filelog الخاص بك:
تحقّق من وجود أخطاء في سجلات collector:
إذا كنت تستخدم مجموعة البيانات التجريبية، فتحقق من إمكانية الوصول إلى ملف السجل:

الخطوات التالية

  • أعدّ التنبيهات للأحداث الحرجة (فشل الاتصال، والاستعلامات البطيئة، والارتفاعات المفاجئة في الأخطاء)
  • اربط السجلات بـمقاييس PostgreSQL للحصول على مراقبة شاملة لقاعدة البيانات
  • أنشئ لوحات معلومات مخصصة لأنماط الاستعلامات الخاصة بتطبيقك
  • اضبط log_min_duration_statement لتحديد الاستعلامات البطيئة بما يتوافق مع متطلبات الأداء لديك

الانتقال إلى بيئة الإنتاج

يعتمد هذا الدليل على OpenTelemetry Collector المضمّن في ClickStack لتسهيل الإعداد السريع. أما لعمليات النشر في بيئة الإنتاج، فنوصي بتشغيل OTel Collector الخاص بك وإرسال البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack. راجع إرسال بيانات OpenTelemetry للاطلاع على إعدادات بيئة الإنتاج.
آخر تعديل في ٢٥ يونيو ٢٠٢٦