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

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

يتناول هذا القسم كيفية تهيئة إعداد MySQL الحالي لديك لإرسال السجلات إلى ClickStack، وذلك من خلال تعديل إعدادات ClickStack OTel collector. إذا كنت ترغب في اختبار تكامل سجلات MySQL قبل تهيئة إعدادك الحالي، فيمكنك تجربة الإعداد المهيأ مسبقًا والبيانات التجريبية في قسم “مجموعة البيانات التجريبية”.
المتطلبات الأساسية
  • مثيل ClickStack قيد التشغيل
  • تثبيت MySQL موجود (الإصدار 5.7 أو أحدث)
  • إمكانية تعديل ملفات إعداد MySQL
  • مساحة قرص كافية لملفات السجل
1

​
تهيئة تسجيل 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
2

​
أنشئ إعدادًا مخصصًا لـ 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 مع إزاحات المنطقة الزمنية.
3

​
هيّئ 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) والتزم بمبدأ الحد الأدنى من الامتيازات.
4

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

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

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

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

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

نزّل ملفات السجل التجريبية:
# 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)
  • الاستعلامات البطيئة ذات خصائص الأداء الواقعية
  • أحداث دورة حياة الاتصال
  • تسلسلات بدء تشغيل خادم قاعدة البيانات وإيقافه
2

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

أنشئ ملفًا باسم 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
3

​
شغّل 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
4

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

بمجرد تشغيل ClickStack:
  1. انتظر بضع لحظات حتى يكتمل تهيئة ClickStack بالكامل (عادةً خلال 30 إلى 60 ثانية)
  2. افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
  3. انتقل إلى عرض Search واضبط المصدر على Logs
  4. اضبط النطاق الزمني على 2025-11-13 00:00:00 - 2025-11-16 00:00:00
  5. من المفترض أن ترى ما مجموعه 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.
1

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

2

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

  1. افتح HyperDX وانتقل إلى قسم Dashboards
  2. انقر على Import Dashboard في الزاوية العلوية اليمنى من قائمة النقاط الثلاث
  1. ارفع ملف mysql-logs-dashboard.json ثم انقر على Finish Import
3

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

سيتم إنشاء لوحة المعلومات مع إعداد جميع التصورات مسبقًا.
بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 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 للاطلاع على إعدادات بيئة الإنتاج.
آخر تعديل في ٢٥ يونيو ٢٠٢٦