الخلاصةاجمع سجلات خادم PostgreSQL واعرضها بصريًا في ClickStack باستخدام مستقبِل OTel filelog (بتنسيق CSV). يتضمن ذلك مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.
التكامل مع 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
يستخدم هذا الدليل تنسيق csvlog في PostgreSQL لإجراء تحليل منظَّم وموثوق. إذا كنت تستخدم التنسيقين stderr أو jsonlog، فستحتاج إلى تعديل إعدادات OpenTelemetry Collector وفقًا لذلك.
# 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 عبر مسار معالجة مخصّص
- لا تُعرِّف في الإعداد المخصّص سوى
receivers وpipelines الجديدة
- إن
processors (memory_limiter, transform, batch) وexporters (clickhouse) معرّفة مسبقًا في إعداد ClickStack الأساسي — ما عليك إلا الإشارة إليها بالاسم
- يستخرج العامل
csv_parser جميع حقول سجل PostgreSQL القياسية بتنسيق CSV إلى سمات منظَّمة
- يستخدم هذا الإعداد
start_at: end لتجنّب إدخال السجلات مجددًا عند إعادة تشغيل المجمّع. ولأغراض الاختبار، غيّره إلى start_at: beginning لعرض السجلات التاريخية فورًا.
- عدّل المسار
include ليتوافق مع موقع دليل سجلات PostgreSQL لديك
هيّئ 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
تأكد من أن جامع ClickStack يملك الأذونات المناسبة لقراءة ملفات سجلات PostgreSQL. في بيئة الإنتاج، استخدم نقاط تحميل للقراءة فقط (:ro) والتزم بمبدأ أقل الصلاحيات اللازمة.
التحقق من السجلات في HyperDX
بعد إتمام الإعداد، سجّل الدخول إلى HyperDX وتأكد من أن السجلات تتدفق:
- انتقل إلى عرض البحث
- اضبط المصدر على السجلات
- صفِّ باستخدام
source:postgresql لعرض السجلات الخاصة بـ PostgreSQL
- ينبغي أن ترى سجلات منظَّمة تتضمن حقولًا مثل
user_name وdatabase_name وerror_severity وmessage وquery وغيرها.
تنزيل مجموعة البيانات النموذجية
نزّل ملف السجل النموذجي: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
عرض المنطقة الزمنيةيعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية في متصفحك. تغطي البيانات التجريبية الفترة 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC). يضمن اتساع النطاق الزمني ظهور السجلات التجريبية لك بغض النظر عن موقعك. وبعد ظهور السجلات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.
لوحات المعلومات والتصورات المرئية
استيراد لوحة المعلومات الجاهزة مسبقًا
- افتح HyperDX وانتقل إلى قسم Dashboards
- انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث
- ارفع ملف
postgresql-logs-dashboard.json وانقر على Finish Import
عرض لوحة المعلومات
سيتم إنشاء لوحة المعلومات مع ضبط جميع التصورات مسبقًا:بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) (عدّله وفقًا لمنطقتك الزمنية المحلية). لن تتضمن لوحة المعلومات المستوردة نطاقًا زمنيًا محددًا افتراضيًا.
تعذّر تحميل الإعدادات المخصّصة
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10
عدم ظهور سجلات في HyperDX
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
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 لتحديد الاستعلامات البطيئة بما يتوافق مع متطلبات الأداء لديك
الانتقال إلى بيئة الإنتاج
