التكامل مع PostgreSQL الحالي
يتناول هذا القسم كيفية تهيئة تثبيت PostgreSQL الحالي لديك لإرسال السجلات إلى ClickStack من خلال تعديل إعدادات ClickStack OTel collector.
إذا كنت ترغب في اختبار تكامل سجلات PostgreSQL قبل تهيئة إعدادك الحالي، فيمكنك تجربة الإعداد المُعَدّ مسبقًا وبياناتنا النموذجية في قسم "مجموعة البيانات التجريبية".
المتطلبات الأساسية
- مثيل ClickStack قيد التشغيل
- تثبيت PostgreSQL حالي (الإصدار 9.6 أو أحدث)
- إمكانية تعديل ملفات تكوين PostgreSQL
- مساحة قرص كافية لملفات السجل
تهيئة تسجيل 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 أو عدّلها فيه:
# Required for CSV logging
logging_collector = on
log_destination = 'csvlog'
# Recommended: Connection logging
log_connections = on
log_disconnections = on
# Optional: Tune based on your monitoring needs
#log_min_duration_statement = 1000 # Log queries taking more than 1 second
#log_statement = 'ddl' # Log DDL statements (CREATE, ALTER, DROP)
#log_checkpoints = on # Log checkpoint activity
#log_lock_waits = on # Log lock contentionبعد إجراء هذه التغييرات، أعد تشغيل PostgreSQL:
# For systemd
sudo systemctl restart postgresql
# For Docker
docker restart تحقّق من أن السجلات تُكتب:
# Default log location on Linux
tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log
# macOS Homebrew
tail -f /usr/local/var/postgres/log/postgresql-*.logإنشاء تهيئة مخصصة لـ OTel collector
يتيح لك ClickStack توسيع التهيئة الأساسية لـ OpenTelemetry Collector من خلال تحميل ملف تهيئة مخصص وتعيين متغير بيئة. وتُدمج التهيئة المخصصة مع التهيئة الأساسية التي يديرها HyperDX عبر OpAMP.
أنشئ ملفًا باسم postgres-logs-monitoring.yaml يتضمن التهيئة التالية:
receivers:
filelog/postgres:
include:
- /var/lib/postgresql/*/main/log/postgresql-*.csv # Adjust to match your PostgreSQL installation
start_at: end
multiline:
line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
operators:
- type: csv_parser
parse_from: body
parse_to: attributes
header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
lazy_quotes: true
- type: time_parser
parse_from: attributes.log_time
layout: '%Y-%m-%d %H:%M:%S.%L %Z'
- type: add
field: attributes.source
value: "postgresql"
- type: add
field: resource["service.name"]
value: "postgresql-production"
service:
pipelines:
logs/postgres:
receivers: [filelog/postgres]
processors:
- memory_limiter
- transform
- batch
exporters:
- clickhouseهذا الإعداد:
- يقرأ سجلات PostgreSQL بتنسيق CSV من موقعها القياسي
- يتعامل مع مُدخلات السجل متعددة الأسطر (فغالبًا ما تمتد الأخطاء عبر عدة أسطر)
- يحلّل تنسيق CSV مع جميع حقول سجل PostgreSQL القياسية
- يستخرج الطوابع الزمنية للحفاظ على التوقيت الأصلي للسجل
- يضيف السمة
source: postgresqlللتصفية في HyperDX - يوجّه السجلات إلى مُصدِّر ClickHouse عبر مسار معالجة مخصّص
هيّئ ClickStack لتحميل إعدادات مخصّصة
لتمكين إعدادات مخصّصة للمجمّع في عملية نشر ClickStack الحالية، يجب عليك:
- ربط ملف الإعدادات المخصّص عند
/etc/otelcol-contrib/custom.config.yaml - تعيين متغير البيئة
CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml - ربط دليل سجلات PostgreSQL لكي يتمكن المجمّع من قراءتها
الخيار 1: Docker Compose
حدّث إعدادات نشر ClickStack:
services:
clickstack:
# ... existing configuration ...
environment:
- CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
# ... other environment variables ...
volumes:
- ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
- /var/lib/postgresql:/var/lib/postgresql:ro
# ... other volumes ...الخيار 2: Docker Run (الصورة المتكاملة)
إذا كنت تستخدم الصورة المتكاملة مع docker run:
docker run --name clickstack \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
-v "$(pwd)/postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v /var/lib/postgresql:/var/lib/postgresql:ro \
clickhouse/clickstack-all-in-one:latestالتحقق من السجلات في HyperDX
بعد إتمام الإعداد، سجّل الدخول إلى HyperDX وتأكد من أن السجلات تتدفق:
- انتقل إلى عرض البحث
- اضبط المصدر على السجلات
- صفِّ باستخدام
source:postgresqlلعرض السجلات الخاصة بـ PostgreSQL - ينبغي أن ترى سجلات منظَّمة تتضمن حقولًا مثل
user_nameوdatabase_nameوerror_severityوmessageوqueryوغيرها.


مجموعة البيانات التجريبية
للمستخدمين الذين يريدون اختبار تكامل سجلات PostgreSQL قبل تهيئة أنظمتهم في بيئة الإنتاج، نوفر مجموعة بيانات نموذجية لسجلات PostgreSQL مُولَّدة مسبقًا بأنماط واقعية.
تنزيل مجموعة البيانات النموذجية
نزّل ملف السجل النموذجي:
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.logإنشاء إعداد collector للاختبار
أنشئ ملفًا باسم postgres-logs-demo.yaml بالإعداد التالي:
cat > postgres-logs-demo.yaml << 'EOF'
receivers:
filelog/postgres:
include:
- /tmp/postgres-demo/postgresql.log
start_at: beginning # اقرأ من البداية للبيانات التجريبية
multiline:
line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
operators:
- type: csv_parser
parse_from: body
parse_to: attributes
header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
lazy_quotes: true
- type: time_parser
parse_from: attributes.log_time
layout: '%Y-%m-%d %H:%M:%S.%L %Z'
- type: add
field: attributes.source
value: "postgresql-demo"
- type: add
field: resource["service.name"]
value: "postgresql-demo"
service:
pipelines:
logs/postgres-demo:
receivers: [filelog/postgres]
processors:
- memory_limiter
- transform
- batch
exporters:
- clickhouse
EOFتشغيل ClickStack باستخدام الإعداد التجريبي
شغّل ClickStack باستخدام السجلات والإعداد التجريبيين:
docker run --name clickstack-demo \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
-v "$(pwd)/postgres-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v "$(pwd)/postgresql.log:/tmp/postgres-demo/postgresql.log:ro" \
clickhouse/clickstack-all-in-one:latestالتحقق من السجلات في HyperDX
بعد تشغيل ClickStack:
- افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
- انتقل إلى عرض Search واضبط source على
Logs - اضبط النطاق الزمني على 2025-11-09 00:00:00 - 2025-11-12 00:00:00


لوحات المعلومات والتصورات المرئية
لمساعدتك على بدء مراقبة PostgreSQL باستخدام ClickStack، نوفر تصورات أساسية لسجلات PostgreSQL.
تنزيل إعدادات لوحة المعلومات
استيراد لوحة المعلومات الجاهزة مسبقًا
- افتح HyperDX وانتقل إلى قسم Dashboards
- انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث

- ارفع ملف
postgresql-logs-dashboard.jsonوانقر على Finish Import

عرض لوحة المعلومات
سيتم إنشاء لوحة المعلومات مع ضبط جميع التصورات مسبقًا:

استكشاف الأخطاء وإصلاحها
تعذّر تحميل الإعدادات المخصّصة
تحقّق من ضبط متغير البيئة:
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILEتحقق من أن ملف الإعدادات المخصّص مُركَّب ويمكن قراءته:
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10عدم ظهور سجلات في HyperDX
تحقق من أن التهيئة الفعّالة تتضمن مستقبِل filelog الخاص بك:
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelogتحقّق من وجود أخطاء في سجلات collector:
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgresإذا كنت تستخدم مجموعة البيانات التجريبية، فتحقق من إمكانية الوصول إلى ملف السجل:
docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -lالخطوات التالية
- أعدّ التنبيهات للأحداث الحرجة (فشل الاتصال، والاستعلامات البطيئة، والارتفاعات المفاجئة في الأخطاء)
- اربط السجلات بـمقاييس PostgreSQL للحصول على مراقبة شاملة لقاعدة البيانات
- أنشئ لوحات معلومات مخصصة لأنماط الاستعلامات الخاصة بتطبيقك
- اضبط
log_min_duration_statementلتحديد الاستعلامات البطيئة بما يتوافق مع متطلبات الأداء لديك
الانتقال إلى بيئة الإنتاج
يستفيد هذا الدليل من OpenTelemetry Collector المضمّن في ClickStack لتسهيل الإعداد السريع. أما لعمليات النشر في بيئة الإنتاج، فنوصي بتشغيل OTel Collector الخاص بك وإرسال البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack. راجع إرسال بيانات OpenTelemetry للاطلاع على إعدادات بيئة الإنتاج.