عرض توضيحي لـ HackerNews Analyzer

باختصاراستنسخ HackerNews Analyzer، واملأ ملف .env بنقطة نهاية OTLP والرمز المميز الخاصين بك، ثم ألصق توجيه agent. لا تحتاج الواجهة الخلفية إلى أي عمليات استيراد لـ OpenTelemetry؛ إذ يوصّل agent الحزمة @hyperdx/node-opentelemetry عند بدء العملية.الوقت المطلوب: نحو 10 دقائق

HackerNews Analyzer هو تطبيق Node.js يستعلم عن مجموعة بيانات HackerNews المستضافة في العرض التجريبي العام لـ ClickHouse. كل مخطط وجدول ومربع بحث هو استعلام ClickHouse حقيقي، لذا ينتج كل تفاعل trace تكون الـ span الرئيسية فيه هي استدعاء HTTPS من الواجهة الخلفية إلى ClickHouse. هذه مهمة مختلفة عن العرض التجريبي لإعادة تشغيل الجلسة، الذي يضيف instrumentation إلى تطبيق يعمل في المتصفح فقط باستخدام ClickStack محلي عبر Docker. هنا تحصل على auto-instrumentation للواجهة الخلفية، وspans لاستعلامات ClickHouse، وإعادة تشغيل الجلسة من التطبيق نفسه.

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

Node 18+ وnpm
نقطة نهاية لـ ClickStack OTLP/HTTP ورمز مميز للاستيعاب:
- ClickHouse Cloud: افتح الخدمة، ثم ClickStack → تهيئة exporter لـ OpenTelemetry → متغيرات البيئة. البروتوكول هو http/protobuf. تكون headers بالشكل authorization=<ingestion token>، من دون بادئة Bearer.
- collector محلي: استخدم http://localhost:4318. إذا كان collector غير مؤمَّن، فاترك authorization= فارغًا.

استنسخ المستودع

استنسخ HackerNews Analyzer، وثبّت التبعيات، وانسخ قالب ملف البيئة:

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

ستملأ ملف .env في الخطوات التالية، ثم جهّز التطبيق لإرسال بيانات التتبّع من هذا الدليل.

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

شغّل التطبيق

من الدليل المستنسخ hn-news-analyzer، شغّل التطبيق. يتصل مصدر بيانات ClickHouse افتراضيًا بالعنقود التجريبي العام للقراءة فقط، لذا يعمل دون الحاجة إلى أي إعداد إضافي:

./run.sh

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

في هذه المرحلة، يكون التطبيق قيد التشغيل لكنه غير مزوَّد بأدوات التتبّع. لا يعرض ClickStack أي بيانات، إذ ينتظر بيانات التتبّع.

تهيئة البيئة

تقرأ حِزم SDK متغيرات exporter القياسية لـ OpenTelemetry. وهي غير مُضمَّنة برمجيًا في شيفرة المصدر. افتح .env واضبط:

OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=<your-otlp-http-endpoint>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=<your-ingestion-token>
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp

OTEL_EXPORTER_OTLP_ENDPOINT هي نقطة نهاية OTLP/HTTP (المنفذ 4318). وOTEL_EXPORTER_OTLP_HEADERS هو رأس التفويض، بالصيغة authorization=<token> من دون بادئة Bearer.إذا لم يفرض الجامع مصادقة، فاترك الرمز فارغًا (OTEL_EXPORTER_OTLP_HEADERS=authorization=). يجب أن يبقى المتغير موجودًا؛ إذ تتخطى حزمة SDK التهيئة إذا لم يكن معيّنًا أو كان فارغًا بالكامل.تعيد Browser SDK استخدام هذه القيم نفسها. يضمّن vite.config.ts نقطة النهاية والرمز في الحزمة العامة وقت البناء، لذا استخدم رمز استيعاب مؤقتًا، وليس رمزًا مخصصًا للإنتاج.

زوّد التطبيق بأدوات القياس عن بُعد

اختر مسارًا واحدًا. تنتهي المسارات الثلاثة بالتطبيق نفسه المزوّد بأدوات القياس.

إضافة أدوات القياس باستخدام agent
إضافة أدوات القياس يدويًا
استخدم فرعًا مجهزًا مسبقًا بأدوات القياس

بعد استنساخ المستودع وتعبئة ملف .env، الصق هذا الـprompt في agent برمجي من داخل ذلك الدليل لإضافة أدوات القياس إلى التطبيق.

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

