بنية span في OpenTelemetry: الحقول والقراءة بلغة DQL

بنية span في OpenTelemetry: المعرّفات والسمات والأحداث والروابط والحالة والنوع، ثم قراءتها باستخدام DQL في Dynatrace SaaS.
Anatomie d'un span OpenTelemetry : champs et lecture en DQL

مساء خميس في موسم التخفيضات، تعرض سلة التسوق في متجر إلكتروني صفحة بيضاء لبعض الزبائن. لوحة المعلومات خضراء ولم يصدر أي تنبيه، لكن التتبع المرفق بالتذكرة يُظهر استدعاءً واحدًا استغرق أربع ثوانٍ. لفهم ما جرى لا بد من معرفة بنية span في OpenTelemetry، فكل حقل يجيب عن سؤال محدد، وغياب الإجابة دليل بحد ذاته. يتتبع هذا الدرس الحالة حقلًا بعد حقل، ثم يعيد التحقيق بلغة DQL في Dynatrace SaaS.

النطاق هنا هو SaaS فقط، فوثائق DQL وGrail التي أعتمد عليها لا تصف Dynatrace Managed. وللدقة في ما جرى التحقق منه: لم أنفّذ أي استعلام. الـ span أدناه مختلق للتوضيح، والاستعلامات مأخوذة من الوثائق أو موسومة بعبارة «لم يُنفَّذ».

بنية span في OpenTelemetry: بطاقة التعريف

على الشبكة (بصيغة OTLP، في الملف trace.proto) لا يعدو الـ span أن يكون سجلًا من حقول مرقّمة قليلة. تلخّصه مواصفة واجهة التتبع هكذا: اسم، وسياق ثابت، وأب اختياري، ونوع، وطابعان زمنيان، وسمات، وروابط، وأحداث، وحالة. وهذا الجدول الذي أبقيه أمامي دائمًا.

الحقل في OTLP السؤال الذي يجيب عنه
trace_id (16 بايت، إلزامي) إلى أي قصة ينتمي هذا الـ span؟
span_id (8 بايت، إلزامي) أي واحد هو داخل تلك القصة؟
parent_span_id من استدعاه؟ فارغ في الجذر.
name (إلزامي) ماذا كان يفعل؟
kind في أي جانب من التبادل كان؟
start_time_unix_nano وend_time_unix_nano متى، بالنانوثانية منذ حقبة Unix؟
attributes في أي ظروف (المسار، الطريقة، المضيف)؟
events وlinks ماذا حدث في الطريق؟ وبمن كان مرتبطًا؟
status (code وmessage) كيف انتهى؟

تفصيلان في المواصفة يجنّبانك المفاجآت. يجب أن يحتوي كل معرّف على بايت واحد غير صفري على الأقل. ويحمل الـ span أيضًا الحقل trace_state (ترويسة W3C المسماة tracestate) وثلاثة عدّادات للعناصر المهمَلة: dropped_attributes_count وdropped_events_count وdropped_links_count. أي عدّاد غير صفري يعني أن حزمة SDK قصّت قصتها بنفسها.

المشتبه به: span السلة

هذا هو الـ span الذي تخيّلته للتذكرة بصيغة JSON الخاصة بـ OTLP. لهذا الترميز قواعده: المعرّفات بالنظام الست عشري، والأسماء بنمط lowerCamelCase، والتعدادات أعدادًا صحيحة، والأعداد الصحيحة ذات 64 بتًا نصوصًا. أما القيم فمختلقة.

مثال على span بصيغة JSON الخاصة بـ OTLP: الحقول traceId وspanId وparentSpanId والاسم GET /cart/id والنوع 2 وسمات HTTP وحدث استثناء ورابط إلى تتبع آخر وحالة برمز 2

قراءة سريعة: الاسم GET /cart/{id} مسار وليس عنوان URL الفعلي، ولهذا تبقى القيم المختلفة قليلة. والقيمة kind: 2 تقابل SPAN_KIND_SERVER (يحتفظ الملف proto بالقيمة 0 لحالة «غير محدد»)، والقيمة code: 2 في الحالة تقابل STATUS_CODE_ERROR. كل شيء هنا سليم. والمهم هو ما يحدث حين لا يكون كذلك.

