آثار OpenTelemetry من المتصفح

تتكوّن OpenTelemetry JavaScript SDK للمتصفحات من عدة حزم: توفر @opentelemetry/sdk-trace-web التنفيذ الأساسي لتتبّع الآثار، وتنشئ @opentelemetry/instrumentation-fetch مقاطع تلقائيًا لجميع استدعاءات Fetch API، بينما ترسل @opentelemetry/exporter-trace-otlp-http المقاطع إلى مُجمّع.

يُعد TracerProvider كائن الإعداد المركزي في OpenTelemetry. وهو يحتفظ بقائمة SpanProcessors، التي تحدد ما يحدث للمقاطع المكتملة، وبالمورد الذي يصف تطبيقك، مثل اسم الخدمة وإصدارها، وبأي إعدادات لأخذ العينات.

يجمع BatchSpanProcessor المقاطع المكتملة في الذاكرة ويصدّرها على دفعات بدلًا من إرسال كل مقطع على حدة. ويقلل ذلك بدرجة كبيرة عدد طلبات HTTP إلى المُجمّع، مما يحسّن أداء المتصفح ويخفف الحمل على نقطة نهاية مُجمّع OTel.

يرسل OTLPTraceExporter المقاطع المجمّعة إلى مُجمّع متوافق مع OpenTelemetry عبر HTTP بتنسيق JSON أو protobuf. وتضبط عنوان URL للمُجمّع، مثل نقطة نهاية الوكيل الخاص بـ OTel Collector، بينما يتولى المُصدّر تلقائيًا منطق التسلسل وإعادة المحاولة.

يمثل Span وحدة عمل واحدة ضمن أثر: تركيب مكوّن، أو استدعاء API، أو تفاعل مستخدم. وللمقاطع اسم ووقت بدء ووقت انتهاء وحالة (OK أو ERROR) ومجموعة من السمات ذات المفتاح والقيمة. وترتبط المقاطع ذات الصلة من خلال trace ID مشترك وعلاقات الأصل والفرع.

تنشئ أداة تتبّع باستخدام provider.getTracer('react-app')، وتبدأ المقاطع باستخدام tracer.startSpan('component-mount'). وبعد اكتمال العمل، استدعِ span.end() لتسجيل وقت الانتهاء. احرص دائمًا على إنهاء المقاطع — فالمقاطع المتسربة تهدر الذاكرة وتنتج بيانات غير مكتملة في الواجهة الخلفية للرصد.

تثري السمات المقاطع ببيانات سياقية: span.setAttribute('user.id', userId) أو span.setAttribute('route', location.pathname). ويمكن البحث عن السمات في الواجهة الخلفية للرصد، مما يتيح استعلامات مثل "اعرض جميع المقاطع البطيئة للمستخدم 42" أو "اعرض جميع الأخطاء في المسار /checkout".

تعدّل @opentelemetry/instrumentation-fetch دالة fetch العامة لإضافة مقاطع تلقائيًا لكل طلب HTTP صادر. ويسجل المقطع URL والطريقة ورمز حالة HTTP والمدة، من دون إجراء أي تغييرات على استدعاءات fetch الحالية.

عندما تنشئ أداة fetch instrumentation كائن span لطلب صادر، فإنها تحقن ترويسة التتبّع traceparent الخاصة بـ W3C TraceContext في الطلب. تقرأ الواجهة الخلفية المستقبِلة هذه الترويسة وتتابع التتبّع نفسه، فتنشئ تتبّعًا مترابطًا يمتد بين المتصفح والخادم.

يجب أن تتم تهيئة OTel قبل تركيب أي مكوّنات — وعادةً ما يكون ذلك في ملف إدخال التطبيق (main.tsx) قبل استدعاء ReactDOM.createRoot. أنشئوا المزوّد، وسجّلوا المعالجات والمصدّرات، ثم استدعوا provider.register() لجعله TracerProvider العام.

يؤدي تسجيل كل تفاعل للمستخدم في التطبيقات ذات عدد الزيارات المرتفع إلى إنشاء كميات هائلة من بيانات التتبّع. اضبطوا أداة TraceIdRatioBased sampler (مثلًا، لأخذ عيّنة من 10% من عمليات التتبّع) في TracerProvider لتقليل الحجم. احرصوا دائمًا على أخذ عيّنة بنسبة 100% من عمليات التتبّع التي تتضمن أخطاءً، باستخدام أداة ParentBased sampler لضمان عدم فقدان أي خطأ.

لماذا يُستخدم BatchSpanProcessor بدلًا من SimpleSpanProcessor في تطبيقات المتصفح؟

تستخدم حزمة OpenTelemetry JavaScript SDK أدوات TracerProvider وBatchSpanProcessor وOTLPTraceExporter لإجراء instrumentation للمتصفحات. تمثّل spans وحدات العمل، وتُثرى بالسمات. تنشئ أداة fetch instrumentation تلقائيًا spans لاستدعاءات API، وتحقن ترويسات W3C TraceContext لإتاحة التتبّع الموزّع من البداية إلى النهاية. ابدأوا التهيئة مبكرًا، واضبطوا أخذ العينات بما يناسب، وأنهِوا spans دائمًا للحفاظ على بيانات تتبّع منظمة.