مرجع LogBrew CLI: الأوامر وعوامل التصفية

تقرأ واجهة سطر الأوامر LogBrew CLI مفتوحة المصدر بيانات القياس عن بُعد وتدير بيانات الحساب من الطرفية. ابدأ من إرشادات استخدام CLI للتثبيت وتسجيل الدخول والمهام الشائعة.

كيف يعمل CLI

استخدم النص المقروء في الطرفية. واستخدم --json في البرامج النصية ووكلاء البرمجة. تسجيل الدخول بالحساب ضروري لقراءات الحساب. قبل أن تبدأ تسجيل الدخول، شغّل logbrew status --json. يجب أن يُكمل شخص التفويض في المتصفح. مفاتيح الاستيعاب الخاصة بالمشاريع ترسل بيانات القياس عن بُعد، ولا تحل محل تسجيل الدخول بالحساب. إنشاء المشاريع وإنشاء المفاتيح وتغيير حالة المشكلات وأولويتها والمسؤول عنها، وعمليات النشر وتحديثات الدعم، كلها تغيّر بيانات الحساب. قبل أن تشغّل أيًّا منها، تأكد من صحة الإجراء والهدف. شغّل logbrew --help لترى كل الأوامر. أضف --help إلى أمر، مثل logbrew read logs --help، لترى خياراته. شغّل logbrew help json لقواعد JSON.

مجموعة الأوامر	الغرض
`login`، `whoami`، `me`، `logout`	بدء تسجيل الدخول، أو قراءة هوية الحساب، أو إغلاق الجلسة المحلية.
`status`، `health`، `doctor`، `version`، `examples`	قراءة الوصول، أو جاهزية المشروع، أو إصدار CLI، أو أمثلة التشغيل الأول.
`setup`	قراءة ملفات البيان المحلية وطباعة خطة إعداد الـ SDK. لا يغيّر الملفات ولا يشغّل أمر التثبيت.
`projects`	قراءة قائمة المشاريع النشطة.
`projects repositories`	قراءة المستودعات المتصلة، أو اكتشاف المكوّنات في مستودع واحد.
`projects create`، `projects keys create`	إنشاء مشروع، أو إنشاء مفتاح استيعاب لمشروع موجود.
`projects setup`	تدوين الإعداد المرصود لمشروع موجود.
`projects archive`، `projects delete`	أرشفة مشروع، أو حذفه نهائيًا بعد التأكيد.
`usage`، `account usage`	قراءة الاستخدام والحدود وحالة الحصة وتواريخ إعادة الضبط.
`mcp grants`، `mcp revoke`	عرض عملاء MCP المتصلين بحسابك بأسمائهم، أو إبطال اتصال واحد.
`read`	قراءة السجلات أو المشكلات أو الإجراءات أو الإصدارات أو المقاييس أو التتبّعات أو عنصر واحد.
`explain`	قراءة أدلة محدودة لمشكلة أو سجل أو إجراء أو تتبّع أو Span أو مقياس أو إصدار.
`investigate issue`	قراءة أدلة تحقيق المشكلة، أو التحقق من عملية نشر مرشّحة.
`issues archive`، `issues resolve`، `issues reopen`	ضبط حالة مشكلة واحدة، أو حتى 100 مشكلة في مشروع واحد.
`issues priority`	ضبط أولوية مشكلة واحدة، أو حتى 100 مشكلة في مشروع واحد.
`issues assign`، `issues unassign`	ضبط المسؤول عن مشكلة واحدة أو إزالته، حسابًا كان أو فريقًا، أو عن حتى 100 مشكلة في مشروع واحد.
`issues assignees`	عرض الحسابات والفرق التي يمكن إسناد المشكلات إليها في مشروع واحد.
`issues owners`	عرض المالكين المقترحين لمشكلة واحدة.
`issues ownership`	قراءة قواعد الملكية وملف CODEOWNERS لمشروع واحد، أو ضبطها.
`issues activity`	قراءة تاريخ التغييرات لمشكلة واحدة.
`issues rule`، `logs rule`	ضبط قاعدة الخطورة لمشكلة واحدة أو لبصمة سجل واحدة.
`inbox`	قراءة المشكلات التي أسندها آخرون إليك أو إلى فرقك، أو وضع علامة مقروءة عليها.
`set issue`، `resolve`، `close`، `ignore`، `reopen`	ضبط حالة مشكلة واحدة. `close` تعني `resolved`. و`ignore` و`ignored` تعنيان `archived`.
`deploy`	تدوين عملية نشر واحدة مكتملة.
`debug-artifacts`	رفع ملفات التصحيح الأصلية لـ Apple أو Android، أو البحث عن هوية صورة (image) واحدة.
`analytics`	قراءة النظرة العامة أو الخصائص أو المقارنات أو المسارات أو قمع التحويل أو الاحتفاظ بالمستخدمين أو دورة الحياة.
`support`	إنشاء تذاكر الدعم أو قراءتها أو الرد عليها أو إغلاقها أو إعادة فتحها.
`watch`	بث السجلات أو المشكلات أو الإجراءات مباشرةً.

