> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# التتبّع الموزّع: التتبّعات والـ Spans والسياق

> تعرّف على طريقة ربط التتبّعات الموزّعة والـ Spans للطلبات والسجلات والمشكلات والإجراءات والمقاييس في LogBrew.

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

استخدم التتبّع عندما يُبلغ سجل عن إخفاق دون أن يذكر مسار العملية. يمكن أن يُظهر
التتبّع:

* العملية التي بدأت الطلب.
* المواضع التي استهلك فيها الطلب وقته.
* العملية الفرعية التي أرجعت خطأ.
* السجلات والمشكلات والإجراءات والمقاييس التي تحمل معرّف التتبّع نفسه.
* الخدمة والبيئة والإصدار التي أرسلت كل Span.

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

| الحقل | المعنى |
| - | - |
| `trace_id` | يحدد التتبّع الذي يملك الـ Span. |
| `span_id` | يحدد عملية واحدة داخل التتبّع. |
| `parent_span_id` | يربط العملية الفرعية بالعملية التي بدأتها. لا يحمله الـ Span الجذري. |
| `name` | يسمّي العملية، مثل قالب مسار (route template). |
| `operation` | نوع العمل، مثل `http.server` أو `db.query`. |
| `status` | النتيجة المُبلَّغ عنها، مثل `ok` أو `error` أو `cancelled`. |
| `started_at` | وقت بدء العملية. |
| `duration_ms` | مدة تشغيل العملية بالمللي ثانية. |
| `service_name`, `environment`, `release` | نطاق الخدمة التي أرسلت الـ 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](/ar/guides/sdk-ingestion#javascript-queue-tracing).

لا تسجّل تكاملات الطلبات الواردة والصادرة في Node.js وPython نصوص الطلبات أو
الاستجابات، ولا سلاسل الاستعلام، ولا الترويسات العشوائية، ولا قيمة
`traceparent` الخام داخل الـ Spans. سمِّ الـ Spans بقوالب المسارات، لا بعناوين
URL فعلية. لمعرفة تكاملات بيئة التشغيل لديك، اقرأ
[إرشادات دمج SDK](/ar/guides/sdk-ingestion).

## <span id="capture-spans">Spans الالتقاط</span>

يخزّن LogBrew كل سجل أو مشكلة أو إجراء أو مقياس جديد مع معرّف تتبّع. إذا لم تُشِر
الإشارة إلى Span في الدفعة نفسها، يضيف LogBrew لها Span التقاط واحدًا:

| الحقل | القيمة |
| - | - |
| `name` | `log capture` أو `issue capture` أو `action capture` أو `metric capture` |
| `operation` | `logbrew.log` أو `logbrew.issue` أو `logbrew.action` أو `logbrew.metric` |
| `duration_ms` | `0` |
| `parent_span_id` | الـ Span الذي كان نشطًا عندما التقط التطبيق الإشارة. يكون فارغًا إذا لم يكن أي Span نشطًا. |
| `status` | `error` للمشكلة، أو للسجل بالمستوى `error` أو `critical`، أو للإجراء الفاشل. ويكون فارغًا في غير ذلك. |
| `attributes.logbrew.evidence` | `signal_capture` |

بعد ذلك يحدد `span_id` الخاص بالإشارة الـ Span الذي التقطها. وإذا لم يكن للإشارة
سياق تتبّع، ينشئ LogBrew لها معرّف تتبّع جديدًا. يُظهر هذا التتبّع أن LogBrew
خزّن الإشارة، ولا يُظهر مسار طلب. لا تقرأ Spans الالتقاط في تتبّع واحد على أنها
طلب واحد.

تُحتسب Spans الالتقاط في `span_count` و`error_span_count`. لذلك قد يجعل سجل خطأ
الخيار `--status error` يختار تتبّعًا لم تفشل فيه أي عملية من عمليات التطبيق.
اقرأ `operation` لكل Span خطأ قبل أن تستنتج شيئًا.

## قراءة تتبّع

استخدم معرّف تتبّع دقيقًا من سجل أو مشكلة أو قائمة تتبّعات:

```bash theme={null}
logbrew read traces --project "<project_id>" --status error --since 24h --json
logbrew read trace "<trace_id>" --project "<project_id>" --json
```

يختار `--status error` التتبّعات التي تحتوي على Span خطأ واحد على الأقل. ويختار
`--status ok` التتبّعات التي لا تحتوي على أي Span خطأ. ويختار
`--min-duration-ms 500` التتبّعات التي استمرت 500 مللي ثانية أو أكثر.

اقرأ مدة الـ Span الجذري أولًا. ثم افحص أطول الـ Spans الفرعية وحالات الخطأ.
أبقِ المشروع والخدمة والبيئة والإصدار أمامك، حتى لا يصبح تتبّع من بيئة التجهيز
دليلًا على بيئة الإنتاج.

يُظهر التتبّع الواحد تنفيذًا واحدًا، وليس خط أساس للأداء. قبل أن تقترح تغييرًا في
الأداء، قارن عدة تتبّعات باتجاه المقياس المرتبط بها.

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

تُرجع `GET /api/telemetry/traces/{trace_id}/summary` ملخصًا دون سمات الـ Spans:

| الحقل | المعنى |
| - | - |
| `root_span` | أقدم Span لا يوجد أبوه في التتبّع. وإذا كان لكل Span أب داخل التتبّع، فهو أقدم Span. |
| `slowest_child_span` | أطول Span له أب. |
| `slowest_path` | سلسلة الآباء المعروفة من الجذر إلى أبطأ Span فرعي. |
| `error_spans` | ما يصل إلى 5 من أطول الـ Spans ذات الحالة `error`. |
| `services` | عدد الـ Spans، وعدد Spans الخطأ، ومدة أطول Span لكل خدمة. |
| `duration_ms` | الوقت من بداية أقدم Span إلى نهاية آخر Span. |

إذا كانت لـ `root_span.parent_span_id` قيمة، فالـ Span الجذري الحقيقي ليس في
التتبّع. لا تقرأ `root_span` على أنه بداية الطلب.

### شرح تتبّع

يُرجع `logbrew explain trace` تحقيقًا في التتبّع:

```bash theme={null}
logbrew explain trace "<trace_id>" --json
```

| الحقل | المعنى |
| - | - |
| `analysis.status` | `errors_observed` أو `latency_focus` أو `no_error_observed`. |
| `analysis.first_error_span`, `analysis.first_error_path` | أقدم Span خطأ وسلسلة آبائه المعروفة. |
| `analysis.bottleneck_span`, `analysis.bottleneck_path` | أطول Span له أب، وسلسلة آبائه المعروفة. |
| `correlations` | المشكلات والسجلات والإجراءات والمقاييس التي تحمل معرّف التتبّع نفسه. لكل قائمة `status` و`truncated`. |
| `evidence` | الحقول الملتقَطة والمفقودة والمحجوبة والمقتطَعة. |
| `next_actions` | القراءات التالية، مرتبة حسب الأولوية. |

قيمة `analysis.causality` هي `evidence_only`. فالتحليل لا يُثبت سببًا جذريًا.
ويطلب الـ CLI الإصدار 3 من الاستجابة، وفيه تحمل كل مشكلة وإجراء ومقياس مرتبط
أيضًا قيمة `span_id` الدقيقة الخاصة به.

لفحص Span واحد مع أبيه وأبنائه وحدود الخدمات، شغّل:

```bash theme={null}
logbrew explain span "<trace_id>" "<span_id>" --project "<project_id>" \
  --environment production --release "<release>" --json
```

يخبرك `topology.parent_chain_status` بما إذا كانت سلسلة الآباء مكتملة:

| القيمة | المعنى |
| - | - |
| `root` | ليس للـ Span معرّف أب. |
| `complete` | كل الآباء حتى الـ Span الجذري موجودون في التتبّع. |
| `missing` | يشير معرّف أب إلى Span غير موجود في التتبّع. |
| `cycle` | تشكّل معرّفات الآباء حلقة. |
| `truncated` | يمنع حدّ في الاستجابة اكتمال السلسلة. |
| `unavailable` | تعذّر إكمال قراءة التتبّع. |

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

ليس لكل حدث تتبّع لطلبه. اقرأ حالة التتبّع:

| الحالة | المعنى |
| - | - |
| `available` | يمكن قراءة أدلة تتبّع دقيقة. |
| `not_linked` | لا يحمل الحدث معرّف تتبّع. بعض الأحداث الأقدم لا تحمل معرّف تتبّع. |
| `not_found` | يحمل الحدث معرّف تتبّع، لكن لم يطابقه أي تتبّع في النطاق المحدد. |
| `unavailable` | تعذّرت قراءة أدلة التتبّع في ذلك الوقت. |

الحالة `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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.