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

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

يتناول هذا القسم كيفية تهيئة إعداد MySQL الحالي لديك لإرسال السجلات إلى ClickStack، وذلك من خلال تعديل إعدادات ClickStack OTel collector.

إذا كنت ترغب في اختبار تكامل سجلات MySQL قبل تهيئة إعدادك الحالي، فيمكنك تجربة الإعداد المهيأ مسبقًا والبيانات التجريبية في قسم "مجموعة البيانات التجريبية".

المتطلبات الأساسية

مثيل ClickStack قيد التشغيل
تثبيت MySQL موجود (الإصدار 5.7 أو أحدث)
إمكانية تعديل ملفات إعداد MySQL
مساحة قرص كافية لملفات السجل

تهيئة تسجيل MySQL

يدعم MySQL عدة أنواع من السجلات. وللحصول على مراقبة شاملة باستخدام OpenTelemetry، نوصي بتمكين سجل الأخطاء وسجل الاستعلامات البطيئة.

يوجد ملف التهيئة my.cnf أو my.ini عادةً في:

Linux (apt/yum): /etc/mysql/my.cnf أو /etc/my.cnf
macOS (Homebrew): /usr/local/etc/my.cnf أو /opt/homebrew/etc/my.cnf
Docker: تُضبط التهيئة عادةً عبر متغيرات البيئة أو من خلال ملف تهيئة يتم ربطه

أضِف هذه الإعدادات أو عدّلها في القسم [mysqld]:

[mysqld]
# Error log configuration
log_error = /var/log/mysql/error.log

# Slow query log configuration
slow_query_log = ON
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1
log_queries_not_using_indexes = ON

# Optional: General query log (verbose, use with caution in production)
# general_log = ON
# general_log_file = /var/log/mysql/mysql-general.log

بعد إجراء هذه التغييرات، أعد تشغيل MySQL:

# For systemd
sudo systemctl restart mysql

# For Docker
docker restart <mysql-container>

تحقق من تسجيل السجلات:

# Check error log
tail -f /var/log/mysql/error.log

# Check slow query log
tail -f /var/log/mysql/mysql-slow.log

أنشئ إعدادًا مخصصًا لـ OTel collector

يتيح لك ClickStack توسيع إعداد OpenTelemetry Collector الأساسي من خلال تركيب ملف إعداد مخصص وتعيين متغير بيئة. ويُدمج الإعداد المخصص مع الإعداد الأساسي الذي يديره HyperDX عبر OpAMP.

أنشئ ملفًا باسم mysql-logs-monitoring.yaml يتضمن الإعداد التالي:

receivers:
  filelog/mysql_error:
    include:
      - /var/log/mysql/error.log
    start_at: end
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
        
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-error"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

  filelog/mysql_slow:
    include:
      - /var/log/mysql/mysql-slow.log
    start_at: end
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-slow"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

service:
  pipelines:
    logs/mysql:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

هذا الإعداد:

يقرأ سجلات أخطاء MySQL وسجلات الاستعلامات البطيئة من مواقعها القياسية
يتعامل مع إدخالات السجل متعددة الأسطر (إذ تمتد الاستعلامات البطيئة عبر عدة أسطر)
يحلّل كِلا تنسيقي السجل لاستخراج الحقول المنظَّمة (level, error_code, query_time, rows_examined)
يحتفظ بالطوابع الزمنية الأصلية للسجلات
يضيف السمات source: mysql-error وsource: mysql-slow لاستخدامها في التصفية داخل HyperDX
يوجّه السجلات إلى ClickHouse exporter عبر pipeline مخصّص

هيّئ ClickStack لتحميل تهيئة مخصصة

لتمكين تهيئة collector مخصصة في نشر ClickStack الحالي، اربط ملف التهيئة المخصص عند /etc/otelcol-contrib/custom.config.yaml واضبط متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml.

حدّث تهيئة نشر ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./mysql-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mysql:/var/log/mysql:ro
      # ... other volumes ...

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

بمجرد اكتمال الإعداد، سجّل الدخول إلى HyperDX وتحقق من تدفق السجلات:

انتقل إلى عرض البحث
اضبط المصدر على Logs
صفِّ باستخدام source:mysql-error أو source:mysql-slow لعرض السجلات الخاصة بـ MySQL
ينبغي أن ترى إدخالات سجل مهيكلة تتضمن حقولًا مثل level وerror_code وmessage (لسجلات الأخطاء)، وquery_time وrows_examined وquery (لسجلات الاستعلامات البطيئة)

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

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

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

نزّل ملفات السجل التجريبية:

# Download error log
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/error.log

# Download slow query log
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/mysql-slow.log

تتضمن مجموعة البيانات ما يلي:

سجلات الأخطاء (رسائل بدء التشغيل، والتحذيرات، وأخطاء الاتصال، ورسائل InnoDB)
الاستعلامات البطيئة ذات خصائص الأداء الواقعية
أحداث دورة حياة الاتصال
تسلسلات بدء تشغيل خادم قاعدة البيانات وإيقافه

أنشئ تهيئة مجمّع الاختبار

أنشئ ملفًا باسم mysql-logs-demo.yaml يتضمن التهيئة التالية:

cat > mysql-logs-demo.yaml << 'EOF'
receivers:
  filelog/mysql_error:
    include:
      - /tmp/mysql-demo/error.log
    start_at: beginning  # Read from beginning for demo data
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-error"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

  filelog/mysql_slow:
    include:
      - /tmp/mysql-demo/mysql-slow.log
    start_at: beginning  # Read from beginning for demo data
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-slow"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

service:
  pipelines:
    logs/mysql-demo:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      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)/mysql-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/error.log:/tmp/mysql-demo/error.log:ro" \
  -v "$(pwd)/mysql-slow.log:/tmp/mysql-demo/mysql-slow.log:ro" \
  clickhouse/clickstack-all-in-one:latest

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

بمجرد تشغيل ClickStack:

انتظر بضع لحظات حتى يكتمل تهيئة ClickStack بالكامل (عادةً خلال 30 إلى 60 ثانية)
افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
انتقل إلى عرض Search واضبط المصدر على Logs
اضبط النطاق الزمني على 2025-11-13 00:00:00 - 2025-11-16 00:00:00
من المفترض أن ترى ما مجموعه 40 سجلًا (30 سجل error مع source:mysql-demo-error + 10 queries بطيئة مع source:mysql-demo-slow)

لوحات المعلومات والتصورات

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

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

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

استيراد لوحة المعلومات المعدّة مسبقًا

افتح HyperDX وانتقل إلى قسم Dashboards
انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث

ارفع ملف mysql-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 mysql

إذا كنت تستخدم مجموعة البيانات التجريبية، فتأكد من أن ملفات السجل متاحة:

docker exec <container> cat /tmp/mysql-demo/error.log | wc -l
docker exec <container> cat /tmp/mysql-demo/mysql-slow.log | wc -l

عدم ظهور سجلات الاستعلامات البطيئة

تأكّد من تفعيل سجل الاستعلامات البطيئة في MySQL:

SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';

تحقق مما إذا كان MySQL يسجل الاستعلامات البطيئة:

tail -f /var/log/mysql/mysql-slow.log

أنشئ استعلامًا بطيئًا تجريبيًا:

SELECT SLEEP(2);

عدم تحليل السجلات بشكل صحيح

تأكد من أن تنسيق سجل MySQL لديك يطابق التنسيق المتوقع. صُممت أنماط Regex في هذا الدليل لتلائم التنسيقات الافتراضية في MySQL 5.7+ و8.0+.

راجع بضعة أسطر من سجل الأخطاء لديك:

head -5 /var/log/mysql/error.log

التنسيق المتوقَّع:

2025-11-14T10:23:45.123456+00:00 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.35) starting as process 1

إذا كان التنسيق المستخدم لديك مختلفًا بدرجة كبيرة، فعدّل أنماط التعبيرات النمطية في الإعداد.

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

أعدّ التنبيهات للأحداث الحرجة (مثل حالات فشل الاتصال، والاستعلامات البطيئة التي تتجاوز الحدود المحددة، والارتفاع المفاجئ في الأخطاء)
أنشئ لوحات معلومات مخصصة لتحليل الاستعلامات البطيئة حسب نمط الاستعلام
اضبط long_query_time بناءً على الأنماط المرصودة في أداء الاستعلامات

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

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