هيّئ تطبيقًا باستخدام Managed ClickStack

دليل لتهيئة تطبيق Node.js باستخدام OpenTelemetry وإرسال السجلات والمقاييس والتتبعات إلى Managed ClickStack

يوضح هذا الدليل كيفية إضافة OpenTelemetry إلى تطبيق Node.js بسيط وإرسال سجلاته ومقاييسه وتتبعاته إلى Managed ClickStack. جرى تضمين القياس في الواجهة الخلفية من دون أي تغييرات على الشفرة المصدرية للتطبيق.

يُعد HackerNews Analyzer تطبيق Node.js صغيرًا ينفّذ استعلامات على مجموعة بيانات HackerNews المستضافة على مثيل ClickHouse التجريبي العام. ويستند كل مخطط وجدول ومربع بحث إلى استعلام ClickHouse حقيقي، لذا ينتج عن كل تفاعل تتبّع يكون فيه الـspan الرئيسي هو استدعاء HTTPS الصادر من الواجهة الخلفية إلى ClickHouse.

المتطلبات الأساسية

• توفُّر OTel collector وإمكانية الوصول إليه، على أن يكون مُعدًّا لإرسال البيانات إلى خدمة Managed ClickStack لديك. ستحتاج إلى نقطة نهاية OTLP الخاصة به ورمز مميز للاستيعاب.
• Node 18+ و npm.

1. استنساخ التطبيق وتشغيله

   استنسخ المستودع، وثبّت التبعيات، وأنشئ ملف .env:

   git clone https://github.com/ClickHouse/hn-news-analyzer.git
   cd hn-news-analyzer
   npm install
   cp .env.example .env
   

   يتصل مصدر بيانات ClickHouse افتراضيًا بالعُنقود التجريبي العام المخصّص للقراءة فقط، لذا يعمل التطبيق دون أي إعداد إضافي. ابدأه:

   ./run.sh
   

   افتح http://localhost:5001. سترى محدِّد السنة، وإحصاءات موجزة، ومخططًا للنشاط، وجدولي أهم المستخدمين والنطاقات، ومربع بحث. جرّب التنقّل: بدّل بين السنوات، وتعمّق في القصص.

   في هذه المرحلة، يكون التطبيق قيد التشغيل لكنه غير مُهيّأ لجمع بيانات الرصد. لا يعرض ClickStack أي بيانات، إذ إنه ينتظر بيانات القياس عن بُعد. هذه هي حالة “قبل”.

2. احصل على تفاصيل الاتصال

   يحتاج التطبيق إلى قيمتين للوصول إلى المجمّع:

   • OTEL_EXPORTER_OTLP_ENDPOINT: نقطة نهاية OTLP التي يتيحها المجمّع لديك (وغالبًا ما تكون على المنفذ 4318 لـ OTLP عبر HTTP).
   • OTEL_EXPORTER_OTLP_HEADERS: ترويسة التفويض التي تتضمن رمز الاستيعاب الخاص بك، بالصيغة authorization=<token>.

   افتح .env واضبطهما:

   OTEL_SERVICE_NAME=hn-analyzer-api
   OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-collector-endpoint>:4318
   OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
   

   تستخدم حزمة SDK المتغير OTEL_EXPORTER_OTLP_HEADERS لضبط ترويسة التفويض لجميع الإشارات الثلاث: التتبعات والمقاييس والسجلات. إذا كان المُجمِّع يعمل محليًا ولا يفرض المصادقة، فيمكنك ترك القيمة فارغة (OTEL_EXPORTER_OTLP_HEADERS=authorization=)، لكن يجب أن يكون المتغير موجودًا؛ إذ تتجاوز حزمة SDK التهيئة بالكامل إذا لم يكن مضبوطًا أو كان فارغًا تمامًا.

