Skip to main content
يتابع التتبّع الموزّع طلبًا واحدًا أو عملية واحدة عبر الخدمات المزوَّدة بأدوات القياس. يجمع التتبّع الـ Spans الخاصة بهذا العمل. وكل Span عملية واحدة لها مدة محددة، مثل طلب HTTP أو استدعاء قاعدة بيانات أو عملية في طابور أو مهمة في الخلفية. وإذا غاب Span بقي جزء من المسار مجهولًا. استخدم التتبّع عندما يُبلغ سجل عن إخفاق دون أن يذكر مسار العملية. يمكن أن يُظهر التتبّع:
  • العملية التي بدأت الطلب.
  • المواضع التي استهلك فيها الطلب وقته.
  • العملية الفرعية التي أرجعت خطأ.
  • السجلات والمشكلات والإجراءات والمقاييس التي تحمل معرّف التتبّع نفسه.
  • الخدمة والبيئة والإصدار التي أرسلت كل Span.

​
حقول التتبّع والـ Span

يبدأ الـ Span الجذري التتبّع وليس له أب. وتحمل الـ Spans الفرعية معرّف التتبّع نفسه، ومعرّفات Span خاصة بها، ومعرّف الأب. هذه المعرّفات وحدها تربط العمليات، والطوابع الزمنية وحدها لا تربطها. لا يعدّ LogBrew الـ Span خطأً إلا عندما تكون قيمة status الخاصة به error.

​
طلب عبر عدة خدمات

  1. تبدأ خدمة الويب Span خادم لمسار إتمام الشراء.
  2. ينشئ عميل الدفع Span فرعيًا لطلب HTTP الصادر منه.
  3. تواصل خدمة الدفع التتبّع بـ Span خادم خاص بها.
  4. تسجّل دالة مساعدة لقاعدة البيانات Span فرعيًا لعملية الكتابة.
  5. يرسل التطبيق سجل خطأ آمنًا داخل Span الدفع النشط.
تحمل القيود الخمسة كلها معرّف التتبّع نفسه. إذا لم تستقبل خدمةٌ سياق التتبّع، فلن ينضم عملها إلى التتبّع، حتى لو تداخلت الأوقات.

​
نقل السياق

تستخدم حزم SDK من LogBrew سياق التتبّع W3C. مثلًا، يواصل SDK الخاص بـ Node.js ترويسة traceparent الواردة الصالحة بـ Span جديد للطلب. وإذا كانت الترويسة مفقودة أو غير صالحة، فإنه يبدأ جذرًا جديدًا. وتحمل السجلات والمشكلات والإجراءات والمقاييس الملتقَطة داخل نطاق هذا الطلب تتبّع الطلب. لا تكتب أدوات القياس الصادرة ترويسة traceparent إلا إلى الوجهات التي تضبطها، مثل tracePropagationTargets. أرسل سياق التتبّع إلى الخدمات الموثوقة المزوَّدة بأدوات القياس فقط. معرّف التتبّع يربط العمليات ببعضها، وليس وسيلة للمصادقة. يمكن أن تحمل رسالة الطابور سياق التتبّع أيضًا. في Node.js، استدعِ createLogBrewQueueTraceHeaders() في عملية المُنتِج لإضافة ترويسة traceparent إلى الرسالة. وفي المستهلك، مرّر هذه الترويسة إلى queueOperationWithLogBrewSpan() بالاسم traceparent. راجع تتبّع الطوابير في JavaScript. لا تسجّل تكاملات الطلبات الواردة والصادرة في Node.js وPython نصوص الطلبات أو الاستجابات، ولا سلاسل الاستعلام، ولا الترويسات العشوائية، ولا قيمة traceparent الخام داخل الـ Spans. سمِّ الـ Spans بقوالب المسارات، لا بعناوين URL فعلية. لمعرفة تكاملات بيئة التشغيل لديك، اقرأ إرشادات دمج SDK.

​
Spans الالتقاط

يخزّن LogBrew كل سجل أو مشكلة أو إجراء أو مقياس جديد مع معرّف تتبّع. إذا لم تُشِر الإشارة إلى Span في الدفعة نفسها، يضيف LogBrew لها Span التقاط واحدًا: بعد ذلك يحدد span_id الخاص بالإشارة الـ Span الذي التقطها. وإذا لم يكن للإشارة سياق تتبّع، ينشئ LogBrew لها معرّف تتبّع جديدًا. يُظهر هذا التتبّع أن LogBrew خزّن الإشارة، ولا يُظهر مسار طلب. لا تقرأ Spans الالتقاط في تتبّع واحد على أنها طلب واحد. تُحتسب Spans الالتقاط في span_count وerror_span_count. لذلك قد يجعل سجل خطأ الخيار --status error يختار تتبّعًا لم تفشل فيه أي عملية من عمليات التطبيق. اقرأ operation لكل Span خطأ قبل أن تستنتج شيئًا.

