مسرد مصطلحات قابلية الملاحظة وLogBrew

يستخدم LogBrew مصطلحًا واحدًا لكل مفهوم في المنتج. وتبقى حقول الـ API وخيارات CLI وقيم التعداد (enum) وأسماء الأحداث ومفاتيح السمات دون تغيير في كل اللغات.

قابلية الملاحظة والمراقبة

المصطلح	المعنى
قابلية الملاحظة (Observability)	فهم سلوك التطبيق من الأدلة التي ينتجها.
القياس عن بُعد (Telemetry)	الإشارات التي يُبلغ عنها التطبيق، مثل السجلات والتتبّعات والمقاييس.
المراقبة (Monitoring)	فحص حالات معروفة، مثل مقارنة قيمة مقيسة بحد معيّن.
`o11y`	اختصار لكلمة observability. يشير الرقم إلى الأحرف الـ 11 بين `o` و`y`.

لاختيار الإشارات ورؤية أمثلة عملية، اقرأ القياس عن بُعد.

وكلاء الذكاء الاصطناعي

المصطلح	المعنى
خادم MCP	خادم LogBrew المستضاف لبروتوكول Model Context Protocol. يستخدمه وكلاء الذكاء الاصطناعي لقراءة المشاريع المعتمدة.
عميل MCP	تطبيق يربط وكيل الذكاء الاصطناعي بخادم MCP، مثل Claude Code.
مشروع معتمد	مشروع اخترته عندما منحت عميل MCP صلاحية الوصول. لا يستطيع العميل قراءة غير المشاريع المعتمدة.
اتصال	الوصول الذي تمنحه لعميل MCP واحد عندما توافق عليه. ينتهي بعد 30 يومًا دون استخدام، أو بعد 90 يومًا، أو عندما تبطله. وتسمّيه CLI باسم grant.

لربط عميل، اقرأ ربط وكيل ذكاء اصطناعي عبر MCP.

إشارات قابلية الملاحظة

المشكلة

مشكلة مجمّعة قد تحتوي على عدة مرات حدوث. الحدوث هو نسخة واحدة ملتقَطة من هذه المشكلة. first_seen_at هو وقت أول حدوث. وlast_seen_at هو وقت أحدث حدوث.

السجل

قيد حدث واحد له طابع زمني. يمكن أن يحمل السجل الخطورة والخدمة والإصدار والبيئة وسياق التتبّع وسمات تحدّها قواعد الخصوصية.

التتبّع والـ Span

يتبع التتبّع العمل عبر طلب أو عملية. والـ Span عملية واحدة محددة التوقيت داخل هذا التتبّع. الارتباط بتتبّع دليل على سياق مشترك، وليس إثباتًا للسبب.

المقياس

قياس وقت التشغيل له وحدة ونوع وطريقة تجميع ونطاق زمني محددة. لا يمكن استبدال نقاط المقاييس بأعداد السجلات أو التتبّعات أو المشكلات.

الإصدار

نسخة منشورة من تطبيق أو خدمة يُبلغ عنها مع بيانات القياس عن بُعد. الإصدار ليس الكائن نفسه الذي يمثله المشروع أو المستودع.

الإجراء

حدث منتج مصنّف، مثل التسجيل في الخدمة أو إتمام الشراء أو الاستيراد أو مهمة فاشلة. تصنّف التحليلات الإجراء على أنه مشاهدة صفحة أو مشاهدة شاشة أو تفاعل. الإجراء ليس أمرًا تلقائيًا يشغّله LogBrew.

التحقيق في المشكلات

لا يحتوي كل حدوث على كل الحقول.

