JavaScript للمتصفح

Browser SDK لـ ClickStack - حزمة Observability من ClickHouse

يتيح لك Browser SDK الخاص بـ ClickStack تضمين أدوات الرصد في تطبيق الواجهة الأمامية لديك لإرسال الأحداث إلى ClickStack. وهذا يتيح لك عرض طلبات الشبكة والاستثناءات إلى جانب أحداث الواجهة الخلفية ضمن خط زمني واحد.

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

يدمج هذا الدليل ما يلي:

• سجلات وحدة التحكم
• إعادات تشغيل الجلسات
• طلبات XHR/Fetch/Websocket
• الاستثناءات

​

البدء

استيراد الحزمة

ثبّت عبر استيراد الحزمة (موصى به)

استخدم الأمر التالي لتثبيت حزمة المتصفح.

npm install @hyperdx/browser

أعِدّ ClickStack

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //احذفها عند استخدام Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // حدّده لربط التتبعات من الواجهة الأمامية بطلبات الواجهة الخلفية
    consoleCapture: true, // التقاط سجلات وحدة التحكّم (القيمة الافتراضية false)
    advancedNetworkCapture: true, // التقاط الرؤوس والمحتوى الكامل لطلبات HTTP واستجاباته (القيمة الافتراضية false)
});

وسم Script

ثبّت عبر وسم Script (بديل)

يمكنك أيضًا تضمين البرنامج النصي وتثبيته عبر وسم script بدلًا من التثبيت عبر NPM. سيؤدي ذلك إلى إتاحة المتغير العام HyperDX، ويمكن استخدامه بالطريقة نفسها المستخدمة مع حزمة NPM.

يُنصح بهذا إذا كان موقعك لا يُبنى حاليًا باستخدام أداة تجميع.

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //احذفها عند استخدام Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // حدّده لربط التتبعات من الواجهة الأمامية بطلبات الواجهة الخلفية
  });
</script>

​

الخيارات

• apiKey - مفتاح واجهة برمجة تطبيقات للإدخال الخاص بك في ClickStack.
• service - اسم الخدمة الذي ستظهر به الأحداث في واجهة مستخدم HyperDX.
• tracePropagationTargets - قائمة بأنماط Regex لمطابقتها مع طلبات HTTP لربط تتبعات الواجهة الأمامية والخلفية، وسيضيف ذلك ترويسة traceparent إضافية إلى جميع الطلبات التي تطابق أيًا من الأنماط. يجب ضبط هذا على نطاق واجهة برمجة تطبيقات للواجهة الخلفية لديك (مثلًا api.yoursite.com).
• consoleCapture - (اختياري) التقاط جميع سجلات وحدة التحكّم (القيمة الافتراضية false).
• advancedNetworkCapture - (اختياري) التقاط رؤوس الطلبات/الاستجابات كاملةً والأجسام (القيمة الافتراضية false).
• url - (اختياري) عنوان URL لـ OpenTelemetry Collector، وهو مطلوب فقط للمثيلات المستضافة ذاتيًا.
• maskAllInputs - (اختياري) ما إذا كان يجب إخفاء جميع حقول الإدخال في إعادة تشغيل الجلسة (القيمة الافتراضية false).
• maskAllText - (اختياري) ما إذا كان يجب إخفاء كل النصوص في إعادة تشغيل الجلسة (القيمة الافتراضية false).
• disableIntercom - (اختياري) ما إذا كان يجب تعطيل تكامل Intercom (القيمة الافتراضية false)
• disableReplay - (اختياري) ما إذا كان يجب تعطيل إعادة تشغيل الجلسة (القيمة الافتراضية false)

​

تهيئة إضافية

​

إرفاق معلومات المستخدم أو البيانات الوصفية

سيتيح لك إرفاق معلومات المستخدم البحث في الجلسات والأحداث وتصفيتها في واجهة مستخدم HyperDX. يمكن استدعاء ذلك في أي وقت أثناء جلسة العميل. وسترتبط جلسة العميل الحالية وجميع الأحداث المُرسلة بعد هذا الاستدعاء بمعلومات المستخدم.

ستملأ userEmail وuserName وteamName واجهة الجلسات بالقيم المقابلة، ولكن يمكن حذفها. ويمكن أيضًا تحديد أي قيم إضافية واستخدامها للبحث عن الأحداث.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Other custom properties...
});

​

الالتقاط التلقائي لأخطاء حدود الأخطاء في React

إذا كنت تستخدم React، فيمكنك تلقائيًا التقاط الأخطاء التي تحدث داخل حدود الأخطاء في React من خلال تمرير مكوّن حدّ الأخطاء الخاص بك إلى الدالة attachToReactErrorBoundary.

// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';

// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

​

إرسال الإجراءات المخصّصة

لتتبّع حدث معيّن في التطبيق بشكل صريح (مثل التسجيل أو الإرسال وغير ذلك)، يمكنك استدعاء الدالة addAction مع اسم الحدث وبيانات وصفية اختيارية له.

مثال:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

​

تفعيل التقاط حركة الشبكة ديناميكيًا

لتفعيل أو تعطيل التقاط حركة الشبكة ديناميكيًا، ما عليك سوى استدعاء الدالة enableAdvancedNetworkCapture أو disableAdvancedNetworkCapture حسب الحاجة.

HyperDX.enableAdvancedNetworkCapture();

​

تفعيل توقيت الموارد لطلبات CORS

إذا كان تطبيق الواجهة الأمامية لديك يُجري طلبات إلى واجهة برمجة تطبيقات على نطاق مختلف، فيمكنك اختياريًا تفعيل إرسال ترويسة Timing-Allow-Originheader مع الطلب. يتيح ذلك لـ ClickStack التقاط معلومات دقيقة عن توقيت الموارد للطلب، مثل استعلام DNS وتنزيل الاستجابة وغير ذلك، عبر PerformanceResourceTiming.

إذا كنت تستخدم express مع حزم cors، فيمكنك استخدام المقتطف التالي لتفعيل الترويسة:

var cors = require('cors');
var onHeaders = require('on-headers');

// ... all your stuff

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());