​
قراءة تتبّع

استخدم معرّف تتبّع دقيقًا من سجل أو مشكلة أو قائمة تتبّعات:
يختار --status error التتبّعات التي تحتوي على Span خطأ واحد على الأقل. ويختار --status ok التتبّعات التي لا تحتوي على أي Span خطأ. ويختار --min-duration-ms 500 التتبّعات التي استمرت 500 مللي ثانية أو أكثر. اقرأ مدة الـ Span الجذري أولًا. ثم افحص أطول الـ Spans الفرعية وحالات الخطأ. أبقِ المشروع والخدمة والبيئة والإصدار أمامك، حتى لا يصبح تتبّع من بيئة التجهيز دليلًا على بيئة الإنتاج. يُظهر التتبّع الواحد تنفيذًا واحدًا، وليس خط أساس للأداء. قبل أن تقترح تغييرًا في الأداء، قارن عدة تتبّعات باتجاه المقياس المرتبط بها.

​
ملخص التتبّع

تُرجع GET /api/telemetry/traces/{trace_id}/summary ملخصًا دون سمات الـ Spans: إذا كانت لـ root_span.parent_span_id قيمة، فالـ Span الجذري الحقيقي ليس في التتبّع. لا تقرأ root_span على أنه بداية الطلب.

​
شرح تتبّع

يُرجع logbrew explain trace تحقيقًا في التتبّع:
قيمة analysis.causality هي evidence_only. فالتحليل لا يُثبت سببًا جذريًا. ويطلب الـ CLI الإصدار 3 من الاستجابة، وفيه تحمل كل مشكلة وإجراء ومقياس مرتبط أيضًا قيمة span_id الدقيقة الخاصة به. لفحص Span واحد مع أبيه وأبنائه وحدود الخدمات، شغّل:
يخبرك topology.parent_chain_status بما إذا كانت سلسلة الآباء مكتملة:

​
سياق التتبّع المفقود

ليس لكل حدث تتبّع لطلبه. اقرأ حالة التتبّع: الحالة not_linked ليست خطأ. وقد يُظهر تتبّع available أيضًا أن الحدث لم يكن له سياق طلب. إذا لم يكن لـ Span الالتقاط الخاص بالحدث parent_span_id، فلم يكن أي Span نشطًا عندما التقط التطبيق الحدث. وغالبًا ما يعطي العمل في الخلفية خارج نطاق الطلب هذه النتيجة. للعثور على علاقة مفقودة:
  1. اقرأ مشروع الحدث وخدمته وبيئته وإصداره ووقته.
  2. تحقّق من أن العمل جرى داخل طلب أو عملية مزوَّدة بأدوات القياس.
  3. تحقّق من أن تكاملات العميل والخادم تنقل السياق عبر هذا الحد.
  4. بعد أن تصحّح أدوات القياس، التقط حدثًا جديدًا واقرأه.
الإصدار الجديد من الـ SDK لا يضيف سياق التتبّع إلى الأحداث المُرسَلة سابقًا. لا تربط حدثًا بتتبّع حسب الطابع الزمني أو المسار أو الرسالة أو الإصدار.

​
خطّط للتتبّع في مشروع واحد

ابدأ بطلب أو مهمة مهمة واحدة، مثل إتمام الشراء. زوّد حدًّا واحدًا بأدوات القياس في كل مرة:
  1. أنشئ Span للطلب الوارد أو للعملية في الخلفية.
  2. أضف Spans فرعية للاستدعاءات الصادرة المهمة.
  3. واصل سياق التتبّع W3C عبر حدود الخدمات الموثوقة.
  4. أرسل سجلًا آمنًا داخل الـ Span النشط.
  5. اقرأ هذا السجل، وافتح معرّف التتبّع الخاص به، وتحقّق من الجذر والأبناء والخدمة والبيئة والإصدار والحالة والمدة.
لا تضف الحد التالي إلا بعد نجاح هذا الفحص. التتبّع المشترك يُظهر ارتباطًا، ولا يُثبت أن Span بعينه سبّب مشكلة. للتحقق من أسماء الـ Spans، شغّل logbrew traces --project "<project_id>" --pagination cursor --json. يعدّ الكائن naming_quality التتبّعات في تلك الصفحة التي لها اسم جذر عام (generic_name_traces) أو مسار غير مطابق (unmatched_route_traces). إذا كانت التسمية تحتاج إلى عناية، تكون قيمة naming_quality.next_action.code هي improve_trace_naming.