المصطلح	المعنى
الخطورة (Severity)	مدى إلحاح الإشارة: `info` أو `warning` أو `error` أو `critical`. وهي منفصلة عن حالة المشكلة.
حالة المشكلة (Issue status)	حالة سير العمل لمشكلة مجمّعة: `unresolved` أو `resolved` أو `archived`. وليست نتيجة طلب واحد.
مشكلة مؤرشفة (Archived issue)	مشكلة أخرجها الفريق من الفرز النشط. تسمّي الاستجابات الأقدم هذه الحالة `ignored`.
أولوية المشكلة (Issue priority)	ترتيب الفرز لمشكلة مجمّعة: `high` أو `medium` أو `low`. تُشتق من الخطورة إلى أن يضبطها شخص.
مصدر الأولوية (Priority source)	مصدر الأولوية. `derived` تُشتق من الخطورة: `error` و`critical` تعطيان `high`، و`warning` تعطي `medium`، و`info` تعطي `low`. و`manual` أولوية ضبطها شخص.
المسؤول عن المشكلة (Issue assignee)	الحساب الواحد أو الفريق الواحد الذي يملك الخطوة التالية في مشكلة مجمّعة. يجب أن يستطيع الحساب قراءة المشروع، وأن ينتمي الفريق إلى مؤسسة المشروع.
الفريق (Team)	مجموعة من أعضاء المؤسسة لها اسم. يمكن إسناد المشكلات إلى فريق، ويمكن أن تذكره قواعد الملكية. ولا يمنح الفريق أعضاءه أي وصول إلى المشروع.
قاعدة الملكية (Ownership rule)	قاعدة في المشروع تربط مسار إطار المكدّس أو الوحدة أو مسار الطلب أو الخدمة أو الوسم بالحسابات أو الفرق التي تملك المشكلات المطابِقة.
المالك المقترح (Suggested owner)	حساب أو فريق يقترحه LogBrew لمشكلة، بناءً على قاعدة ملكية أو سطر في CODEOWNERS أو نشاط حديث. وهو اقتراح، لا إسناد.
صندوق الوارد (Inbox)	قائمة المشكلات التي أسندها إليك أو إلى فرقك أشخاص آخرون. لا يرسل LogBrew بريدًا إلكترونيًا بشأنها.
تتبّع المكدّس (stack trace)	دليل ملتقَط على استدعاءات الدوال المرتبطة بخطأ. وهو يختلف عن التتبّع الموزّع.
إطار المكدّس (Stack frame)	إدخال واحد في تتبّع المكدّس. قد يحدد دالة أو وحدة أو ملفًا أو سطرًا أو عمودًا.
سلسلة الاستثناءات (Exception chain)	استثناءات مترابطة يُبلغ عنها معًا، مثل خطأ وسببه. الإدخالات المفقودة أو المحجوبة أو المقتطَعة تحدّ من الأدلة.
إطار التطبيق (Application frame)	إطار مكدّس معلَّم على أنه شيفرة التطبيق. يبيّن الشيفرة التي يجب فحصها، ولا يثبت موضع العطل.
Breadcrumb	حدث قصير مسجَّل قبل وقوع حدوث المشكلة. الـ Breadcrumbs ليست تسجيلًا كاملًا للجلسة.
استثناء معالَج (Handled exception)	استثناء أبلغ التطبيق أنه عالجه. لا يثبت أن العملية نجحت.
خريطة المصدر (Source map)	ملف بناء يربط مواضع JavaScript المولَّدة بمواضعها في المصدر الأصلي.
إطار محلَّل الرموز (Symbolicated frame)	إطار حُوّل موضعه المولَّد إلى معلومات المصدر الأصلي.
الحدوث المرجعي (Baseline occurrence)	الحدوث الملتقَط المستخدم مرجعًا لإعادة الإنتاج.
المنشأ (Provenance)	مصدر التقييم. `backend_observed` تعني أن LogBrew رصده. و`application_reported` تعني أن التطبيق أبلغ عنه ولم يتحقق منه LogBrew.
جاهزية إعادة الإنتاج (Reproduction readiness)	هل يحتوي الحدوث المرجعي على الأدلة اللازمة لمحاولة إعادة الإنتاج. وهي ليست اختبار إعادة إنتاج ناجحًا.

استخدم إرشادات التحقيق في مشكلة لمعرفة ترتيب القراءة وحقول الاستجابة.

الهوية والارتباط

القيمة المفقودة لا تثبت أن النشاط المرتبط بها لم يحدث.

المصطلح	المعنى
سياق التتبّع (Trace context)	معرّفات التتبّع والـ Span التي تربط العمل عبر الإشارات.
الـ Span الجذري (Root span)	الـ Span الذي يبدأ التتبّع وليس له Span أب. أقدم Span مُرجَع ليس بالضرورة هو الجذر.
Span فرعي (Child span)	Span له Span أب في التتبّع نفسه.
ارتباط (Correlation)	علاقة دقيقة يُرجعها LogBrew، مثل معرّف تتبّع مشترك. لا تثبت السبب.
مستخدم معروف الهوية (Identified user)	كيان يوفّره التطبيق، له معرّف ثابت ونوع `user`.
كيان مجهول الهوية (Anonymous subject)	كيان يوفّره التطبيق، نوعه `anonymous`. تبقيه الأعداد منفصلًا عن المستخدمين معروفي الهوية.
نوع هوية غير معروف (Unknown identity kind)	كيان بلا نوع معروف. لا يُحسب مستخدمًا معروف الهوية.
كيان مفقود (Missing subject)	حدث بلا كيان. وهذا يختلف عن كيان نوعه غير معروف.

يبيّن نوع الهوية كيف صنّف التطبيق الكيان. ولا يثبت أن البيانات مجهولة الهوية. فقد يظل المعرّف الثابت يربط النشاط.

النطاق وجودة البيانات

