إضافة Chrome

يقوم إضافة HyperDX Chrome بحقن حزمة SDK الخاصة بـ@hyperdx/browser في الصفحات التي تزورها. ويكون مفيدًا عندما تريد تصحيح أخطاء إعادة تشغيل الجلسة أو RUM أو تمرير التتبّع على موقع من دون تعديل الشفرة المصدرية الخاصة به — مثل تطبيق تابع لجهة خارجية، أو إصدار إنتاجي، أو خادم تطوير محلي يفرض سياسة Content Security Policy ‏(CSP) صارمة.

حزمة SDK مضمّنة داخل الإضافة (~480 KB)، لذلك لا تحتاج الصفحات إلى تحميل البرامج النصية من CDN وقت التشغيل. وتحاول الإضافة أولًا حقن البرامج النصية الخارجية عبر chrome-extension://، ثم تلجأ إلى الحقن المضمّن عندما تمنع CSP البرامج النصية القادمة من مصدر الإضافة.

وعلى خلاف Session Replay Demo، الذي يضيف أدوات الرصد إلى تطبيق تجريبي تتحكم فيه، يعمل هذا الأسلوب مع أي عنوان URL تفتحه في Chrome. وتُنشئ بيانات الجلسة من خلال التفاعل مع الموقع كمستخدم عادي.

للاطلاع على خلفية حول إعادة تشغيل الجلسة وكيف تندرج ضمن ClickStack، راجع صفحة ميزة إعادة تشغيل الجلسة.

• Google Chrome أو متصفح يعتمد على Chromium ‏(Edge وBrave وما إلى ذلك)
• تثبيت Docker إذا كنت تشغّل ClickStack محليًا
• توافر المنافذ 4317 و4318 و8080 (لتشغيل ClickStack محليًا)

استنساخ مستودع الإضافة

git clone https://github.com/kyreddie/hyperdx-chrome-extension
cd hyperdx-chrome-extension

تثبيت الإضافة

1. افتح Chrome وانتقل إلى chrome://extensions.
2. فعّل Developer mode (أعلى اليمين).
3. انقر على Load unpacked.
4. حدّد الدليل hyperdx-chrome-extension الذي استنسخته.

ستظهر الإضافة في شريط الأدوات باسم HyperDX Browser Extension.

تشغيل ClickStack

إذا كانت لديك بالفعل نقطة نهاية لاستيعاب البيانات في ClickStack أو HyperDX، فانتقل مباشرةً إلى تهيئة الإضافة.

بالنسبة إلى ClickStack محلي، شغّل OpenTelemetry Collector. استبدل {{CLICKHOUSE_ENDPOINT}} و{{CLICKHOUSE_PASSWORD}} بتفاصيل اتصال ClickHouse:

export CLICKHOUSE_ENDPOINT={{CLICKHOUSE_ENDPOINT}}
export CLICKHOUSE_PASSWORD={{CLICKHOUSE_PASSWORD}}

docker run \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  clickhouse/clickstack-otel-collector:latest

افتح HyperDX على http://localhost:8080 للتأكد من أن واجهة المستخدم تعمل.

للنشر المحلي الكامل مع ClickHouse وHyperDX UI، راجع البدء مع ClickStack.

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

بالنسبة إلى ClickStack المحلي، قد لا تحتاج إلى مفتاح واجهة برمجة التطبيقات — اترك الحقل فارغًا في الإضافة عند إرسال بيانات telemetry إلى collector مستضاف ذاتيًا على http://localhost:4318.

أما لاستيعاب البيانات في ClickStack Cloud أو HyperDX Cloud، فافتح HyperDX وانتقل إلى Team Settings → مفاتيح واجهة برمجة التطبيقات، ثم انسخ مفتاح واجهة برمجة التطبيقات للاستيعاب الخاص بك.

تهيئة الإضافة

انقر على أيقونة HyperDX Browser Extension في شريط أدوات Chrome واملأ الإعدادات التالية:

