Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

مراقبة سجلات PostgreSQL باستخدام ClickStack

التكامل مع 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 الحالية، يجب عليك:

  1. ربط ملف الإعدادات المخصّص عند /etc/otelcol-contrib/custom.config.yaml
  2. تعيين متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. ربط دليل سجلات 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 وتأكد من أن السجلات تتدفق:

  1. انتقل إلى عرض البحث
  2. اضبط المصدر على السجلات
  3. صفِّ باستخدام source:postgresql لعرض السجلات الخاصة بـ PostgreSQL
  4. ينبغي أن ترى سجلات منظَّمة تتضمن حقولًا مثل 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:

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

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

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

تنزيل إعدادات لوحة المعلومات

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

  1. افتح HyperDX وانتقل إلى قسم Dashboards
  2. انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث
زر استيراد لوحة المعلومات
  1. ارفع ملف 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 للاطلاع على إعدادات بيئة الإنتاج.

Navigation