> ## 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.
# مراقبة تتبعات Node.js باستخدام ClickStack
> مراقبة تتبعات تطبيقات Node.js باستخدام 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
{children}
;
};
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
**باختصار**
التقط التتبعات الموزعة من تطبيقات Node.js في ClickStack باستخدام الرصد التلقائي من OpenTelemetry. يتضمن مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.
## التكامل مع تطبيق Node.js الحالي
يتناول هذا القسم كيفية إضافة التتبّع الموزّع إلى تطبيق Node.js الحالي لديك باستخدام الرصد التلقائي في OpenTelemetry.
إذا كنت ترغب في اختبار هذا التكامل قبل تهيئة بيئتك الحالية، يمكنك تجربة الإعداد المُعَدّ مسبقًا والبيانات النموذجية في [قسم مجموعة البيانات التجريبية](#demo-dataset).
##### المتطلبات الأساسية
* مثيل ClickStack قيد التشغيل مع إتاحة الوصول إلى نقاط نهاية OTLP (المنافذ 4317/4318)
* تطبيق Node.js حالي (Node.js 14 أو أحدث)
* مدير حزم npm أو yarn
* اسم المضيف أو عنوان IP الخاص بـ ClickStack
ثبّت الحزمة `@hyperdx/node-opentelemetry` وقم بتهيئتها عند بدء تطبيقك. راجع [دليل Node.js SDK](/docs/ar/clickstack/ingesting-data/sdks/nodejs#getting-started) للاطلاع على خطوات التثبيت التفصيلية.
ستحتاج إلى مفتاح واجهة برمجة تطبيقات لإرسال التتبعات إلى نقطة نهاية OTLP الخاصة بـ ClickStack.
1. افتح HyperDX على عنوان URL الخاص بـ ClickStack (على سبيل المثال: [http://localhost:8080](http://localhost:8080))
2. أنشئ حسابًا أو سجّل الدخول عند الحاجة
3. انتقل إلى **Team Settings → API Keys**
4. انسخ **Ingestion API Key** الخاص بك
ابدأ تشغيل تطبيق Node.js بعد تعيين متغيرات البيئة:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```
أرسل طلبات إلى تطبيقك لإنشاء تتبعات:
```bash theme={null}
# طلبات بسيطة
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 وتحقّق من وصول التتبعات. ينبغي أن ترى شيئًا مشابهًا لما يلي. إذا لم تظهر لك التتبعات، فجرّب تعديل النطاق الزمني:
انقر على أي تتبع لعرض التفاصيل، بما في ذلك spans والتوقيت والسمات:
## مجموعة البيانات التجريبية
للمستخدمين الذين يريدون اختبار التتبّع في Node.js باستخدام ClickStack قبل إضافة أدوات الرصد إلى تطبيقاتهم في بيئة الإنتاج، نوفر مجموعة بيانات نموذجية تحتوي على تتبعات مُولَّدة مسبقًا لتطبيق Node.js بأنماط حركة مرور واقعية.
نزّل ملف التتبعات النموذجي:
```bash theme={null}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json
```
إذا لم يكن ClickStack قيد التشغيل لديك بعد، فابدأه باستخدام:
```bash theme={null}
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
```
ستحتاج إلى مفتاح واجهة برمجة تطبيقات لإرسال التتبعات إلى نقطة نهاية OTLP الخاصة بـ ClickStack.
1. افتح HyperDX على عنوان URL الخاص بـ ClickStack لديك (على سبيل المثال، [http://localhost:8080](http://localhost:8080))
2. أنشئ حسابًا أو سجّل الدخول إذا لزم الأمر
3. انتقل إلى **Team Settings → API Keys**
4. انسخ **Ingestion API Key** الخاص بك
عيّن مفتاح واجهة برمجة تطبيقات الخاص بك كمتغير بيئة:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
```
```bash theme={null}
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-H "Authorization: $CLICKSTACK_API_KEY" \
-d @nodejs-traces-sample.json
```
ينبغي أن ترى استجابة مثل `{"partialSuccess":{}}`، ما يشير إلى أنه تم إرسال التتبعات بنجاح.
1. افتح [HyperDX](http://localhost:8080/) وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
2. انتقل إلى عرض **Search** وعيّن المصدر إلى **Traces**
3. عيّن النطاق الزمني إلى **2025-10-25 13:00:00 - 2025-10-28 13:00:00**
**عرض المنطقة الزمنية**
يعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية لمتصفحك. تمتد البيانات التجريبية عبر **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**. يضمن النطاق الزمني الواسع ظهور التتبعات التجريبية بغض النظر عن موقعك. وبعد ظهور التتبعات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.
## لوحات المعلومات والتصورات
لمساعدتك على بدء مراقبة أداء تطبيقات Node.js، نوفر لوحة معلومات مُعدّة مسبقًا تتضمن تصورات أساسية للتتبعات.
نزّل ملف إعدادات لوحة المعلومات.
1. افتح HyperDX وانتقل إلى قسم **لوحات المعلومات**
2. انقر على **استيراد لوحة معلومات** في الزاوية العلوية اليمنى (ضمن قائمة النقاط الثلاث)
3. ارفع ملف `nodejs-traces-dashboard.json` وانقر على **إنهاء الاستيراد**
بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)** (عدّله وفقًا لمنطقتك الزمنية المحلية). لن يكون للنطاق الزمني في لوحة المعلومات المستوردة أي قيمة محددة افتراضيًا.
## استكشاف الأخطاء وإصلاحها
### عدم ظهور تتبعات العرض التوضيحي عند الإرسال عبر curl
إذا كنت قد أرسلت التتبعات عبر curl ولكنك لا تراها في HyperDX، فجرّب إرسالها مرةً أخرى:
```bash theme={null}
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-H "Authorization: $CLICKSTACK_API_KEY" \
-d @nodejs-traces-sample.json
```
هذه مشكلة معروفة تحدث عند استخدام نهج العرض التوضيحي عبر curl، ولا تؤثر في تطبيقات الإنتاج المزوّدة بأدوات الرصد.
### عدم ظهور التتبعات في HyperDX
**تحقق من ضبط متغيرات البيئة:**
```bash theme={null}
echo $CLICKSTACK_API_KEY
# Should output your API key
echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Should output http://localhost:4318 or your ClickStack host
```
**تحقّق من الاتصال بالشبكة:**
```bash theme={null}
curl -v http://localhost:4318/v1/traces
```
يجب أن يتصل بنجاح بـ OTLP endpoint.
**تحقق من سجلات التطبيق:**
ابحث عن رسائل تهيئة OpenTelemetry عند بدء تشغيل تطبيقك. يجب أن تعرض حزمة SDK الخاصة بـ HyperDX تأكيدًا على اكتمال التهيئة.
## الخطوات التالية
* أعدّ [التنبيهات](/docs/ar/clickstack/features/alerts) للمقاييس المهمة (معدلات الأخطاء، حدود زمن الاستجابة)
* أنشئ لوحات معلومات إضافية لحالات استخدام محددة (مراقبة واجهة برمجة التطبيقات، الأحداث الأمنية)
## الانتقال إلى الإنتاج
يستخدم هذا الدليل HyperDX SDK، الذي يرسل التتبعات مباشرةً إلى نقطة نهاية OTLP الخاصة بـ ClickStack. ينجح هذا النهج مع بيئات التطوير والاختبار وعمليات النشر الإنتاجية الصغيرة إلى المتوسطة.
أما في بيئات الإنتاج الأكبر، أو إذا كنت بحاجة إلى مزيد من التحكم في بيانات القياس عن بُعد، ففكّر في نشر OpenTelemetry Collector الخاص بك بصفته agent.
راجع [إدخال البيانات باستخدام OpenTelemetry](/docs/ar/clickstack/ingesting-data/opentelemetry) للاطلاع على أنماط النشر في بيئة الإنتاج وأمثلة على تهيئة collector.