الفخ الأول: في أي جانب نقف؟

يحدد نوع الـ span من ينتظر من. وله خمس قيم:

  • SERVER: يعالج طلبًا وصل من الخارج، وثمة من ينتظر الرد؛
  • CLIENT: يرسل طلبًا وينتظر بنفسه؛
  • PRODUCER: يطلق عملًا أو يجدوله، وغالبًا ينتهي قبل أن يبدأ ذلك العمل؛
  • CONSUMER: ينفّذ عملًا تركه منتِج لا ينتظر النتيجة؛
  • INTERNAL: القيمة الافتراضية، أي خطوة داخلية في العملية.

في سيناريوي تستدعي السلة خدمة المخزون، فأتوقع span من نوع CLIENT في السلة وآخر من نوع SERVER في المخزون. إذا ظهر الاثنان INTERNAL فالأدوات مثبّتة جزئيًا وتفقد خرائط الاعتماديات أسهمها. وفي Dynatrace تكتب الوثائق الحقل span.kind بأحرف صغيرة (server وclient وconsumer وproducer).

الفخ الثاني: سمات تُضاف متأخرة

تروي السمات ظروف العملية. توصي المواصفة بتمريرها عند إنشاء الـ span، لأن أداة أخذ العينات لا تحكم إلا بما هو موجود في تلك اللحظة، ولأن شيئًا لا يتغير بعد تثبيت نهاية الـ span. وفي span خادم لـ HTTP تتوقع الاصطلاحات الدلالية السمات http.request.method وurl.path وurl.scheme، إضافة إلى http.route وhttp.response.status_code متى كانا معروفين. وفي جهة العميل: http.request.method وserver.address وserver.port وurl.full.

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

الفخ الثالث: خطأ لا يُسجَّل خطأً

نعود إلى السلة البيضاء. يعرض الـ span استثناءً ومع ذلك تبقى اللوحة خضراء. والسبب المرجح هو الحالة: قيمتها الافتراضية Unset، ولا تصبح Ok أو Error إلا إذا قرر أحدهم ذلك، ولا معنى لرسالة الوصف إلا مع Error. وتنصح المواصفة مكتبات القياس بعدم ضبط Ok دون إعداد صريح. وفي HTTP يترك الرمز 4xx الـ span من نوع SERVER بلا حالة، بينما يستدعي الرمز 5xx الحالة Error.

الأحداث والاستثناءات

الحدث ملاحظة موسومة بوقت داخل الـ span. تُنشئ RecordException حدثًا اسمه exception يحمل exception.type وexception.message ومعهما مكدّس الاستدعاءات إذا طُلب. فالاستثناء الذي يُلتقط ثم يُبتلع يترك أثرًا في events دون أن يمس الحالة أبدًا، وهذا بالضبط ما حدث في سلتنا. تنبيه: صفحة الاصطلاحات الخاصة بالاستثناءات في الـ spans موسومة بأنها مهجورة لصالح السجلات، فتحقق مما تفعله حزمة SDK لديك.

الروابط

يشير الرابط إلى سياق span آخر، من التتبع نفسه أو من تتبع مختلف، ويحمل سماته الخاصة. وهو يحل محل علاقة الأب والابن حين لا تناسب: معالجة دفعية تستهلك عشرين رسالة لا يمكن أن يكون لها عشرون أبًا.

إعادة التحقيق بلغة DQL

في Dynatrace SaaS يعرض الأمر fetch spans النموذج التالي: trace.id وspan.id وspan.parent_id (بايتات تُعرض بالنظام الست عشري) وspan.kind وstart_time وend_time وduration. أما الحالة فهي span.status_code، ولا تظهر إلا للقيمتين error وok، ومعها span.status_message. والأحداث والروابط مصفوفتان: span.events وspan.links.

يعيد الاستعلام 1 قراءة تتبع مشتبهنا (لم يُنفَّذ)، أما الاستعلام 2 فمن وثائق Advanced Tracing Analytics ويعدّ الاستثناءات بحسب نوعها.