3. أضِف أدوات القياس عن بُعد إلى التطبيق

   تتضمن عملية إضافة القياس عن بُعد ثلاثة أجزاء: تثبيت SDKs، وتبديل أمر التشغيل، وتمكين Browser SDK. ولا يغيّر أيٌّ من ذلك منطق العمل في التطبيق.

   تثبيت SDKs

   ثبّت OpenTelemetry SDKs لكلٍ من الواجهة الخلفية والمتصفح:

   npm install @hyperdx/node-opentelemetry @hyperdx/browser
   

   استخدم CLI الخاص بـ opentelemetry-instrument

   يُشغَّل التطبيق بواسطة run.sh، والذي يحتوي في أسفله على سطرَي exec: أحدهما نشط والآخر مُعلَّق. بدّل السطر النشط بحيث يتم تشغيل Node عبر opentelemetry-instrument:

    # BEFORE: plain node, no instrumentation, collector stays silent:
   -exec node scripts/entrypoint.js
   +# exec node scripts/entrypoint.js
   
    # AFTER: same source, wrapped by opentelemetry-instrument CLI.
   -# exec npx opentelemetry-instrument scripts/entrypoint.js
   +exec npx opentelemetry-instrument scripts/entrypoint.js
   

   هذا هو التغيير الكامل في الـbackend. يتم تحميل auto-instrumentation بواسطة opentelemetry-instrument عند بدء العملية.

   فعِّل Browser SDK

   لالتقاط التتبعات الموزعة (من المتصفح إلى الـbackend) وميزة إعادة تشغيل الجلسات، فعِّل Browser SDK في src/web/telemetry.ts. أزل التعليق عن سطر الاستيراد وكتلة HyperDX.init({...}):

   import HyperDX from '@hyperdx/browser';
   
   export function initTelemetry(): void {
     HyperDX.init({
       url: __OTLP_ENDPOINT__,
       apiKey: __OTLP_AUTH_TOKEN__,
       service: 'hn-analyzer-web',
       tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
       consoleCapture: true,
       advancedNetworkCapture: true,
     });
   }
   

   لا حاجة إلى أي تعديلات إضافية على .env. يمثّل __OTLP_ENDPOINT__ و__OTLP_AUTH_TOKEN__ ثابتين لوقت الترجمة يُدرجهما vite.config.ts: نقطة النهاية هي OTEL_EXPORTER_OTLP_ENDPOINT، ويُستخرج الرمز المميّز من OTEL_EXPORTER_OTLP_HEADERS، وهما القيمتان نفسيهما اللتان تستخدمهما الواجهة الخلفية.

   يكون رمز الإدخال مضمّنًا في حزمة المتصفح العامة، ويمكن لأي شخص قراءته عند فحص تبويب Network.

4. أنشئ حركة مرور واعرض بيانات القياس عن بُعد

   أعِد تشغيل التطبيق حتى يدخل أمر التشغيل الجديد وحزمة المتصفح المنشأة حديثًا حيّز التنفيذ:

   # Ctrl-C the previous run, then:
   ./run.sh
   

   أعِد تحميل علامة تبويب المتصفح لكي يقدّم Vite الحزمة المحدَّثة، ثم حدِّث التطبيق بضع مرات، وبدّل بين السنوات، وانقر للدخول إلى المشاركات لتوليد بعض الزيارات.

   افتح واجهة ClickStack:

   1. انتقل إلى Search وصفِّ النتائج لآخر 5 دقائق. ستبدأ سجلات hn-analyzer-api بالظهور تباعًا.

   2. انقر على أحد الطلبات ثم تنقّل صعودًا عبر التتبّع. سترى مقطع التتبّع (span) الخاص بمعالج Express، ومقطع HTTP فرعيًا يشير إلى عنقود ClickHouse مع مدة الشبكة الفعلية، وسجلات console.log مرتبطة على التتبّع نفسه.

   3. افتح Session Replay لتشغيل فيديو يمكنك التنقّل خلاله لجلسة في المتصفح، متزامنًا مع المخطط الزمني للتتبّع.

   تظهر السجلات والمقاييس والتتبعات وإعادات تشغيل الجلسات كلها في الواجهة نفسها، وتستخدم لغة الاستعلام نفسها، وترتبط تلقائيًا ببعضها بعضًا.

تعرّف على المزيد

• Session Replay: نظرة عامة على الميزة، وخيارات SDK، وعناصر التحكّم في الخصوصية.
• Session Replay Demo: عرض توضيحي مستقل مع مثيل ClickStack محلي.
• البدء مع ClickStack: انشر ClickStack وأدخِل أولى بياناتك.
• كل مجموعات البيانات التجريبية: مجموعات بيانات تجريبية وأدلة أخرى.