مراقبة تتبعات Node.js باستخدام ClickStack

يتناول هذا القسم كيفية إضافة التتبّع الموزّع إلى تطبيق Node.js الحالي لديك باستخدام الرصد التلقائي في OpenTelemetry.

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

• مثيل ClickStack قيد التشغيل مع إتاحة الوصول إلى نقاط نهاية OTLP (المنافذ 4317/4318)
• تطبيق Node.js حالي (Node.js 14 أو أحدث)
• مدير حزم npm أو yarn
• اسم المضيف أو عنوان IP الخاص بـ ClickStack

تثبيت OpenTelemetry وتهيئته

ثبّت الحزمة @hyperdx/node-opentelemetry وقم بتهيئتها عند بدء تطبيقك. راجع دليل Node.js SDK للاطلاع على خطوات التثبيت التفصيلية.

الحصول على مفتاح واجهة برمجة تطبيقات لـ ClickStack

ستحتاج إلى مفتاح واجهة برمجة تطبيقات لإرسال التتبعات إلى نقطة نهاية OTLP الخاصة بـ ClickStack.

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

شغّل تطبيقك

ابدأ تشغيل تطبيق Node.js بعد تعيين متغيرات البيئة:

export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

ولّد بعض الحركة

أرسل طلبات إلى تطبيقك لإنشاء تتبعات:

# طلبات بسيطة
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# محاكاة حمل
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done

تحقّق من التتبعات في HyperDX

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

انقر على أي تتبع لعرض التفاصيل، بما في ذلك spans والتوقيت والسمات:

للمستخدمين الذين يريدون اختبار التتبّع في Node.js باستخدام ClickStack قبل إضافة أدوات الرصد إلى تطبيقاتهم في بيئة الإنتاج، نوفر مجموعة بيانات نموذجية تحتوي على تتبعات مُولَّدة مسبقًا لتطبيق Node.js بأنماط حركة مرور واقعية.

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

نزّل ملف التتبعات النموذجي:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

بدء ClickStack

إذا لم يكن ClickStack قيد التشغيل لديك بعد، فابدأه باستخدام:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest

الحصول على مفتاح واجهة برمجة تطبيقات لـ ClickStack

ستحتاج إلى مفتاح واجهة برمجة تطبيقات لإرسال التتبعات إلى نقطة نهاية OTLP الخاصة بـ ClickStack.

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

عيّن مفتاح واجهة برمجة تطبيقات الخاص بك كمتغير بيئة:

export CLICKSTACK_API_KEY=your-api-key-here

إرسال التتبعات إلى ClickStack

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

ينبغي أن ترى استجابة مثل {"partialSuccess":{}}، ما يشير إلى أنه تم إرسال التتبعات بنجاح.

التحقق من التتبعات في HyperDX

1. افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
2. انتقل إلى عرض Search وعيّن المصدر إلى Traces
3. عيّن النطاق الزمني إلى 2025-10-25 13:00:00 - 2025-10-28 13:00:00

لمساعدتك على بدء مراقبة أداء تطبيقات Node.js، نوفر لوحة معلومات مُعدّة مسبقًا تتضمن تصورات أساسية للتتبعات.

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

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

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

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

3. ارفع ملف nodejs-traces-dashboard.json وانقر على إنهاء الاستيراد

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

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

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json

هذه مشكلة معروفة تحدث عند استخدام نهج العرض التوضيحي عبر curl، ولا تؤثر في تطبيقات الإنتاج المزوّدة بأدوات الرصد.

تحقق من ضبط متغيرات البيئة:

echo $CLICKSTACK_API_KEY
# Should output your API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Should output http://localhost:4318 or your ClickStack host

تحقّق من الاتصال بالشبكة:

curl -v http://localhost:4318/v1/traces

يجب أن يتصل بنجاح بـ OTLP endpoint.

تحقق من سجلات التطبيق: ابحث عن رسائل تهيئة OpenTelemetry عند بدء تشغيل تطبيقك. يجب أن تعرض حزمة SDK الخاصة بـ HyperDX تأكيدًا على اكتمال التهيئة.

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

يستخدم هذا الدليل HyperDX SDK، الذي يرسل التتبعات مباشرةً إلى نقطة نهاية OTLP الخاصة بـ ClickStack. ينجح هذا النهج مع بيئات التطوير والاختبار وعمليات النشر الإنتاجية الصغيرة إلى المتوسطة. أما في بيئات الإنتاج الأكبر، أو إذا كنت بحاجة إلى مزيد من التحكم في بيانات القياس عن بُعد، ففكّر في نشر OpenTelemetry Collector الخاص بك بصفته agent. راجع إدخال البيانات باستخدام OpenTelemetry للاطلاع على أنماط النشر في بيئة الإنتاج وأمثلة على تهيئة collector.