> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<Info>
  **باختصار**

  راقب تطبيقات JVM في ClickStack باستخدام وكيل OpenTelemetry لـ Java. يتضمن مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.
</Info>

<div id="existing-jvm">
  ## التكامل مع تطبيق JVM موجود
</div>

يوضح هذا القسم كيفية تهيئة تطبيق JVM الموجود لديك لإرسال المقاييس إلى ClickStack باستخدام وكيل OpenTelemetry لـ Java.

إذا كنت ترغب في اختبار التكامل قبل تهيئة إعداد الإنتاج لديك، يمكنك الاختبار باستخدام مجموعة البيانات التجريبية الخاصة بنا في [قسم مجموعة البيانات التجريبية](#demo-dataset).

<div id="prerequisites">
  ##### المتطلبات المسبقة
</div>

* مثيل ClickStack قيد التشغيل
* تطبيق Java موجود (Java 8+)
* إمكانية تعديل وسيطات بدء تشغيل JVM

<Steps>
  <Step title="الحصول على مفتاح API لـ ClickStack" id="get-api-key">
    يرسل وكيل OpenTelemetry لـ Java البيانات إلى OTLP endpoint الخاص بـ ClickStack، وهو ما يتطلب المصادقة.

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

    <Image img="https://mintcdn.com/private-7c7dfe99/Xl4dVm4Z5MHG1h5Z/images/clickstack/api-key.webp?fit=max&auto=format&n=Xl4dVm4Z5MHG1h5Z&q=85&s=2988f52ae02de449619fe59ca8c55a58" alt="مفتاح API لـ ClickStack" width="3810" height="1924" data-path="images/clickstack/api-key.webp" />
  </Step>

  <Step title="تنزيل وكيل OpenTelemetry لـ Java" id="download-agent">
    نزّل ملف JAR الخاص بوكيل OpenTelemetry لـ Java:

    ```bash theme={null}
    curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.22.0/opentelemetry-javaagent.jar
    ```

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

  <Step title="تهيئة وسيطات بدء تشغيل JVM" id="configure-jvm">
    أضف وكيل Java إلى أمر بدء تشغيل JVM. يجمع الوكيل تلقائيًا مقاييس JVM ويرسلها إلى ClickStack.

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

    ```bash theme={null}
    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: متغيرات البيئة

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

    ```bash theme={null}
    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 الخاص بتطبيقك

    <Tip>
      يجمع وكيل OpenTelemetry لـ Java تلقائيًا مقاييس JVM التالية:

      * **الذاكرة**: `jvm.memory.used`, `jvm.memory.limit`, `jvm.memory.committed`, `jvm.memory.used_after_last_gc`
      * **جمع القمامة**: `jvm.gc.duration`
      * **الخيوط**: `jvm.thread.count`
      * **الفئات**: `jvm.class.count`, `jvm.class.loaded`, `jvm.class.unloaded`
      * **CPU**: `jvm.cpu.time`, `jvm.cpu.count`
    </Tip>
  </Step>

  <Step title="التحقق من المقاييس في HyperDX" id="verifying-metrics">
    بعد تشغيل تطبيقك باستخدام الوكيل، تحقّق من أن المقاييس تتدفّق إلى ClickStack:

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

<div id="demo-dataset">
  ## مجموعة البيانات التجريبية
</div>

بالنسبة إلى المستخدمين الذين يريدون اختبار تكامل مقاييس JVM قبل تزويد تطبيقاتهم بأدوات الرصد، نوفر مجموعة بيانات نموذجية تحتوي على مقاييس مُولَّدة مسبقًا تُظهر سلوك JVM واقعيًا لخدمة مصغّرة متوسطة الحجم ذات حركة مرور ثابتة ومعتدلة.

<Steps>
  <Step title="تنزيل مجموعة البيانات النموذجية" id="download-sample">
    ```bash theme={null}
    # نزّل مقاييس 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
  </Step>

  <Step title="تشغيل ClickStack" id="start-clickstack">
    إذا لم يكن ClickStack قيد التشغيل لديك بالفعل:

    ```bash theme={null}
    docker run -d --name clickstack \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

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

  <Step title="استيراد مجموعة البيانات التجريبية" id="import-demo-data">
    ```bash theme={null}
    # استورد مقاييس 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.
  </Step>

  <Step title="التحقق من البيانات التجريبية" id="verify-demo-metrics">
    بعد اكتمال الاستيراد:

    1. افتح HyperDX على [http://localhost:8080](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`

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

    <Info>
      **عرض المنطقة الزمنية**

      يعرض HyperDX timestamps وفقًا للمنطقة الزمنية المحلية في متصفحك. تمتد البيانات التجريبية عبر **2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)**. اضبط النطاق الزمني على **2025-12-06 14:00:00 - 2025-12-09 14:00:00** لضمان ظهور المقاييس التجريبية بغض النظر عن موقعك. وبعد ظهور المقاييس، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.
    </Info>
  </Step>
</Steps>

<div id="dashboards">
  ## لوحات المعلومات والتصورات
</div>

