استكشاف أخطاء التطبيق وإصلاحها عند فقدان سجلاته

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

أضف --json لسير عمل الوكلاء. الفحص الفاشل يعيد حقل next ثابتًا.

ابدأ بالفحوص السريعة

العَرَض	الفحص الأول	الخطوة التالية
لم يسجّل CLI الدخول	`logbrew status --json`	يشغّل شخص `logbrew login`.
مشروع مفقود	`logbrew projects --json`	استخدم معرّفًا من قائمة المشاريع.
حالة الإعداد غير واضحة	`logbrew doctor --project "<project_id>" --json`	اتّبع قيمة `next` المُعادة.
السجلات فارغة	اقرأ السجلات للمشروع والنطاق الزمني المحددين تمامًا	افحص أنواع الإشارات الأخرى كلًّا على حدة.
النتائج واسعة أكثر من اللازم	أضف عوامل تصفية للمشروع والخدمة والإصدار والبيئة	أبقِ النطاق نفسه في كل قراءة.
تتبّع مفقود	اقرأ تفاصيل المشكلة	لا تقرأ تتبّعًا إلا عندما تحتوي الاستجابة على معرّف تتبّع.
إطارات JavaScript تعرض الشيفرة المبنية	افحص زوج البناء وخريطة المصدر	اتّبع خرائط المصدر لـ JavaScript.
وكيل MCP لا يستطيع قراءة مشروع	افحص المشاريع المعتمدة	اتّبع مشكلات اتصال MCP.

استعِد أول بيانات قياس عن بُعد مفقودة

شغّل أوامر القراءة فقط هذه قبل أن تغيّر إعدادات الـ SDK:

logbrew version --json
logbrew status --json
logbrew projects --json
logbrew doctor --project "<project_id>" --json

يفحص logbrew doctor الوصول إلى API والمصادقة والمشروع ومفتاح الاستيعاب والإعداد وبيانات القياس عن بُعد وظهور السجلات. ولا يغيّر المشروع. اقرأ قيمة status العامة وكل فحص في تقرير التشخيص (doctor). رمز الخروج 0 لا يعني أن كل الفحوص نجحت.

حالة التشخيص	الخطوة التالية
`needs_ingest_key`	أنشئ مفتاح استيعاب خاصًا بالمشروع. راجع تدوير مفتاح الاستيعاب.
`needs_setup`	أكمل إعداد الـ SDK. راجع دمج SDK.
`needs_telemetry`	أرسل حدثًا تجريبيًا آمنًا واحدًا من التطبيق، ثم شغّل أداة التشخيص مرة أخرى.
`ready`	اقرأ السجلات أو المشكلات أو الإصدارات أو التتبّعات الحديثة.

قد تكون حالة التقرير أيضًا auth_invalid أو project_missing أو api_unreachable أو check_failed. يقدّم تقرير التشخيص الخطوة التالية لكل حالة منها. قد لا يحتوي المشروع الذي حالته ready على سجلات، لأن كل نوع إشارة منفصل. قد تكون نتيجة الفحص logs هي empty أو unavailable. القراءة الفاشلة للسجلات ليست نتيجة فارغة.

أرسل حدثًا تجريبيًا آمنًا واحدًا

أرسل سجلًا تجريبيًا واحدًا برسالة فريدة من الـ SDK المثبّت. لا تضمّن رمزًا مميزًا أو بيانات مستخدم أو نص طلب. دوّن معرّف المشروع والخدمة والبيئة والإصدار ووقت البدء بتوقيت UTC وإصدار الـ SDK. انتظر التسليم، ثم اقرأ نطاقًا زمنيًا قصيرًا في المشروع نفسه. لا ترسل أحداثًا تجريبية أخرى ما دام التسليم معلّقًا.

اعثر على السجلات المفقودة

اقرأ نطاقًا صغيرًا ومحددًا تمامًا أولًا:

logbrew read releases --project "<project_id>" --environment production --json
logbrew read logs --project "<project_id>" --environment production \
  --release checkout@1 --since 1h --limit 20 --json

افحص هذه البنود بالترتيب:

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

إذا بقي الحدث مفقودًا، فأزل عامل تصفية واحدًا في كل مرة:

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

توقف عندما يظهر الحدث. آخر عامل تصفية أزلته لا يطابق إعدادات التطبيق. لا تقرأ كل المشاريع بدل المشروع المضبوط.

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

صفحة النتائج ليست المجموع الكلي. مع --pagination cursor، تابع باستخدام next_cursor المُعاد، وأبقِ عوامل التصفية نفسها. راجع ترقيم الصفحات بالمؤشر.

افحص عرض لوحة التحكم

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

افحص المشكلات والتتبّعات

استخدم معرّف مشكلة أو معرّف تتبّع أعاده LogBrew. لا تختلق معرّفًا أبدًا.

logbrew read issues --project "<project_id>" --environment production \
  --status unresolved --since 24h --json
logbrew read issue "<issue_id>" --json
logbrew read trace "<trace_id>" --project "<project_id>" --json
logbrew read logs --trace "<trace_id>" --project "<project_id>" --json

