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

التكامل مع نشر Kafka حالي

راقب نشر Kafka الحالي لديك من خلال تشغيل حاوية OpenTelemetry JMX Metric Gatherer لجمع المقاييس وإرسالها إلى ClickStack عبر OTLP.

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

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

مثيل ClickStack قيد التشغيل
تثبيت Kafka قائم (الإصدار 2.0 أو أحدث) مع تمكين JMX
إمكانية الوصول عبر الشبكة بين ClickStack وKafka (منفذ JMX ‏9999، ومنفذ Kafka ‏9092)
ملف JAR الخاص بـ OpenTelemetry JMX Metric Gatherer (تعليمات التنزيل أدناه)

الحصول على مفتاح API لـ ClickStack

يرسل JMX Metric Gatherer البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack، والتي تتطلب المصادقة.

افتح HyperDX على عنوان URL الخاص بـ ClickStack (على سبيل المثال، http://localhost:8080)
أنشئ حسابًا أو سجّل الدخول إذا لزم الأمر
انتقل إلى إعدادات الفريق → مفاتيح API
انسخ مفتاح API للإدخال الخاص بك

عيّنه كمتغير بيئة:

export CLICKSTACK_API_KEY=your-api-key-here

حمّل OpenTelemetry JMX Metric Gatherer

حمّل ملف JAR الخاص بـ JMX Metric Gatherer:

curl -L -o opentelemetry-jmx-metrics.jar \
  https://github.com/open-telemetry/opentelemetry-java-contrib/releases/download/v1.32.0/opentelemetry-jmx-metrics.jar

تحقّق من تفعيل Kafka JMX

تأكّد من أن JMX مفعّل على وسطاء Kafka لديك. بالنسبة إلى عمليات نشر Docker:

services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... other Kafka configuration
    ports:
      - "9092:9092"
      - "9999:9999"

بالنسبة لعمليات النشر غير المعتمدة على Docker، اضبط ما يلي في إعدادات بدء تشغيل Kafka:

export JMX_PORT=9999

تأكّد من إمكانية الوصول إلى JMX:

netstat -an | grep 9999

نشر JMX Metric Gatherer باستخدام Docker Compose

يوضح هذا المثال إعدادًا كاملًا يضم Kafka وJMX Metric Gatherer وClickStack. عدّل أسماء الخدمات ونقاط النهاية لتتوافق مع عملية النشر الحالية لديك:

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring

  kafka:
    image: confluentinc/cp-kafka:latest
    hostname: kafka
    container_name: kafka
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092'
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://kafka:9092,CONTROLLER://kafka:29093'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      KAFKA_JMX_OPTS: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=kafka -Dcom.sun.management.jmxremote.rmi.port=9999'
    ports:
      - "9092:9092"
      - "9999:9999"
    networks:
      - monitoring

  kafka-jmx-exporter:
    image: eclipse-temurin:11-jre
    depends_on:
      - kafka
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./opentelemetry-jmx-metrics.jar:/app/opentelemetry-jmx-metrics.jar
    command: >
      sh -c "java
      -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi
      -Dotel.jmx.target.system=kafka
      -Dotel.metrics.exporter=otlp
      -Dotel.exporter.otlp.protocol=http/protobuf
      -Dotel.exporter.otlp.endpoint=http://clickstack:4318
      -Dotel.exporter.otlp.headers=authorization=\${CLICKSTACK_API_KEY}
      -Dotel.resource.attributes=service.name=kafka,kafka.broker.id=broker-0
      -Dotel.jmx.interval.milliseconds=10000
      -jar /app/opentelemetry-jmx-metrics.jar"
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

معلمات التكوين الأساسية:

service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - عنوان URL للاتصال عبر JMX (استخدم اسم مضيف Kafka الخاص بك)
otel.jmx.target.system=kafka - يفعّل المقاييس الخاصة بـ Kafka
http://clickstack:4318 - نقطة نهاية OTLP عبر HTTP (استخدم اسم مضيف ClickStack الخاص بك)
authorization=\${CLICKSTACK_API_KEY} - مفتاح API للمصادقة (مطلوب)
service.name=kafka,kafka.broker.id=broker-0 - سمات المورد لأغراض التصفية
10000 - الفاصل الزمني للتجميع بالمللي ثانية (10 ثوانٍ)

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

سجّل الدخول إلى HyperDX وتأكد من أن المقاييس تصل بشكل صحيح:

انتقل إلى Chart Explorer
ابحث عن kafka.message.count أو kafka.partition.count
يجب أن تظهر المقاييس كل 10 ثوانٍ

المقاييس الرئيسية التي يجب التحقق منها:

kafka.message.count - إجمالي الرسائل المُعالجة
kafka.partition.count - إجمالي الأقسام
kafka.partition.under_replicated - يجب أن تكون القيمة 0 في عنقود سليم
kafka.network.io - معدل نقل الشبكة
kafka.request.time.* - المئينات لزمن استجابة الطلب

لتوليد نشاط وملء المزيد من المقاييس:

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

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

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

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

نزّل ملفات المقاييس المُولَّدة مسبقًا (29 ساعة من مقاييس Kafka بأنماط واقعية):

# نزّل مقاييس gauge (أعداد الأقسام، وأحجام الطوابير، وزمن الاستجابة، وتأخر المستهلك)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv

# نزّل مقاييس sum (معدلات الرسائل، ومعدلات البايتات، وأعداد الطلبات)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv

تتضمن مجموعة البيانات أنماطًا واقعية لعنقود Kafka للتجارة الإلكترونية بوسيط واحد:

06:00-08:00: ذروة الصباح - ارتفاع حاد في حركة المرور انطلاقًا من خط الأساس الليلي
10:00-10:15: تخفيضات خاطفة - قفزة كبيرة إلى 3.5 أضعاف حركة المرور المعتادة
11:30: حدث نشر - قفزة بمقدار 12 ضعفًا في تأخر المستهلك مع التقسيمات غير المكررة بما يكفي
14:00-15:30: ذروة التسوق - حركة مرور مرتفعة مستمرة عند 2.8 ضعف خط الأساس
17:00-17:30: ذروة ما بعد العمل - ذروة ثانوية في حركة المرور
18:45: إعادة توازن المستهلك - قفزة بمقدار 6 أضعاف في التأخر أثناء إعادة التوازن
20:00-22:00: تراجع المساء - انخفاض حاد إلى مستويات الليل

ابدأ ClickStack

ابدأ مثيل ClickStack:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

حمّل المقاييس إلى ClickStack

حمّل المقاييس مباشرةً إلى ClickHouse:

# حمّل مقاييس gauge (أعداد الأقسام، وأحجام الطوابير، وزمن الاستجابة، وتأخر المستهلك)
cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# حمّل مقاييس sum (معدلات الرسائل، ومعدلات البايتات، وأعداد الطلبات)
cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

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

بعد التحميل، أسرع طريقة لرؤية مقاييسك هي عبر لوحة المعلومات المُعَدّة مسبقًا.

انتقل إلى قسم لوحات المعلومات والتصور لاستيراد لوحة المعلومات وعرض جميع مقاييس Kafka دفعةً واحدة.

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

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

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

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

استورد لوحة المعلومات الجاهزة مسبقًا

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

ارفع ملف kafka-metrics-dashboard.json وانقر على Finish Import

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

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

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

عدم ظهور أي مقاييس في HyperDX

تحقق من ضبط مفتاح API وتمريره إلى الحاوية:

# Check environment variable
echo $CLICKSTACK_API_KEY

# Verify it's in the container
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY

إذا لم يكن موجودًا، فاضبطه ثم أعد التشغيل:

export CLICKSTACK_API_KEY=your-api-key-here
docker compose up -d kafka-jmx-exporter

تحقّق من وصول المقاييس إلى ClickHouse:

docker exec <clickstack-container> clickhouse-client --query "
SELECT DISTINCT MetricName 
FROM otel_metrics_sum 
WHERE ServiceName = 'kafka' 
LIMIT 10
"

إذا لم تظهر أي نتائج، فتحقق من سجلات JMX exporter:

docker compose logs kafka-jmx-exporter | grep -i "error\|connection" | tail -10

أنشئ نشاطًا على Kafka لتعبئة المقاييس:

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

أخطاء المصادقة

إذا رأيت Authorization failed أو 401 Unauthorized:

تحقّق من مفتاح API في واجهة مستخدم HyperDX (الإعدادات → مفاتيح API → مفتاح API للإدخال)
أعِد التصدير ثم أعِد التشغيل:

export CLICKSTACK_API_KEY=your-correct-api-key
docker compose down
docker compose up -d

تعارضات المنافذ مع أوامر عميل Kafka

عند تشغيل أوامر Kafka من داخل حاوية Kafka، قد يظهر لك:

Error: Port already in use: 9999

ابدأ الأوامر بـ unset JMX_PORT &&:

docker exec kafka bash -c "unset JMX_PORT && kafka-topics --list --bootstrap-server kafka:9092"

مشكلات الاتصال بالشبكة

إذا كانت سجلات JMX exporter تعرض Connection refused:

تحقّق من أن جميع الحاويات على شبكة Docker نفسها:

docker compose ps
docker network inspect <network-name>

اختبر الاتصال:

# From JMX exporter to ClickStack
docker exec <jmx-exporter-container> sh -c "timeout 2 bash -c 'cat < /dev/null > /dev/tcp/clickstack/4318' && echo 'Connected' || echo 'Failed'"

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

قم بإعداد التنبيهات للمقاييس الحرجة (التقسيمات غير المكررة بما يكفي، وزيادة تأخر المستهلك، والارتفاعات المفاجئة في زمن استجابة الطلبات)
أنشئ لوحات معلومات إضافية لحالات استخدام محددة (معدل النقل لكل topic، ومراقبة consumer group)
راقب عدة وسطاء Kafka عبر إضافة مثيلات إضافية من JMX Metric Gatherer مع resource attributes فريدة لـ kafka.broker.id

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

يرسل هذا الدليل المقاييس مباشرةً من JMX Metric Gatherer إلى نقطة نهاية OTLP الخاصة بـ ClickStack، وهو ما يناسب الاختبار وعمليات النشر الصغيرة.

بالنسبة إلى بيئات الإنتاج، انشر OpenTelemetry Collector الخاص بك بوصفه agent لتلقّي المقاييس من JMX Exporter وإعادة توجيهها إلى ClickStack. يوفّر ذلك التجميع الدفعي، والمرونة، والإدارة المركزية للتهيئة.

راجع إدخال البيانات باستخدام OpenTelemetry للاطلاع على أنماط النشر في بيئة الإنتاج وأمثلة على تهيئة collector.