لمساعدتك في مراقبة تطبيقات JVM باستخدام ClickStack، نوفر لوحة معلومات مُعدّة مسبقًا تتضمن التصورات الأساسية لمقاييس JVM.

<Steps>
  <Step title="تنزيل إعداد لوحة المعلومات" id="download">
    <TrackedLink href={'https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/examples/jvm-metrics-dashboard.json'} download="jvm-metrics-dashboard.json" eventName="docs.kafka_metrics_monitoring.dashboard_download">تنزيل ملف إعداد لوحة المعلومات</TrackedLink>.
  </Step>

  <Step title="استيراد لوحة المعلومات المُعدّة مسبقًا" id="import-dashboard">
    1. افتح HyperDX وانتقل إلى قسم لوحات المعلومات
    2. انقر على **Import لوحة معلومات** في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث

    <Image img="https://mintcdn.com/private-7c7dfe99/MFPY913TqoHcFPXJ/images/clickstack/import-dashboard.webp?fit=max&auto=format&n=MFPY913TqoHcFPXJ&q=85&s=ec4eae8ea8e1f77c9b5897b45339b08b" alt="زر استيراد لوحة المعلومات" width="3024" height="556" data-path="images/clickstack/import-dashboard.webp" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99/MFPY913TqoHcFPXJ/images/clickstack/jvm/jvm-metrics-import.webp?fit=max&auto=format&n=MFPY913TqoHcFPXJ&q=85&s=a62193f99cf4bc8da09114b6d632edcd" alt="إنهاء الاستيراد" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-import.webp" />
  </Step>

  <Step title="عرض لوحة المعلومات" id="created-dashboard">
    سيتم إنشاء لوحة المعلومات مع تهيئة جميع التصورات مسبقًا:

    <Image img="https://mintcdn.com/private-7c7dfe99/MFPY913TqoHcFPXJ/images/clickstack/jvm/jvm-metrics-dashboard.webp?fit=max&auto=format&n=MFPY913TqoHcFPXJ&q=85&s=d7eaec5728cef210052ab15d51e00535" alt="لوحة معلومات مقاييس Kafka" width="3812" height="1902" data-path="images/clickstack/jvm/jvm-metrics-dashboard.webp" />

    <Note>
      بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على **2025-12-07 14:00:00 - 2025-12-08 14:00:00 (UTC)**. وعدّل ذلك وفقًا لمنطقتك الزمنية المحلية.
    </Note>
  </Step>
</Steps>

<div id="troubleshooting">
  ## استكشاف الأخطاء وإصلاحها
</div>

<div id="troubleshooting-not-loading">
  ### تعذّر بدء تشغيل الوكيل
</div>

**تأكّد من وجود ملف JAR الخاص بالوكيل:**

```bash theme={null}
ls -lh /path/to/opentelemetry-javaagent.jar
```

**تحقّق من توافق إصدار Java (يتطلّب Java 8+):**

```bash theme={null}
java -version
```

**تحقّق من ظهور رسالة في السجل عند بدء تشغيل العامل:**
عند بدء تشغيل تطبيقك، يُفترض أن ترى ما يلي:

```text theme={null}
[otel.javaagent] OpenTelemetry Javaagent v2.22.0 started
```

<div id="no-metrics">
  ### عدم ظهور أي مقاييس في HyperDX
</div>

**تحقّق من أن ClickStack قيد التشغيل ويمكن الوصول إليه:**

```bash theme={null}
docker ps | grep clickstack
curl -v http://localhost:4318/v1/metrics
```

**تحقق من تهيئة مُصدِّر المقاييس:**

```bash theme={null}
# If using environment variables, verify:
echo $OTEL_METRICS_EXPORTER
# Should output: otlp
```

**تحقّق من سجلات التطبيق بحثًا عن أخطاء OpenTelemetry:**
ابحث عن أي رسائل error مرتبطة بـ OpenTelemetry أو حالات فشل التصدير عبر OTLP في سجلات تطبيقك.

**تحقّق من اتصال الشبكة:**
إذا كان ClickStack مستضافًا على host بعيد، فتأكّد من إمكانية الوصول إلى المنفذ 4318 من خادم التطبيق لديك.

**تحقّق من إصدار agent:**
تأكّد من أنك تستخدم أحدث إصدار مستقر من agent (حاليًا 2.22.0)، إذ تتضمّن الإصدارات الأحدث غالبًا تحسينات في الأداء.

<div id="next-steps">
  ## الخطوات التالية
</div>

* أعدّ [التنبيهات](/docs/ar/clickstack/features/alerts) للمقاييس الحرِجة مثل ارتفاع استخدام heap، أو تكرار توقّفات GC، أو نفاد الخيوط
* استكشف [تكاملات ClickStack الأخرى](/docs/ar/clickstack/integration-examples/index) لتوحيد بيانات observability لديك

<div id="going-to-production">
  ## الانتقال إلى بيئة الإنتاج
</div>

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

راجع [إدخال البيانات باستخدام OpenTelemetry](/docs/ar/clickstack/ingesting-data/opentelemetry) للاطلاع على أنماط النشر في بيئة الإنتاج وأمثلة على تهيئة collector.