اقرأ تقرير تشخيص المشروع (doctor)

استخدم معرّف مشروع من logbrew projects --json:

logbrew doctor --project "<project_id>" --json

يقرأ الأمر حالة المشروع وسجلًا حديثًا واحدًا. ولا ينشئ مشروعًا، ولا يغيّر مفتاحًا، ولا يدوّن إعدادًا. يحتوي التقرير على status وchecks وnext. ويحتوي كل فحص على check وstatus وnext. الفحوص هي api وauth وproject وingest_key وsetup وtelemetry وlogs. رمز الخروج 0 يعني أن CLI كتب تقريرًا. ولا يعني أن المشروع جاهز. اقرأ قيمة status في التقرير وكل فحص. الفحص الذي قيمته not_checked لم ينجح.

قيمة `status` في التقرير	المعنى والخطوة التالية
`auth_invalid`	وصول الحساب مفقود أو غير صالح. يشغّل شخص `logbrew login`.
`project_missing`	لا يستطيع هذا الحساب الوصول إلى المشروع. استخدم معرّفًا من `logbrew projects --json`.
`api_unreachable`	لم يكتمل طلب API. افحص اتصال الشبكة، ثم شغّل الأمر مرة أخرى.
`check_failed`	فشل طلب أو كانت استجابته غير صالحة. شغّل الأمر مرة أخرى دون تغييرات. إذا فشل مرة أخرى، فأبلغ عن مشكلة.
`needs_ingest_key`	ليس للمشروع مفتاح استيعاب نشط. لا تنشئ مفتاحًا إلا إذا كانت لديك صلاحية تغيير المشروع.
`needs_setup`	إعداد الـ SDK ضروري. اتّبع البدء السريع.
`needs_telemetry`	بدأ الإعداد، لكن ليس لدى LogBrew بيانات قياس عن بُعد للمشروع. أرسل حدثًا تجريبيًا.
`ready`	للمشروع مفتاح نشط وبيانات قياس عن بُعد. اقرأ الإشارة التي تحتاجها مهمتك.

عندما تنجح قراءة المشروع، تكون نتيجة الفحص logs هي visible أو empty أو unavailable أو error أو invalid_response. لا يغيّر هذا الفحص قيمة status في التقرير. نتيجة السجلات الفارغة لا تقول شيئًا عن الإشارات الأخرى. والقراءة الفاشلة ليست نتيجة فارغة. استخدم next كإرشاد للتعافي. ولا يمنحك صلاحية تغيير حالة الحساب أو المشروع.

مثال: وصول الحساب مفقود

دون بيانات اعتماد الحساب، لا يرسل الأمر أي طلب API. ويكتب هذا التقرير إلى المخرجات القياسية ويخرج بالرمز 0:

{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}

يختلف هذا التقرير عن تشخيص المشروع عبر API. ولا يحتوي على حقول API state أو setup_status أو next_action.

عوامل التصفية

عامل التصفية	الأوامر
`--project <project_id>`	logs، issues، actions، releases، metrics، traces، trace
`--release <release>`	logs، issues، actions، releases، metrics، traces، trace
`--environment <environment>`	logs، issues، actions، releases، metrics، traces، trace
`--service <service_name>`	logs، issues، actions، releases، metrics، traces
`--since 24h`	logs، issues، actions، releases، metrics، traces، analytics
`--until <RFC3339>`	logs، issues، actions، releases، metrics، traces، analytics
`--limit 100`	logs، issues، actions، releases، metrics، traces
`--severity error`	logs، watch
`--search checkout`	logs
`--trace <trace_id>`	logs
`--status unresolved`	issues (`unresolved`، `resolved`، `archived`)
`--priority high`	issues (`high`، `medium`، `low`)
`--assignee me`	issues (`me` أو `none` أو `my_teams` أو معرّف مستخدم أو `team:<team_id>`)
`--status error`	traces (`error`، `ok`)
`--min-duration-ms <milliseconds>`	traces
`--name <name>`	actions، metrics
`--user <distinct_id>`	actions

