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

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

يتناول هذا القسم كيفية تهيئة تثبيت MongoDB الحالي لديك لإرسال السجلات إلى ClickStack عبر تعديل تهيئة ClickStack OTel collector. إذا كنت ترغب في اختبار تكامل MongoDB قبل تهيئة بيئتك الحالية، فيمكنك التجربة باستخدام الإعداد المُعد مسبقًا والبيانات النموذجية الخاصة بنا في قسم "مجموعة البيانات التجريبية".

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

مثيل ClickStack قيد التشغيل
تثبيت MongoDB مُدار ذاتيًا وموجود مسبقًا (الإصدار 4.4 أو أحدث)
إمكانية الوصول إلى ملفات سجلّات MongoDB

تحقّق من إعدادات التسجيل في MongoDB

ينشئ MongoDB 4.4+ سجلات JSON منظَّمة افتراضيًا. تحقّق من موقع ملف السجل:

cat /etc/mongod.conf | grep -A 5 systemLog

مسارات سجلات MongoDB الشائعة:

Linux (apt/yum): /var/log/mongodb/mongod.log
macOS (Homebrew): /usr/local/var/log/mongodb/mongo.log
Docker: غالبًا ما تُسجَّل السجلات إلى stdout، ولكن يمكن تهيئة MongoDB للكتابة إلى /var/log/mongodb/mongod.log

إذا كان MongoDB يسجّل إلى stdout، فقم بتهيئته للكتابة إلى ملف عبر تحديث mongod.conf:

systemLog:
  destination: file
  path: /var/log/mongodb/mongod.log
  logAppend: true

بعد تغيير الإعدادات، أعد تشغيل MongoDB:

# For systemd
sudo systemctl restart mongod

# For Docker
docker restart <mongodb-container>

أنشئ تهيئة مخصّصة لـ OTel collector خاصة بـ MongoDB

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

أنشئ ملفًا باسم mongodb-monitoring.yaml بالتكوين التالي:

receivers:
  filelog/mongodb:
    include:
      - /var/log/mongodb/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

      - type: move
        from: attributes.msg
        to: body

      - type: add
        field: attributes.source
        value: "mongodb"

      - type: add
        field: resource["service.name"]
        value: "mongodb-production"

service:
  pipelines:
    logs/mongodb:
      receivers: [filelog/mongodb]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

تهيئة ClickStack لتحميل إعدادات مخصصة

لتمكين إعداد مخصص للمجمّع في عملية نشر ClickStack الحالية، يجب عليك:

ربط ملف الإعدادات المخصص عند /etc/otelcol-contrib/custom.config.yaml
تعيين متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
ربط دليل سجلات MongoDB لكي يتمكن المجمّع من قراءته

حدّث إعدادات نشر ClickStack لديك:

services:
  clickstack:
    # ... الإعدادات الحالية ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... متغيرات بيئة أخرى ...
    volumes:
      - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mongodb:/var/log/mongodb:ro
      # ... وحدات تخزين أخرى ...

إذا كنت تستخدم صورة الكل في واحد مع Docker، فشغّل:

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)/mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/mongodb:/var/log/mongodb:ro \
  clickhouse/clickstack-all-in-one:latest

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

بعد إتمام الإعداد، سجّل الدخول إلى HyperDX وتأكد من وصول السجلات:

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

اختبر تكامل MongoDB باستخدام مجموعة بيانات نموذجية مُعدّة مسبقًا قبل تهيئة أنظمة الإنتاج لديك.

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

نزّل ملف السجل النموذجي:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mongodb/mongod.log

إنشاء تهيئة collector للاختبار

أنشئ ملفًا باسم mongodb-demo.yaml بالتكوين التالي:

cat > mongodb-demo.yaml << 'EOF'
receivers:
  filelog/mongodb:
    include:
      - /tmp/mongodb-demo/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

      - type: move
        from: attributes.msg
        to: body

      - type: add
        field: attributes.source
        value: "mongodb-demo"

      - type: add
        field: resource["service.name"]
        value: "mongodb-demo"

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

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

بعد تشغيل ClickStack:

افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج أولًا إلى إنشاء حساب)
انتقل إلى عرض Search واضبط المصدر على Logs
اضبط النطاق الزمني ليشمل 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

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

تنزيل تهيئة لوحة المعلومات

تنزيل ملف تهيئة لوحة المعلومات.

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

افتح HyperDX وانتقل إلى قسم لوحات المعلومات.
انقر على "استيراد لوحة معلومات" في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث.

ارفع ملف mongodb-logs-dashboard.json ثم انقر على إنهاء الاستيراد.

إنهاء استيراد لوحة معلومات سجلات MongoDB

ستُنشأ لوحة المعلومات مع تهيئة جميع التصورات مسبقًا

بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني ليشمل 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

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

عدم ظهور أي سجلات في 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

تعذّر تحليل السجلات بشكل صحيح

تحقق من أن MongoDB يُخرج السجلات بتنسيق JSON ‏(4.4+):

tail -1 /var/log/mongodb/mongod.log | python3 -m json.tool

إذا لم يكن الإخراج بتنسيق JSON صالحًا، فقد يكون إصدار MongoDB لديك يستخدم تنسيق سجل نصي قديمًا (ما قبل 4.4). ستحتاج إلى استبدال العامل json_parser بـ regex_parser، أو الترقية إلى MongoDB 4.4+.

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

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

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

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