استعلامان بلغة DQL: الأول fetch spans مصفّى بمعرّف trace.id باستخدام toUid، والثاني استعلام وثائق Dynatrace الذي يعدّ الاستثناءات بحسب exception.type انطلاقًا من span.events
  1. حمّل التتبع بالاستعلام 1 في notebook مع معرّف حقيقي وفترة زمنية تشمل وقت الـ span.
  2. ابحث عن الجذر: هو الصف الذي يكون فيه span.parent_id فارغًا، وتشير الصفوف الأخرى إلى span.id لأبيها.
  3. ابحث عن الإخفاقات الحقيقية بالشرط filter span.status_code == "error" (لم يُنفَّذ، استنادًا إلى تعريف الحقل)، ثم قارنها بعدد الـ spans التي تحمل استثناءً بلا حالة.
  4. افتح الأحداث بالاستعلام 2: يجعل expand span.events ثم fieldsFlatten سماتها قابلة للتصفية.

إن لم تكن الأوامر مألوفة لك فابدأ بدرس filter وsummarize وtimeseries.

كيف تتحقق من أن الأمر يعمل

أرسل span تجريبيًا: يجب أن يعيد الاستعلام 1 صفًا لكل span مع قيم صحيحة لـ span.parent_id وduration. ويحتاج رمز الإدخال الخاص بـ OTLP إلى النطاق الذي تذكره صفحة «OTLP API» (كان openpipeline:traces:ingest وقت قراءتي)، ولا تقبل هذه الواجهة إلا HTTP مع Protobuf، دون gRPC أو JSON. وتذكر مقالات أخرى في هذه المدوّنة النطاق openTelemetryTrace.ingest، فتأكد من النطاق المعتمد حاليًا قبل إنشاء الرمز. وإن لم يظهر شيء فاتبع غياب تتبعات OpenTelemetry في Dynatrace.

ما الذي يُفشل التحقيق

  • ساعة خارج النافذة: بحسب وثائق الإدخال يجب ألا تسبق نهاية الـ span الوقت الحالي بأكثر من 60 دقيقة، ولا تتجاوزه بأكثر من 10 دقائق.
  • أبوان محتملان: قد ينتج عن اجتماع OneAgent وOpenTelemetry في التتبع نفسه spans مكررة. تتوقع الوثائق الحقل span.alternate_parent_id، وهو حقل تجريبي، وتجد التفاصيل في مقال الـ spans المكررة.
  • اسم متغيّر: وضع معرّف الزبون داخل اسم الـ span يضخّم عدد القيم المختلفة.

عاداتي في القياس

  • التسمية بمسار أو عملية ثابتة.
  • تمرير السمات المطلوبة عند إنشاء الـ span.
  • ضبط Error عند الإخفاقات الفعلية، حتى بعد استثناء ملتقَط، وترك Unset لما سواها.
  • إبعاد البيانات الشخصية عن السمات ورسائل الاستثناءات.

الأسئلة الشائعة

ما الفرق بين span وتتبع؟

الـ span عملية واحدة. أما التتبع فهو مجموعة الـ spans التي تتشارك trace_id نفسه وترتبط بآبائها.

هل أستخدم حدثًا أم سمة؟

تصف السمة الـ span كله، أما الحدث فيؤرّخ لحظة بعينها، كاستثناء أو إعادة محاولة.

أين أقرأ حالة الـ span في Dynatrace؟

في span.status_code (وكذلك span.status_message). لا يوجد الحقل عندما تكون الحالة Unset، وهذا يفسّر كثيرًا من الأخطاء غير المرئية.

الخلاصة

أمام أي span مشبوه اطرح الأسئلة نفسها بالترتيب نفسه: إلى أي قصة ينتمي، ومن استدعاه، وفي أي جانب كان، وفي أي ظروف، وماذا حدث، وكيف انتهى. وفي Dynatrace SaaS يجيب الأمر fetch spans عن كل سؤال منها. خذ تتبعًا حقيقيًا، وأعد قراءته بالاستعلام 1، وقارنه بما تصدره حزمة SDK لديك. المرجع: مواصفة واجهة التتبع في OpenTelemetry.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Paquets malveillants Dynatrace : détecter et trier le CWE-506

الحزم الخبيثة Dynatrace: اكتشاف CWE-506 وفرزه

Next Post
Honeytoken Kubernetes : leurres Koney et détection Tetragon

رموز الخداع honeytoken في Kubernetes: أفخاخ Koney وكشف Tetragon

Related Posts