يقبل --since مدة مثل 24h أو 7d، أو طابعًا زمنيًا بتنسيق RFC 3339. ويقبل --until طابعًا زمنيًا بتنسيق RFC 3339. وهو وقت نهاية غير مشمول في النطاق، ويجب أن يكون بعد --since. قراءة مشكلة واحدة بمعرّفها لا تقبل --until. خطورة السجل هي info أو warning أو error أو critical. حالة المشكلة هي مرحلتها في سير العمل، لا خطورتها. --status ignored اسم أقدم لـ --status archived. و--status open تعني unresolved، و--status closed تعني resolved. يختار --assignee none المشكلات التي ليس لها مسؤول، ويختار --assignee my_teams مشكلات فرقك. وأي قيمة أخرى لـ --assignee تفشل مع invalid_assignee. يقبل CLI أيضًا هذه الأسماء البديلة: --project-id و--env و--service-name و--trace-id و--distinct-id، و--level بدل --severity. استخدم الأسماء الموجودة في الجدول في البرامج النصية الجديدة. يقرأ هذا الأمر أخطاء يوم واحد:

logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json

يحدد معرّف المشروع المشروعَ. ويحدد اسم الخدمة مكوّنًا داخل ذلك المشروع. ضع علامات اقتباس حول القيم التي تحتوي على مسافات:

logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json

لنص البحث الذي يبدأ بشرطة، ضع -- قبل النص:

logbrew logs --json -- --timeout

اختر حدوثًا للمشكلة

تجمع المشكلة مرات الحدوث المتطابقة. اقرأ المشكلة لمعرفة حالتها وعدد مرات حدوثها ووقتي أول ظهور وآخر ظهور:

logbrew read issue "<issue_id>" --json

استخدم explain issue أو investigate issue لأدلة حدوث واحد. دون --occurrence، يختار LogBrew الحدوث الموصى به. وهو ليس دائمًا أحدث حدث. لقراءة أحدث حدث:

logbrew explain issue "<issue_id>" --occurrence latest --json

يقبل --occurrence أيضًا recommended أو first أو معرّف حدوث أعاده LogBrew. ترفض هذه الأوامر عوامل تصفية المشروع والإصدار والبيئة والوقت. قبل أن تقارن الأدلة، اقرأ الطابع الزمني للحدوث المختار. راجع التحقيق في مشكلة لمعرفة حقول الأدلة.

غيّر حالة المشكلة وأولويتها

استخدم معرّف مشكلة واحدًا لتغيير مشكلة واحدة:

logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json

يضبط archive القيمة archived، ويضبط resolve القيمة resolved، ويضبط reopen القيمة unresolved. الأولوية هي high أو medium أو low. الأولوية التي تضبطها بنفسك تبقى ثابتة. وإلا فإن الأولوية تتبع خطورة المشكلة. لتغيير أكثر من مشكلة واحدة، أضف --project. يجب أن تكون كل المشكلات في ذلك المشروع. يغيّر الأمر الواحد حتى 100 مشكلة:

logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json

تحتوي النتيجة على إدخال واحد لكل مشكلة. كل إدخال هو updated أو unchanged أو not_found. المشكلة unchanged كانت لها القيمة المطلوبة بالفعل. يمكنك تشغيل الأمر نفسه مرة أخرى بعد فشل في الشبكة. لا تطلب هذه الأوامر تأكيدًا. افحص معرّفات المشكلات أولًا. تعرض قراءات المشكلات وتغييراتها archived بدل ignored، وتعرض priority وpriority_source وassignee لكل مشكلة. راجع استجابة المشكلة.

أسند المشكلات

للمشكلة مسؤول واحد أو لا مسؤول لها، والمسؤول حساب واحد أو فريق واحد. اعرض الحسابات والفرق التي يمكنك الإسناد إليها في مشروع:

logbrew issues assignees --project "<project_id>" --json

أسند مشكلة واحدة إلى حساب، أو إلى نفسك باستخدام me، أو إلى فريق:

logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json

أزل المسؤول:

logbrew issues unassign "<issue_id>" --json

أضف --project لتغيير حتى 100 مشكلة في ذلك المشروع، كما في الحالة والأولوية. يجب أن يستطيع الحساب قراءة المشروع، ويجب أن يتبع الفريق مؤسسة المشروع. للعثور على المشكلات المُسندة إليك أو إلى فرقك:

logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json

تعرض المخرجات النصية اسم المسؤول، أو team #<slug> للفريق. إذا لم يكن للحساب اسم، فتعرض عنوان البريد الإلكتروني، ثم معرّف المستخدم. المشكلة التي ليس لها مسؤول تعرض unassigned.

المالكون والتاريخ وصندوق الوارد

logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json