الحقل	مثال ClickStack محلي	ملاحظات
Enable HyperDX Monitoring	تشغيل	مفتاح التبديل الرئيسي للحقن
Service Name	my-frontend-app	مطلوب — يعرّف الخدمة في ClickStack
مفتاح واجهة برمجة التطبيقات	(فارغ)	مطلوب للاستيعاب السحابي؛ واختياري في بعض إعدادات الاستضافة الذاتية
Collector URL	http://localhost:4318	نقطة نهاية OTLP HTTP؛ والقيمة السحابية الافتراضية هي https://in-otel.hyperdx.io
Environment	development	اختياري — يضبط سمة المورد deployment.environment
Trace Propagation Targets	/api\.myapp\.domain/i, /localhost/i	اختياري — أنماط regex في JavaScript مفصولة بفواصل لنشر ترويسات التتبّع
Only inject on matching URLs	إيقاف	فعّله لحصر التهيئة بالمواقع المطابقة فقط
Capture console logs	إيقاف	فعّله لإرسال مخرجات console في المتصفح
Advanced network capture	إيقاف	فعّله لالتقاط طلبات الشبكة بتفاصيل إضافية

انقر على Save Configuration، ثم أعد تحميل أي علامات تبويب تريد تهيئتها.

توضح لقطة الشاشة أعلاه إعدادًا محليًا نموذجيًا: المراقبة مفعّلة، واسم الخدمة معيّن، وcollector موجّه إلى http://localhost:4318، ونشر التتبّع مقيّد بعناوين URL الخاصة بـ واجهة برمجة التطبيقات وlocalhost.

تصفّح موقعًا وأنشئ جلسة

افتح أي موقع ويب أو تطبيق محلي في Chrome — على سبيل المثال، http://localhost:3000 لخادم تطوير الواجهة الأمامية.

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

اعرض إعادة تشغيل الجلسة الخاصة بك

عُد إلى HyperDX على http://localhost:8080 وانتقل إلى Client Sessions من الشريط الجانبي الأيسر.

يُفترض أن تظهر جلستك في القائمة مع مدتها وعدد الأحداث فيها. انقر على الزر ▶️ لإعادة تشغيلها.

بدّل بين وضعي Highlighted وAll Events لضبط مستوى التفاصيل في المخطط الزمني.

بشكل افتراضي، تُدرِج الإضافة حزمة SDK في كل صفحة تزورها ما دامت المراقبة مفعّلة. لقصر الحقن على مواقع محددة، فعِّل الحقن فقط في عناوين URL المطابقة وأضف نمطًا واحدًا في كل سطر (أو افصل بينها بفواصل):

أعِد تحميل علامة التبويب بعد حفظ أنماط عناوين URL.

افتح أدوات المطوّر على صفحة قيد المراقبة (علامة تبويب Console)، ثم أعد تحميل الصفحة وابحث عن:

[HyperDX Extension] Configuration valid, injecting HyperDX
[HyperDX Extension] Injected via extension scripts
[HyperDX Extension] HyperDX initialized

إذا حظر CSP البرامج النصية الصادرة عن الإضافة، تسجّل الإضافة رسالة تفيد بالرجوع إلى مسار بديل ثم تعيد المحاولة باستخدام الحقن المضمّن.

تحقن الإضافة شيفرة الرصد في الصفحات التي تزورها. استخدمها فقط على المواقع المصرّح لك بتصحيح أخطائها. لا تشارك مفاتيح واجهة برمجة التطبيقات ولا تُضمّنها في نظام التحكّم بالإصدارات.

• إعادة تشغيل الجلسة — نظرة عامة على الميزة، وخيارات SDK، وضوابط الخصوصية
• Browser SDK Reference — جميع خيارات SDK والإعدادات المتقدمة
• إعادة تشغيل الجلسة Demo — جهّز تطبيقًا تجريبيًا انطلاقًا من الشيفرة المصدرية
• ClickStack Getting Started — انشر ClickStack وأدخِل أولى بياناتك
• إضافة HyperDX Chrome on GitHub — الشيفرة المصدرية ومتتبّع المشكلات