> ## 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.

# القياس عن بُعد للتطبيقات: السجلات والتتبّعات والمقاييس

> قارن السجلات والتتبّعات والمقاييس والمشكلات وإجراءات المنتج. اختر إشارة LogBrew المناسبة لتحقيقك.

القياس عن بُعد هو الأدلة المنظَّمة التي يرسلها التطبيق عن سلوكه. تسجّل السجلات
الأحداث المُبلَّغ عنها. وتربط التتبّعات العمليات ببعضها. وتقيس المقاييس القيم.
وتجمع المشكلات الإخفاقات. وتسجّل الإجراءات نشاط المنتج.

تحدد حقول المشروع والخدمة والبيئة والإصدار والوقت نطاق كل نتيجة. لمعرفة
الإشارات التي يلتقطها الـ SDK لديك، اقرأ
[إرشادات دمج SDK](/ar/guides/sdk-ingestion).

## <span id="choose-the-correct-telemetry-data-type">اختر إشارة</span>

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

ابدأ التحقيق في الإخفاق بالمشكلات أو السجلات. استخدم تتبّعًا متاحًا لفحص تنفيذ
واحد. واستخدم اتجاه مقياس لفحص الفترة الأوسع. لمعرفة النشاط والاحتفاظ
بالمستخدمين، اقرأ [تحليلات المنتج](/ar/concepts/product-analytics).

التقط الحقول التي يحتاجها التحقيق فقط. استخدم أسماء ثابتة للخدمات والعمليات
والمقاييس. لا ترسل بيانات الاعتماد أو بيانات الدفع أو نصوص الطلبات الخام. تشرح
[إرشادات التحكم في البيانات الملتقطة](/ar/guides/safe-capture) أدوات التحكم في ذلك.

## السجلات

السجل قيد يصدر عن التطبيق في لحظة زمنية واحدة. يحتوي السجل المفيد على:

* وقت وقوع الحدث في المصدر.
* مستوى خطورة معياري.
* نطاق المشروع والخدمة.
* البيئة والإصدار.
* معرّفَي التتبّع والـ Span عندما يكون للسجل سياق تتبّع نشط.
* سمات صغيرة ومسمّاة تحمل سياق الحدث.

تحتوي استجابة السجل على هذه القيم في `occurred_at` و`severity` و`project_id`
و`service_name` و`environment` و`release` و`trace_id` و`span_id`
و`attributes`. ضع السياق في سمات مسمّاة، لا في نص الرسالة.

السجلات الصادرة عن عدة خدمات في عرض واحد لا تجمعها علاقة تتبّع. سياق التتبّع
وحده ينشئ هذه العلاقة.

## التتبّعات

يحتوي التتبّع على الـ Spans الخاصة بطلب واحد أو عملية واحدة. الـ Span الجذري
ليس له أب. ويحدد الـ Span الفرعي الـ Span الأب الخاص به. تحمل كل Spans التتبّع
معرّف التتبّع نفسه ومعرّفات Span مختلفة. راجع
[التتبّع الموزّع](/ar/concepts/distributed-tracing).