تثبيت Node SDK

npm install @hyperdx/node-opentelemetry

تفعيل wrapper في run.sh

يوجد سطرا exec في نهاية run.sh. علّق سطر node العادي وأزل التعليق عن السطر المزوّد بأدوات القياس:

 # قبل: node عادي، بلا أدوات قياس:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js

 # بعد: المصدر نفسه، مُغلّف بواسطة opentelemetry-instrument:
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js

استمر في التشغيل عبر scripts/entrypoint.js. يستدعي هذا البرنامج الوسيط require('console') حتى يلتف التقاط console حول console.log. يؤدي توجيه opentelemetry-instrument مباشرةً إلى dist/server/index.js إلى إرسال traces، لكنه يُسقط logs بصمت.

تفعيل Browser SDK

npm install @hyperdx/browser

في src/web/telemetry.ts، أزل التعليق عن سطر الاستيراد وكتلة HyperDX.init({...}) وHyperDX.addAction في recordAction():

-// import HyperDX from '@hyperdx/browser';
+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,
-  // });
+  HyperDX.init({
+    url: __OTLP_ENDPOINT__,
+    apiKey: __OTLP_AUTH_TOKEN__,
+    service: 'hn-analyzer-web',
+    tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
+    consoleCapture: true,
+    advancedNetworkCapture: true,
+  });
 }

إن __OTLP_ENDPOINT__ و__OTLP_AUTH_TOKEN__ ثوابت وقت الترجمة البرمجية، ويحقنها vite.config.ts من قيم OTEL_EXPORTER_OTLP_* نفسها التي تستخدمها الواجهة الخلفية.

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

لتجاوز إضافة أدوات القياس والبدء بتطبيق مجهز بها مسبقًا، نفّذ checkout لفرع instrumented.

git checkout instrumented
npm install

لا تشغّل ./reset.sh على هذا الفرع إلا إذا أردت إزالة SDKs.

أنشئ حركة مرور واعرض بيانات التتبّع

أعد تشغيل التطبيق لتفعيل أمر التشغيل الجديد وحزمة المتصفح التي أُنشئت حديثًا:

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

تأكد من أن رسالة بدء التشغيل تطبع ثلاثة أسطر «Health check passed» لـ /v1/traces و/v1/metrics و/v1/logs. أعد تحميل علامة تبويب المتصفح لكي يقدّم Vite الحزمة المحدّثة، ثم بدّل بين السنوات وانقر على القصص لإنشاء حركة مرور.افتح واجهة مستخدم ClickStack:

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

بحث ClickStack يعرض سجلات hn-analyzer-api من آخر خمس دقائق

انقر على طلب وتتبّع الـ trace صعودًا. سترى span لمعالج Express، وspan HTTP تابعًا يشير إلى sql-clickhouse.clickhouse.com مع مدة شبكة فعلية، وسجلات console.log مرتبطة بالـ trace نفسه.

trace في ClickStack يتضمن span لمعالج Express وspan HTTP تابعًا إلى ClickHouse

افتح Session Replay لتشغيل فيديو قابل للتمرير لجلسة متصفح، متزامن مع المخطط الزمني للـ trace.

إعادة تشغيل جلسة ClickStack متزامنة مع المخطط الزمني للـ trace

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

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

HackerNews Analyzer: المستودع التجريبي الذي يوضّح هذا الدليل كيفية تزويده بأدوات القياس.
إعادة تشغيل الجلسة: نظرة عامة على الميزة، وخيارات SDK، وعناصر التحكّم في الخصوصية.
عرض توضيحي لإعادة تشغيل الجلسة: عرض توضيحي مستقل مع مثيل ClickStack محلي.
البدء مع ClickStack: انشر ClickStack وأدخِل أولى بياناتك.
كل مجموعات البيانات التجريبية: مجموعات بيانات تجريبية وأدلة أخرى.

بدء الاستخدام

الميزات

إدارة ClickStack

أدلة إرشادية

شركاء التكامل

عرض توضيحي لـ HackerNews Analyzer

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

استنسخ المستودع

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

تثبيت Node SDK

تفعيل wrapper في run.sh

تفعيل Browser SDK

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

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

​استنسخ المستودع

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

​تثبيت Node SDK

​تفعيل wrapper في run.sh

​تفعيل Browser SDK

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

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

استنسخ المستودع

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

تثبيت Node SDK

تفعيل wrapper في run.sh

تفعيل Browser SDK

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