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

الخلاصةاجمع سجلات أخطاء MySQL وسجلات الاستعلامات البطيئة واعرضها بصريًا في ClickStack باستخدام مستقبِل filelog من OTel. يتضمن ذلك مجموعة بيانات تجريبية ولوحة معلومات جاهزة مسبقًا.

التكامل مع 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

يلتقط سجل الاستعلامات البطيئة الاستعلامات التي تستغرق أكثر من long_query_time ثانية. اضبط هذه العتبة وفقًا لمتطلبات أداء تطبيقك. سيؤدي ضبطها على قيمة منخفضة جدًا إلى إنشاء عدد مفرط من السجلات.

بعد إجراء هذه التغييرات، أعد تشغيل 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 مخصّص

يلزم استخدام receiverَين لأن سجلات أخطاء MySQL وسجلات الاستعلامات البطيئة لها تنسيقات مختلفة تمامًا. يستخدم time_parser تخطيط gotime للتعامل مع تنسيق الطابع الزمني ISO8601 الخاص بـ MySQL مع إزاحات المنطقة الزمنية.

هيّئ 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 ...

تأكد من أن ClickStack collector لديه الأذونات المناسبة لقراءة ملفات سجلّات MySQL. استخدم نقاط تحميل للقراءة فقط (:ro) والتزم بمبدأ الحد الأدنى من الامتيازات.

التحقق من السجلات في 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)

إذا لم تظهر لك السجلات الأربعون كلها فورًا، فانتظر نحو دقيقة حتى ينتهي collector من المعالجة. وإذا لم تظهر السجلات بعد الانتظار، فنفّذ docker restart clickstack-demo ثم تحقّق مرة أخرى بعد دقيقة إضافية. هذه مشكلة معروفة في filelog receiver الخاص بـ OpenTelemetry عند التحميل المجمّع لملفات موجودة مسبقًا باستخدام start_at: beginning. أما عمليات النشر في بيئة production التي تستخدم start_at: end فتعالج السجلات لحظة كتابتها بشكل real-time، ولا تواجه هذه المشكلة.

عرض المنطقة الزمنيةيعرض HyperDX الطوابع الزمنية وفق المنطقة الزمنية المحلية في متصفحك. تمتد بيانات العرض التوضيحي عبر 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC). ويضمن النطاق الزمني الواسع ظهور سجلات العرض التوضيحي بغض النظر عن موقعك. وبعد ظهور السجلات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.

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

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

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

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

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

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

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

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

بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 2025-11-14 00:00:00 - 2025-11-15 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

تحقق من أن الإعدادات الفعلية تتضمن مستقبِل 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 للاطلاع على إعدادات بيئة الإنتاج.

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

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

​تهيئة تسجيل MySQL

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

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

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

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

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

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

​شغّل ClickStack باستخدام التكوين التجريبي

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

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

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

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

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

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

​تعذّر تحميل التهيئة المخصّصة

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

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

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

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

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

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

تهيئة تسجيل MySQL

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

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

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

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

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

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

شغّل ClickStack باستخدام التكوين التجريبي

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

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

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

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

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

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

تعذّر تحميل التهيئة المخصّصة

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

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

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

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

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