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

يرسل وكيل OpenTelemetry لـ Java البيانات إلى OTLP endpoint الخاص بـ ClickStack، وهو ما يتطلب المصادقة.

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

نزّل ملف JAR الخاص بوكيل OpenTelemetry لـ Java:

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar

سيؤدي هذا إلى تنزيل الوكيل إلى الدليل الحالي. يمكنك وضعه في أي مكان يناسب عملية النشر لديك (على سبيل المثال: /opt/opentelemetry/ أو بجوار ملف JAR الخاص بتطبيقك).

أضف وكيل Java إلى أمر بدء تشغيل JVM. يجمع الوكيل تلقائيًا مقاييس JVM ويرسلها إلى ClickStack.

الخيار 1: خيارات سطر الأوامر

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-java-app \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.exporter.otlp.headers="authorization=YOUR_API_KEY" \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=none \
  -Dotel.traces.exporter=none \
  -jar my-application.jar

استبدل ما يلي:

• opentelemetry-javaagent.jar → المسار الكامل إلى ملف JAR الخاص بالوكيل (على سبيل المثال: /opt/opentelemetry/opentelemetry-javaagent.jar)
• my-java-app → اسمًا واضحًا لخدمتك (على سبيل المثال: payment-service, user-api)
• YOUR_API_KEY → مفتاح API الخاص بـ ClickStack من الأمر أعلاه
• my-application.jar → اسم ملف JAR الخاص بتطبيقك
• http://localhost:4318 → endpoint الخاص بـ ClickStack (استخدم localhost:4318 إذا كان ClickStack يعمل على الجهاز نفسه، وإلا فاستخدم http://your-clickstack-host:4318)

الخيار 2: متغيرات البيئة

بدلًا من ذلك، استخدم متغيرات البيئة:

export JAVA_TOOL_OPTIONS="-javaagent:opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="my-java-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=YOUR_API_KEY"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="none"
export OTEL_TRACES_EXPORTER="none"

java -jar my-application.jar

استبدل ما يلي:

• opentelemetry-javaagent.jar → المسار الكامل إلى ملف JAR الخاص بالوكيل
• my-java-app → اسم خدمتك
• YOUR_API_KEY → مفتاح API الخاص بـ ClickStack
• http://localhost:4318 → endpoint الخاص بـ ClickStack
• my-application.jar → اسم ملف JAR الخاص بتطبيقك

بعد تشغيل تطبيقك باستخدام الوكيل، تحقّق من أن المقاييس تتدفّق إلى ClickStack:

1. افتح HyperDX على http://localhost:8080 (أو عنوان URL الخاص بـ ClickStack)
2. انتقل إلى Chart Explorer
3. ابحث عن المقاييس التي تبدأ بـ jvm. (على سبيل المثال: jvm.memory.used, jvm.gc.duration, jvm.thread.count)

# نزّل مقاييس Gauge ‏(الذاكرة، والخيوط، وCPU، والفئات)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-gauge.jsonl

# نزّل مقاييس Sum ‏(أحداث GC)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/jvm/jvm-metrics-sum.jsonl

تتضمن مجموعة البيانات 24 ساعة من مقاييس JVM، وتُظهر:

• نمو ذاكرة Heap مع أحداث garbage collection دورية
• تغيّرات في عدد الخيوط
• أزمنة توقّف GC واقعية
• نشاط تحميل الفئات
• أنماط استخدام CPU

إذا لم يكن ClickStack قيد التشغيل لديك بالفعل:

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

انتظر بضع لحظات حتى يكتمل تشغيل ClickStack بالكامل.

# استورد مقاييس Gauge ‏(الذاكرة، والخيوط، وCPU، والفئات)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_gauge FORMAT JSONEachRow
" < jvm-metrics-gauge.jsonl

# استورد مقاييس Sum ‏(أحداث GC)
docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_metrics_sum FORMAT JSONEachRow
" < jvm-metrics-sum.jsonl

يؤدي ذلك إلى استيراد المقاييس مباشرةً إلى جداول المقاييس في ClickStack.

بعد اكتمال الاستيراد:

1. افتح HyperDX على http://localhost:8080 وسجّل الدخول (أنشئ حسابًا إذا لزم الأمر)
2. انتقل إلى Search view واضبط source على Metrics
3. اضبط النطاق الزمني على 2025-12-06 14:00:00 - 2025-12-09 14:00:00
4. ابحث عن jvm.memory.used أو jvm.gc.duration

يُفترض أن ترى مقاييس الخدمة التجريبية.

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

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

3. حمّل الملف jvm-metrics-dashboard.json ثم انقر على Finish Import

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