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

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

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

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

مثيل ClickStack قيد التشغيل
تثبيت Kafka حالي (الإصدار 2.0 أو أحدث)
إمكانية الوصول إلى ملفات سجلات Kafka (server.log, controller.log، إلخ.)

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

يستخدم Kafka ‏Log4j ويكتب السجلات في الدليل المحدد عبر خاصية النظام kafka.logs.dir أو متغير البيئة LOG_DIR. تحقّق من موقع ملف السجل:

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

ملفات سجل Kafka الأساسية:

server.log: سجلات الوسيط العامة (بدء التشغيل، والاتصالات، والنسخ المتماثل، والأخطاء)
controller.log: الأحداث الخاصة بوحدة التحكم (انتخاب القائد، وإعادة توزيع الأقسام)
state-change.log: انتقالات حالة الأقسام والنسخ المتماثلة

يُنتج نمط Log4j الافتراضي في Kafka أسطرًا مثل:

[2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)

أنشئ تهيئة مخصصة لـ OTel collector لـ Kafka

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

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

receivers:
  filelog/kafka:
    include:
      - /var/log/kafka/server.log
      - /var/log/kafka/controller.log  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

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

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

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

service:
  pipelines:
    logs/kafka:
      receivers: [filelog/kafka]
      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
ربط دليل سجلات Kafka حتى يتمكن المُجمّع من قراءتها

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

services:
  clickstack:
    # ... الإعدادات الحالية ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... متغيرات بيئة أخرى ...
    volumes:
      - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/kafka:/var/log/kafka: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)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/kafka:/var/log/kafka:ro \
  clickhouse/clickstack-all-in-one:latest

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

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

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

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

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

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

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

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

أنشئ ملفًا باسم kafka-logs-demo.yaml بالمحتوى التالي:

cat > kafka-logs-demo.yaml << 'EOF'
receivers:
  filelog/kafka:
    include:
      - /tmp/kafka-demo/server.log
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

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

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

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

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

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

بعد تشغيل ClickStack:

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

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

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

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

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

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

حمّل ملف kafka-logs-dashboard.json وانقر على إنهاء الاستيراد.

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

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

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

تحقّق من أن التهيئة الفعلية تتضمّن مستقبِل filelog الخاص بك:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

تحقّق من أخطاء المجمّع:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

تحقّق من أن تنسيق سجلات Kafka يطابق النمط المتوقع:

tail -1 /var/log/kafka/server.log

إذا كان تثبيت Kafka يستخدم نمط Log4j مخصصًا، فعدّل تعبير regex الخاص بـ regex_parser وفقًا لذلك.

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

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

الانتقال إلى الإنتاج

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