سجلات وآثار تتبع ومقاييس نموذجية

البدء مع ClickStack ومجموعة بيانات نموذجية تتضمن السجلات والجلسات وآثار التتبع والمقاييس

يستعرض هذا الدليل كلاً من ClickStack Open Source وManaged ClickStack باستخدام عينة من البيانات.

ClickStack المُدار

يفترض هذا الدليل أنك أكملت دليل البدء الخاص بـ Managed ClickStack وقمت بتدوين بيانات اعتماد الاتصال.

1. ​

   اختر الخدمة

   اختر الخدمة التي تحمل علامة Managed ClickStack من صفحة ClickHouse Cloud الرئيسية.

2. ​

   انتقل إلى ClickStack UI (HyperDX)

   اختر ClickStack من القائمة اليسرى للانتقال إلى ClickStack UI، حيث سيتم تسجيل دخولك تلقائيًا.

3. ​

   تنزيل بيانات تجريبية

   لتعبئة واجهة المستخدم ببيانات تجريبية، نزّل الملف التالي:

   بيانات تجريبية

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # or
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   يحتوي هذا الملف على أمثلة على السجلات والمقاييس والتتبعات من OpenTelemetry demo المتاح للعامة - وهو متجر تجارة إلكترونية بسيط قائم على الخدمات المصغّرة. انسخ هذا الملف إلى الدليل الذي تختاره.

4. ​

   تحميل بيانات تجريبية

   لتحميل هذه البيانات، نرسلها ببساطة إلى نقطة نهاية HTTP الخاصة بـ OTel collector الذي تم نشره.

   شغّل الأمر التالي لإرسال البيانات إلى OTel collector:

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   يحاكي هذا مصادر OTLP للسجلات والتتبعات والمقاييس التي ترسل البيانات إلى OTel collector. في بيئة الإنتاج، قد تكون هذه المصادر مكتبات العملاء للغات البرمجة، أو حتى OTel collectors أخرى.

   بالعودة إلى عرض Search، ينبغي أن ترى أن البيانات قد بدأت بالتحميل (اضبط الإطار الزمني على Last 1 hour إذا لم تظهر البيانات):

   قد يستغرق تحميل البيانات بضع دقائق. انتظر حتى يكتمل التحميل قبل المتابعة إلى الخطوات التالية.

5. ​

   استكشاف الجلسات

   لنفترض أننا تلقّينا بلاغات تفيد بأن مستخدمينا يواجهون مشكلات عند الدفع مقابل السلع. يمكننا الاطّلاع على تجربتهم باستخدام إمكانات إعادة تشغيل الجلسات في HyperDX.

   حدّد Client Sessions من القائمة اليسرى.

   يتيح لنا هذا العرض رؤية جلسات الواجهة الأمامية لمتجرنا الإلكتروني. وتظل الجلسات مجهولة الهوية إلى أن يبدأ المستخدمون إتمام الشراء ويحاولوا إكمال الدفع.

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

   حدّد trace يتضمّن حالة فشل وبريدًا إلكترونيًا مرتبطًا. يتيح لنا العرض التالي إعادة تشغيل جلسة المستخدم ومراجعة مشكلته. اضغط على play لمشاهدة الجلسة.

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

   تُعلَّم أي أخطاء على المخطط الزمني باللون الأحمر.

   لم يتمكن المستخدم من إتمام الطلب من دون ظهور خطأ واضح. مرّر إلى أسفل اللوحة اليسرى التي تحتوي على أحداث الشبكة ووحدة التحكّم من متصفح المستخدم. ستلاحظ ظهور خطأ 500 عند إجراء استدعاء /api/checkout.

   حدّد هذا الخطأ 500. لا يشير كلٌّ من Overview وColumn Values إلى مصدر المشكلة، سوى أن الخطأ غير متوقَّع، ما يؤدي إلى Internal Error.