يعرض issues owners المالكين المقترحين والأدلة التي فحصها. ويرسل issues ownership set ملفات محلية لا يتجاوز كل منها 128 KiB. والملف الفارغ يمسح نصه. ويقبل issues activity وinbox الخيار --limit من 1 إلى 200، و--cursor-time مع --cursor-id من next_cursor. راجع اعرف مالك المشكلة.

اضبط قواعد الخطورة

logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json

الخطورة هي info أو warning أو error أو critical أو source. وتعيد source عرض الخطورة الملتقَطة. ويخفي --ignore السجلات المطابقة من قائمة السجلات الافتراضية. ودون --ignore، تعرضها القاعدة.

اقرأ الصفحة التالية

تقبل السجلات والمشكلات والإجراءات والمقاييس والتتبّعات ترقيم الصفحات بالمؤشر. أما الإصدارات فلا تقبله. استخدم --pagination cursor للصفحة الأولى:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json

تحتوي الاستجابة على logs وnext_cursor. وتحتوي قيمة next_cursor غير الفارغة على time وid. أرسلهما باستخدام --cursor-time و--cursor-id:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json

أبقِ عوامل التصفية والحد نفسها في كل صفحة. توقف عندما تكون قيمة next_cursor هي null. استخدم المؤشر، لا عدد الصفوف، لتعرف هل توجد صفحات أخرى. قد تكون الصفحة الأخيرة فارغة:

{
  "logs": [],
  "next_cursor": null
}

تستخدم المشكلات والإجراءات والمقاييس الشكل نفسه، مع issues أو actions أو metrics مكان logs.

المتابعة المباشرة

يبث logbrew watch --json السجلات والمشكلات والإجراءات مباشرةً. أضف logs أو issues أو actions لبث نوع واحد. tail وfollow وstream أسماء بديلة لـ watch. لا تدعم المتابعة التتبّعات أو الـ Spans. تحتاج المتابعة إلى --json. ومن دونه، يكتب الأمر watch streams JSON for agents ويخرج بالرمز 1. تعرض أحداث المشكلات في المتابعة المشكلةَ المؤرشفة على أنها ignored، دون أولوية. اقرأ المشكلة لتعرف حالتها وأولويتها الحاليتين. لا تقبل المتابعة إلا --severity، مثل --severity error,critical. ولا يقبل logbrew watch actions الخيار --severity. يطبّق CLI عامل التصفية هذا بعد أن يستلم الأحداث، ولا يقلّل ما يرسله الخادم. ليس للمتابعة عامل تصفية للمشروع أو الإصدار أو البيئة أو الوقت. لعوامل التصفية هذه، استخدم أمر read. بعد انقطاع مؤقت للاتصال، ينتظر CLI ثم يعيد الاتصال.

اقرأ النتائج والأخطاء

ضع --json قبل الأمر أو بعده. اقرأ رمز الخروج قبل أن تستخدم المخرجات. لا تحلّل المخرجات المخصصة للقراءة البشرية، فقد تتغير بين الإصدارات.

رمز الخروج	المعنى
`0`	نجاح. يكون JSON في المخرجات القياسية.
`1`	فشل الأمر أثناء تشغيله، مثل خطأ API أو خطأ في الشبكة.
`2`	رفض CLI الأمر قبل تشغيله.

تحافظ مخرجات النجاح على شكل استجابة API. وقد تكون مصفوفة أو كائنًا. دون ترقيم الصفحات بالمؤشر، تعيد قراءة السجلات مصفوفة. المصفوفة الفارغة تعني أنه لا توجد سجلات مطابقة. وهي ليست خطأً. تذهب الأخطاء إلى الخطأ القياسي. الاستثناء هو debug-artifacts --json، الذي يكتب الأخطاء إلى المخرجات القياسية. يحتوي خطأ JSON على ok وerror وmessage وnext. استخدم error كرمز فشل ثابت. افحص next قبل أن تشغّل الأمر الذي يقترحه. مثلًا، يخرج logbrew watch traces --json بالرمز 2 ويكتب:

{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}

ويخرج logbrew read logs --limit 0 --json بالرمز 2 ويكتب:

{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}

صحّح القيمة وشغّل الأمر مرة أخرى. الأمر المرفوض ليس نتيجة فارغة. راجع أخطاء API لأخطاء HTTP، ومرجع Telemetry API لطلبات API المباشرة.

​كيف يعمل CLI

​اقرأ تقرير تشخيص المشروع (doctor)

​مثال: وصول الحساب مفقود

​عوامل التصفية

​اختر حدوثًا للمشكلة

​غيّر حالة المشكلة وأولويتها

​أسند المشكلات

​المالكون والتاريخ وصندوق الوارد

​اضبط قواعد الخطورة

​اقرأ الصفحة التالية

​المتابعة المباشرة

​اقرأ النتائج والأخطاء