المصطلح	المعنى
المشروع (Project)	الحد الأساسي للمنتج الذي تملكه. يمكن أن يحتوي المشروع الواحد على عدة خدمات أو مكوّنات مستودع.
الخدمة (Service)	بيئة تشغيل أو مكوّن يُبلغ عن البيانات داخل مشروع.
البيئة (Environment)	سياق إبلاغ محدد بدقة، مثل بيئة الإنتاج أو بيئة الاختبار المرحلي (staging).
مستوعَب (Ingested)	قَبِله عقد الاستيعاب. ولا يعني ذلك الاحتفاظ به إلى أجل غير محدد.
مفهرَس (Indexed)	متاح للفهرس أو الاستعلام المحدد. وليس مرادفًا لـ «مستوعَب».
محتفَظ به (Retained)	موجود في نافذة البيانات التي جرى تقييمها.
خاضع لأخذ العيّنات (Sampled)	اختير جزء من بيانات القياس قبل الجمع أو أثناءه.
التغطية (Coverage)	نسبة مقيسة لها بسط ومقام صريحان.
مقتطَع (Truncated)	وصلت الاستجابة إلى حد معيّن. البيانات المحذوفة ليست بالضرورة غير موجودة.
تقريبي (Approximate)	مقدَّر بالطريقة الموثّقة بدلًا من العدّ الدقيق.
النطاق الزمني (Time window)	الفترة الدقيقة التي يقيّمها الاستعلام.

القياسات والوقت

المصطلح	المعنى
نقطة بيانات (Data point)	قيمة واحدة في وقت مُبلَغ عنه. اقرأ اسم المقياس ووحدته قبل أن تقارن نقاط البيانات.
سلسلة زمنية (Time series)	قيم القياس نفسه مرتبة حسب الوقت. الفجوة لا تعني أن القيمة كانت صفرًا.
المدة (Duration)	الوقت المنقضي لعملية. وهي تختلف عن وقت حدوث العملية.
التجميع (Aggregation)	عملية حسابية محددة على القياسات، مثل المجموع أو المتوسط.
فاصل زمني (Time bucket)	فترة واحدة في رسم بياني أو نتيجة مجمّعة. تحدد بدايتها ونهايتها النطاق.
فترة غير مكتملة (Partial period)	فترة لم تكتمل بعد. وليست فترة مكتملة بلا نشاط.

لا تجمع مدد الـ Spans الفرعية المتداخلة للحصول على إجمالي وقت الطلب. ولا تقارن عدد الأحداث بعدد المستخدمين معروفي الهوية.

حالات الأدلة

هذه الحالات لا يحل بعضها محل بعض:

ملتقَط: الدليل موجود.
مفقود: لم يُلتقط الدليل.
محجوب: أُخفي الدليل عمدًا.
مقتطَع: تجاوز الدليل حدًا في الاستجابة أو الالتقاط.
غير متاح: لم تستطع القراءة توفير الدليل.

يصف «السبب المحتمل» (Likely cause) و«موضع الإصلاح المحتمل» (likely fix area) أدلة تشخيصية محدودة، لا سببًا جذريًا مثبتًا. ويأتي «التأثير المبلَّغ عنه» (Reported impact) من التطبيق الذي يُبلغ عن البيانات، إلا إذا وصف عقدٌ صراحةً قياسًا يجريه LogBrew.

تحليلات المنتج

المصطلح	المعنى
الحدث (Event)	نشاط منتج مصنّف له اسم ثابت ودقيق.
خاصية (Property)	مفتاح سياق يُستخدم لوصف الحدث أو تصفيته.
جلسة (Session)	زيارة أو جلسة في التطبيق، وليست شخصًا.
مجموعة نموذجية (Cohort)	مجموعة محدودة تحددها معايير دقيقة.
قمع التحويل (Funnel)	خطوات مرتبة تُستخدم لقياس التقدم أو التحويل.
الاحتفاظ بالمستخدمين (Retention)	سلوك العودة، مقيسًا بفترة ومقام صريحين.
المسارات (Paths)	رحلات الجلسات قبل حدث مختار أو بعده.
دورة الحياة (Lifecycle)	تصنّف الكيانات معروفة الهوية في كل فترة إلى: جديد ضمن التاريخ المرصود، أو عائد، أو مستعاد، أو خامل.
جديد ضمن التاريخ المرصود (New in observed history)	نشط دون حدث مختار سابق ضمن نافذة التاريخ المرصود المحدودة. ولا يعني عميلًا جديدًا لأول مرة.

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

​قابلية الملاحظة والمراقبة

​وكلاء الذكاء الاصطناعي

​إشارات قابلية الملاحظة

​التحقيق في المشكلات

​الهوية والارتباط

​النطاق وجودة البيانات

​القياسات والوقت

​حالات الأدلة

​تحليلات المنتج