6. ​

   استكشاف التتبعات

   انتقل إلى علامة التبويب Trace لرؤية التتبّع الموزّع الكامل.

   مرّر إلى أسفل التتبّع لرؤية مصدر الخطأ، وهو امتداد خدمة checkout. حدّد امتداد خدمة Payment.

   حدّد علامة التبويب Column Values ومرّر إلى الأسفل. يمكننا أن نرى أن المشكلة مرتبطة بامتلاء ذاكرة التخزين المؤقت.

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

   تبيّن لنا أن ذاكرة التخزين المؤقت تمتلئ في خدمة الدفع، وهذا يمنع اكتمال عمليات الدفع.

7. ​

   استكشاف السجلات

   للمزيد من التفاصيل، يمكننا الرجوع إلى Search:

   حدِّد Logs من المصادر وطبِّق عامل تصفية على خدمة payment.

   يمكننا أن نرى أنه رغم أن المشكلة حديثة، فإن عدد المدفوعات المتأثرة مرتفع. علاوة على ذلك، يبدو أن ذاكرة تخزين مؤقت مرتبطة بمدفوعات Visa هي سبب هذه المشكلات.

8. ​

   مقاييس المخطط

   رغم أنه تم بوضوح إدخال خطأ في الشيفرة، يمكننا استخدام المقاييس للتحقق من حجم ذاكرة التخزين المؤقت. انتقل إلى عرض Chart Explorer.

   حدّد Metrics كمصدر البيانات. أكمل إعدادات منشئ المخطط لرسم Maximum لـ visa_validation_cache.size (Gauge) ثم اضغط زر play. كان حجم ذاكرة التخزين المؤقت يزداد بوضوح حتى بلغ الحد الأقصى، وبعد ذلك بدأت الأخطاء بالظهور.

ClickStack مفتوح المصدر

يفترض المثال التالي أنك قد شغّلت Open Source ClickStack باتباع تعليمات الصورة الشاملة وأنك اتصلت بـ نسخة ClickHouse المحلية.

1. ​

   انتقِل إلى واجهة ClickStack ‏(HyperDX)

   زُر http://localhost:8080 للوصول إلى واجهة ClickStack.

2. ​

   انسخ مفتاح API للإدخال

   انتقل إلى إعدادات الفريق وانسخ Ingestion API Key من قسم API Keys. يضمن مفتاح API هذا تأمين إدخال البيانات عبر مجمّع OpenTelemetry.

3. ​

   تنزيل بيانات نموذجية

   لكي تظهر بيانات نموذجية في واجهة المستخدم، نزّل الملف التالي:

   بيانات نموذجية

   # curl
   curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
   # or
   # wget https://storage.googleapis.com/hyperdx/sample.tar.gz
   

   يحتوي هذا الملف على سجلات ومقاييس وتتبعات تجريبية من تطبيق OpenTelemetry demo العام لدينا، وهو متجر تجارة إلكترونية بسيط قائم على الخدمات المصغّرة. انسخ هذا الملف إلى الدليل الذي تختاره.

4. ​

   تحميل بيانات تجريبية

   لتحميل هذه البيانات، ما علينا سوى إرسالها إلى نقطة نهاية HTTP الخاصة بجامع OpenTelemetry ‏(OTel) الذي تم نشره.

   أولاً، صدّر مفتاح API الذي نسخته أعلاه.

   # export API key
   export CLICKSTACK_API_KEY=<YOUR_INGESTION_API_KEY>
   

   نفّذ الأمر التالي لإرسال البيانات إلى OTel collector:

   for filename in $(tar -tf sample.tar.gz); do
     endpoint="http://localhost:4318/v1/${filename%.json}"
     echo "loading ${filename%.json}"
     tar -xOf sample.tar.gz "$filename" | while read -r line; do
       printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
       -H "Content-Type: application/json" \
       -H "authorization: ${CLICKSTACK_API_KEY}" \
       --data-binary @-
     done
   done
   

   يحاكي هذا مصادر السجلات والتتبعات والمقاييس عبر OTLP وهي ترسل البيانات إلى OTel collector. في بيئة الإنتاج، قد تكون هذه المصادر مكتبات العملاء للغات البرمجة أو حتى OTel collectors أخرى.

   بالعودة إلى عرض Search، ينبغي أن ترى أن تحميل البيانات قد بدأ (اضبط النطاق الزمني على Last 1 hour إذا لم تظهر البيانات):

   سيستغرق تحميل البيانات بضع دقائق. انتظر حتى يكتمل التحميل قبل الانتقال إلى الخطوات التالية.