يحصل كل سجل أو مشكلة أو إجراء أو مقياس يُرسَل دون سياق تتبّع نشط على تتبّع
التقاط. لا يحتوي هذا التتبّع إلا على Spans التقاط، ولا يُظهر مسار طلب. راجع
[Spans الالتقاط](/ar/concepts/distributed-tracing#capture-spans).

## <span id="read-the-metric-value">المقاييس</span>

يسجّل المقياس قيمة مقيسة عبر الزمن. اقرأ كل مقياس مع اسمه ووحدته وأبعاده
ومشروعه ونطاقه الزمني وفاصله الزمني. يختار LogBrew قيمة `value` لكل نقطة بناءً
على `kind` و`temporality` للمقياس:

| عقد المقياس | `aggregation.code` | قيمة `value` للنقطة |
| - | - | - |
| `gauge` مع `instant` | `gauge_last` | آخر حالة في الفاصل الزمني، مثل عمق الطابور. |
| `counter` مع `delta` | `delta_sum` | مجموع التغييرات في الفاصل الزمني، مثل المهام المكتملة. |
| `histogram` مع `delta` | `distribution_p95` | النسبة المئوية 95 التقريبية، مثل مدة الطلب. |
| تدفق `cumulative` | `raw_cumulative_last` | آخر إجمالي خام. وهو ليس معدّلًا. |
| أي زوج آخر | `raw_last` | آخر عيّنة خام. |

مثلًا، ثلاث عيّنات من عدّاد تغيّر (delta counter) بالقيم `2` و`3` و`5` في فاصل
زمني واحد تعطي نقطة قيمتها `value` تساوي `10` وقيمة `sample_count` تساوي `3`.
أما ثلاث عيّنات gauge بالقيم نفسها وبالترتيب نفسه فتعطي نقطة قيمتها `value`
تساوي `5`. قيمة p95 ليست متوسطًا. فنحو 95% من الملاحظات المسجّلة تساويها أو
تقل عنها.

عند `status: "ready"` يكون التجميع المشتق متاحًا. وعند `status: "limited"` اقرأ
`aggregation.limitation` واستخدم القيم الخام فقط. لا تجمع قيم gauge أو تدفقًا
تراكميًا. والفاصل الزمني الذي لا نقطة فيه ليس قياسًا بقيمة صفر. لمعرفة حقول
الاستعلام، اقرأ
[عوامل تصفية الاستعلام](/ar/reference/telemetry-api-filters).

تُرجع `GET /api/telemetry/metrics/series` هذه النقاط. وتتطلب `project_id`
و`name` و`since`. لكل سلسلة `identity` واحدة تحمل `kind` و`unit`
و`temporality`. وتبقى السلاسل ذات الهويات المختلفة منفصلة. ويمكن أن تحتوي كل
نقطة أيضًا على:

| الحقل | المعنى |
| - | - |
| `min`, `max`, `average` | نطاق العيّنات في الفاصل الزمني ومتوسطها. |
| `p50`, `p95`, `p99` | نسب مئوية تقريبية للـ histogram. |
| `rate_per_second` | مجموع عدّاد التغيّر مقسومًا على عرض الفاصل الزمني. |
| `trace_exemplars` | معرّفات تتبّعات مأخوذة كعيّنات من الفاصل الزمني. افتح أحدها لفحص طلب من ذلك الفاصل. |

تكون `coverage.truncated` بالقيمة `true` عندما يُسقط `series_limit` السلاسل
الأقل حجمًا. لمقارنة نافذة مقياس بالنافذة السابقة لها بالطول نفسه، شغّل:

```bash theme={null}
logbrew explain metric '<metric-name>' --project '<project-id>' --since 24h --json
```

## المشكلات

تجمع المشكلة الإخفاقات المتكررة حسب بصمة ثابتة. ولها خطورة وحالة وعدد مرات
حدوث ووقت أول ظهور ووقت آخر ظهور. ويمكن أن تضيف تفاصيل المشكلة سلاسل الاستثناءات
وإطارات المكدّس والـ Breadcrumbs (أحداث قصيرة مسجَّلة قبل وقوع المشكلة)
والسجلات المرتبطة وعلاقة تتبّع.

تمثّل `last_seen_at` أحدث حدوث في المجموعة. وقد يكون الحدوث الذي تختاره أقدم.
اقرأ الوقتين كليهما.

تكون قيمة `status` للمشكلة `unresolved` أو `resolved` أو `archived`. يعرض
الإصدار 1 من استجابة الـ API القيمة `archived` على أنها `ignored`. ويضيف
الإصداران 2 و3 الحقلين `priority` (`high` أو `medium` أو `low`)
و`priority_source`. ويضيف الإصدار 3 أيضًا `assignee`. راجع
[قيم الحالة](/ar/guides/issue-workflow#status-values)
و[الأولوية](/ar/guides/issue-workflow#priority).

## الإجراءات

يسجّل الإجراء نشاط المنتج. ويصنّفه التصنيف المدعوم على أنه مشاهدة صفحة أو مشاهدة
شاشة أو تفاعل. اسم الحدث وحده لا يحدد التصنيف. استخدم
[التقاط أحداث المنتج](/ar/guides/product-events) لإضافة هذا السياق.

الجلسات ليست مستخدمين. والكيانات مجهولة الهوية ليست مستخدمين معروفي الهوية.

## <span id="shared-fields">الحقول المشتركة</span>

| الحقل | الاستخدام |
| - | - |
| `project_id` | يملك بيانات القياس عن بُعد ويتحكم في حدود القراءة. |
| `service_name` | يحدد التطبيق أو الخدمة التي أرسلت الإشارة. |
| `environment` | يفصل بيانات الإنتاج والتجهيز (staging) والمعاينة والبيئة المحلية. |
| `release` | يحدد إصدار الشيفرة المنشورة. |
| `occurred_at` | يعطي وقت المصدر لسجل واحد أو إجراء واحد. تستخدم الـ Spans الحقل `started_at`. |
| `trace_id` | يربط الإشارات الملتقَطة في سياق التتبّع نفسه. |
| `span_id` | يحدد الـ Span الذي تنتمي إليه الإشارة داخل تتبّعها. |

## <span id="severity-values">قيم الخطورة</span>

| القيمة المعيارية | الأسماء البديلة المقبولة في الإدخال |
| - | - |
| `info` | `trace`, `debug`, `info` |
| `warning` | `warn`, `warning` |
| `error` | `error` |
| `critical` | `fatal`, `critical` |

يقبل LogBrew الأسماء البديلة في الإدخال بأي حالة أحرف. ويستخدم الـ API والـ CLI
والأحداث المباشرة القيم المعيارية. ويرفض قيم الخطورة غير المعروفة. الخطورة هي
درجة الإلحاح المسجّلة، ولا تُظهر التأثير على العمل أو السبب الجذري.

يمكن للمستخدم تغيير الخطورة المعروضة لمشكلة أو سجل. عندها تحتوي الاستجابة على
كائن `triage` فيه `effective_severity`. ويحتفظ الحقل `severity` بالقيمة
الملتقَطة.

## القراءة المباشرة واللقطات

يُرجع `logbrew read` لقطة للمشروع والنطاق الزمني وعوامل التصفية المحددة. شغّله
مرة أخرى لقراءة الأحداث الجديدة. ويبثّ `logbrew watch` السجلات والمشكلات
والإجراءات الجديدة ما دام الاتصال مفتوحًا. ولا يبثّ التتبّعات أو المقاييس. فشل
الاتصال لا يعني أن المشروع فارغ.

## <span id="evidence-quality-and-trace-lifecycle">حالات الأدلة</span>

تُبقي الاستجابات هذه الحالات منفصلة: ملتقَط، ومفقود، ومحجوب، ومقتطَع، وغير متاح.
ولأدلة التتبّع أربع حالات: `available` و`not_linked` و`not_found`
و`unavailable`. راجع [المقدمة](/ar/introduction#follow-exact-relationships)
لمعرفة معناها، و[حدود الأدلة](/ar/introduction#read-evidence-states-before-drawing-a-conclusion)
لمعرفة حقول التغطية. الإصدار الأحدث من الـ SDK لا يضيف حقولًا إلى الأحداث التي
أرسلها سابقًا.

## <span id="a-practical-investigation">التحقيق في مشروع واحد</span>

<Steps>
  <Step title="اعثر على المشكلات غير المحلولة">
    ```bash theme={null}
    logbrew read issues --project '<project-id>' --status unresolved --since 24h --json
    ```
  </Step>

  <Step title="اقرأ مشكلة واحدة">
    يقرأ هذا الأمر تاريخ المشكلة المحتفَظ به. ولا ينطبق عليه عامل التصفية
    `--since` المستخدم في القائمة.

    ```bash theme={null}
    logbrew investigate issue '<issue-id>' --json
    ```
  </Step>

  <Step title="افتح تتبّعًا متاحًا">
    استخدم معرّف التتبّع فقط عندما يُرجعه الحدوث المحدد.

    ```bash theme={null}
    logbrew read trace '<trace-id>' --project '<project-id>' --json
    ```
  </Step>

  <Step title="اقرأ الأدلة المرتبطة">
    صفِّ السجلات والإجراءات والمقاييس حسب المشروع والخدمة والبيئة والإصدار
    نفسها. لا تربط الإشارات بالوقت وحده.
  </Step>
</Steps>

لمعرفة حقول الاستجابة، اقرأ [Telemetry API](/ar/reference/telemetry-api)
و[تنسيقات الاستجابة](/ar/reference/telemetry-response-shapes).


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