يقبل --status القيم unresolved وresolved وarchived. وتختار القيمة ignored المشكلات نفسها التي تختارها archived. حالة المشكلة وحالة التتبّع مختلفتان. لقيم حالة التتبّع not_linked وnot_found وunavailable معانٍ مختلفة. راجع التحقيق في مشكلة لمعرفة كل قيمة. اقرأ المشكلة وسجلاتها قبل أن تحلّها أو تؤرشفها أو تعيد فتحها.

تعامل مع أخطاء CLI وAPI

في وضع JSON، يحتوي خطأ CLI على ok وerror وmessage وnext:

{
  "ok": false,
  "error": "not_logged_in",
  "message": "not logged in: run logbrew login",
  "next": "run logbrew login"
}

عندما يعيد API خطأً، تكون قيمة error هي api_error. ويحتوي الخطأ أيضًا على status (حالة HTTP) وapi_code (قيمة code من API) وapi_error وapi_next. وفي خطأ rate_limited، يحتوي أيضًا على retry_after_seconds. لا يعيد CLI المحاولة تلقائيًا.

الحالة أو الخطأ	التعافي
`not_logged_in` أو HTTP `401`	يشغّل شخص `logbrew login`. ثم أعد محاولة القراءة.
HTTP `403`	استخدم بيانات الاعتماد الصحيحة للمشروع. يحتاج تغيير المشكلة أيضًا إلى صلاحية إدارة المشكلات في المشروع. لا تعرض قيمة بيانات الاعتماد.
HTTP `404`	استخدم معرّف مشروع أو مشكلة أو تتبّع حاليًا من استجابة.
HTTP `422`	صحّح الحقل المذكور.
HTTP `429` مع `rate_limited`	انتظر `retry_after_seconds`، ثم أعد المحاولة مرة واحدة.
HTTP `429` مع رمز آخر	أوقف إعادات المحاولة التلقائية. اتّبع `api_next`.
HTTP `5xx`	انتظر، وأعد محاولة قراءة واحدة، وأبلغ عن المشكلة إذا استمرت.

راجع أخطاء API لمعرفة كل رمز خطأ.

أمّن حسابًا مخترقًا

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

حافظ على أمان استكشاف الأخطاء وإصلاحها

استخدم بيانات اعتماد وصول الحساب لقراءات CLI. واستخدم بيانات اعتماد استيعاب خاصة بالمشروع لكتابات الـ SDK فقط. لا تضع الرموز المميزة أو ترويسات التفويض أو السجلات الخام أو بيانات العملاء أو نصوص الطلبات أو المسارات المحلية أو الشيفرة المصدرية في أمر أو محادثة أو تذكرة دعم. قبل أن تبلّغ عن مشكلة، كرّر قراءة واحدة بأصغر نطاق ما زال يفشل. دوّن الأمر دون قيم بيانات الاعتماد، ورمز الخطأ، ومعرّف المشروع، وقيم عوامل التصفية. إذا لم تحلّ الفحوص المشكلة، فأبلغ عن مشكلة.

صفحات ذات صلة

البدء السريع

أرسل أول حدث آمن واقرأه.

استخدام CLI

استخدم عوامل تصفية دقيقة ومخرجات JSON.

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

اقرأ أدلة المشكلة قبل أن تغيّر حالتها.

أخطاء API

تعافَ من كل رمز خطأ.

البدء

المفاهيم

التثبيت والإرسال

التحقيق

CLI والوكلاء

الدعم

استكشاف أخطاء التطبيق وإصلاحها عند فقدان سجلاته

ابدأ بالفحوص السريعة

استعِد أول بيانات قياس عن بُعد مفقودة

أرسل حدثًا تجريبيًا آمنًا واحدًا

اعثر على السجلات المفقودة

افحص عرض لوحة التحكم

افحص المشكلات والتتبّعات

تعامل مع أخطاء CLI وAPI

أمّن حسابًا مخترقًا

حافظ على أمان استكشاف الأخطاء وإصلاحها

صفحات ذات صلة

البدء السريع

استخدام CLI

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

أخطاء API

​ابدأ بالفحوص السريعة

​استعِد أول بيانات قياس عن بُعد مفقودة

​أرسل حدثًا تجريبيًا آمنًا واحدًا

​اعثر على السجلات المفقودة

​افحص عرض لوحة التحكم

​افحص المشكلات والتتبّعات

​تعامل مع أخطاء CLI وAPI

​أمّن حسابًا مخترقًا

​حافظ على أمان استكشاف الأخطاء وإصلاحها

​صفحات ذات صلة

البدء السريع

استخدام CLI

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

أخطاء API

ابدأ بالفحوص السريعة

استعِد أول بيانات قياس عن بُعد مفقودة

أرسل حدثًا تجريبيًا آمنًا واحدًا

اعثر على السجلات المفقودة

افحص عرض لوحة التحكم

افحص المشكلات والتتبّعات

تعامل مع أخطاء CLI وAPI

أمّن حسابًا مخترقًا

حافظ على أمان استكشاف الأخطاء وإصلاحها

صفحات ذات صلة