5. ​

   استكشاف الجلسات

   لنفترض أن لدينا تقارير تفيد بأن مستخدمينا يواجهون مشكلات عند الدفع مقابل السلع. يمكننا عرض تجربتهم باستخدام ميزة session replay في HyperDX.

   حدِّد Client Sessions من القائمة اليمنى.

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

   لاحظ أن بعض الجلسات المرتبطة بعناوين بريد إلكتروني تتضمن error مرتبطًا بها، ما قد يؤكد التقارير عن المعاملات الفاشلة.

   حدِّد trace يتضمن فشلًا وعنوان بريد إلكتروني مرتبطًا. يتيح لنا العرض التالي إعادة تشغيل جلسة المستخدم ومراجعة مشكلته. اضغط على play لمشاهدة الجلسة.

   تُظهر الإعادة المستخدم وهو يتنقل في الموقع ويضيف عناصر إلى سلته. يمكنك الانتقال إلى جزء لاحق من الجلسة حيث يحاول إكمال عملية الدفع.

   يتم تمييز أي أخطاء على المخطط الزمني باللون الأحمر.

   لم يتمكن المستخدم من إتمام الطلب، من دون ظهور خطأ واضح. مرّر إلى أسفل اللوحة اليسرى التي تعرض أحداث الشبكة ووحدة التحكم من متصفح المستخدم. ستلاحظ أنه تم طرح خطأ 500 عند إجراء استدعاء /api/checkout.

   حدِّد هذا الخطأ 500. لا يوضح كلٌّ من Overview وColumn Values مصدر المشكلة، باستثناء أن الخطأ غير متوقع، مما يؤدي إلى Internal Error.

6. ​

   استكشاف التتبعات

   انتقل إلى علامة التبويب Trace لرؤية التتبّع الموزّع بالكامل.

   مرّر إلى أسفل التتبّع لرؤية مصدر الخطأ، وهو span خدمة checkout. حدِّد span خدمة Payment.

   حدِّد علامة التبويب Column Values ومرّر إلى الأسفل. يمكننا أن نرى أن المشكلة مرتبطة بامتلاء الذاكرة المؤقتة.

   عند التمرير للأعلى والعودة إلى التتبّع، يمكننا أن نرى أن السجلات مرتبطة بـ span، وذلك بفضل الإعداد الذي أجريناه سابقًا. وهذا يوفّر سياقًا إضافيًا.

   لقد تبيّن لنا أن الذاكرة المؤقتة تمتلئ في خدمة الدفع، مما يمنع اكتمال عمليات الدفع.

7. ​

   استكشاف السجلات

   لمزيد من التفاصيل، يمكننا العودة إلى عرض Search:

   حدِّد Logs من المصادر، ثم طبّق عامل تصفية على خدمة payment.

   يمكننا أن نرى أنه رغم حداثة المشكلة، فإن عدد عمليات الدفع المتأثرة كبير. علاوةً على ذلك، يبدو أن ذاكرة تخزين مؤقت مرتبطة بمدفوعات Visa تتسبب في هذه المشكلات.

8. ​

   مقاييس المخطط

   رغم أنه أُدخل خطأ بوضوح في الشيفرة، يمكننا استخدام المقاييس للتأكد من حجم ذاكرة التخزين المؤقت. انتقل إلى عرض Chart Explorer.

   حدّد Metrics كمصدر للبيانات. أكمل أداة إنشاء المخططات لرسم Maximum لـ visa_validation_cache.size (Gauge)، ثم اضغط زر play. من الواضح أن ذاكرة التخزين المؤقت كانت تزداد قبل أن تصل إلى حجمها الأقصى، وبعد ذلك بدأت الأخطاء بالظهور.