> ## 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 وفحص الإشارات

> أعدّ مشروعًا في LogBrew. اختر أسماء الخدمات والبيئات، واقرأ حالة الإعداد، وابحث عن الأحداث التجريبية من تطبيقك.

المشروع هو حدّ الوصول إلى بيانات القياس عن بُعد. تنتمي كل إشارة مقبولة إلى مشروع
واحد، ويمكن لكل أمر قراءة أن يصفّي النتائج حسب المشروع.

استخدم مشروعًا منفصلًا عندما تحتاج بيانات القياس عن بُعد إلى حدّ ملكية أو وصول
منفصل. وهذا يعني لدى أغلب الفرق تطبيقًا واحدًا أو خدمة واحدة أو مجالًا واحدًا من
المنتج. لا يلزم أن يطابق المستودع مشروعًا واحدًا. فقد يرسل مستودع موحّد
(monorepo) عدة خدمات إلى مشروع واحد. استخدم أسماء الخدمات للتمييز بينها.

## <span id="project-service-environment">المشروع والخدمة والبيئة</span>

| المصطلح | مثال | استخدمه لـ |
| - | - | - |
| المشروع | `checkout-platform` | الملكية والوصول. |
| الخدمة | `checkout-api` | التطبيق أو الخدمة التي أرسلت الإشارة. |
| البيئة | `production` | سياق التشغيل. |
| الإصدار | `api@1.2.3` | إصدار الشيفرة. |

## <span id="recommended-model">إعداد مشروع</span>

[ثبّت الـ CLI](/ar/guides/cli). شغّل `logbrew status --json` لقراءة صلاحيات
الوصول في حسابك. إذا لم يكن الوصول صالحًا، يشغّل شخص `logbrew login`. ولا يمكن
لمفتاح الاستيعاب الخاص بالمشروع أن يسجّل دخولك.

<Steps>
  <Step title="أنشئ مشروعًا أو اختره">
    اعرض مشاريعك أولًا. لا تنشئ مشروعًا إلا إذا لم يكن موجودًا.

    ```bash theme={null}
    logbrew projects --json
    install -d -m 700 "$HOME/.logbrew"

    logbrew projects create checkout-api \
      --runtime node \
      --environment production \
      --ingest-key-file "$HOME/.logbrew/checkout-api.ingest" \
      --json
    ```

    يكتب الـ CLI مفتاح الاستيعاب في ملف جديد لا يقرؤه إلا مالكه. ولا يطبع المفتاح
    ولا مسار الملف أبدًا. إذا لم تكن النتيجة واضحة، فشغّل الأمر نفسه تمامًا مرة
    أخرى. لا تغيّر اسم المشروع ولا ملف المفتاح. يعيد الـ CLI استخدام هوية طلبه
    المعلّق. وتشرح صفحة [البدء السريع](/ar/quickstart) طريقة قراءة معرّف المشروع
    من النتيجة.

    لمشروع موجود، احفظ حالة الإعداد:

    ```bash theme={null}
    logbrew projects setup "<project_id>" --source cli --environment production --json
    ```

    لإنشاء مفتاح استيعاب آخر لمشروع موجود، استخدم
    `logbrew projects keys create`. وتعرض
    [إرشادات تدوير مفتاح الاستيعاب](/ar/guides/rotate-ingest-key) هذا الأمر.

    لا يعرض `logbrew setup --create-project` إلا المساعدة، ولا ينشئ مشروعًا.
  </Step>

  <Step title="اضبط أسماء الخدمات في الـ SDK">
    استخدم أسماء من مستودعك وعملية النشر لديك، مثل `api` أو `worker` أو `web`
    أو `ios` أو `checkout-api`. اسم الخدمة تسمية، وليس أداة لاختيار المشروع.
    مفتاح الاستيعاب هو الذي يختار المشروع. وتغيير اسم الخدمة لا ينقل الأحداث
    المخزّنة. إذا لم تجد حدثًا، فتحقّق من المشروع ومفتاح الاستيعاب اللذين
    يستخدمهما التطبيق قبل أن تنشئ مشروعًا آخر.
  </Step>

  <Step title="استخدم بيئات قياسية">
    استخدم `production` و`staging` و`preview` و`local`. إذا كانت عملية النشر
    لديك تستخدم أسماء أخرى، فاستخدمها باتساق. لا يمكن أن يحتوي اسم البيئة على
    مسافات أو `/` أو شرطة مائلة عكسية.
  </Step>

  <Step title="أرسل حدثًا تجريبيًا واقرأه">
    اضبط الـ SDK بمفتاح الاستيعاب الخاص بالمشروع، كما تشرح
    [إرشادات دمج SDK](/ar/guides/sdk-ingestion). إنشاء المشروع لا
    يثبّت SDK في تطبيقك. أبقِ المفتاح خارج نظام التحكم بالمصدر. اضبط الخدمة
    والبيئة والإصدار في التطبيق. أرسل حدثًا آمنًا واحدًا، ثم اقرأه:

    ```bash theme={null}
    logbrew read logs --project "<project_id>" --json
    ```

    لكل إشارة قائمتها الخاصة. وقائمة السجلات الفارغة لا تعني أن المشروع لا
    يحتوي على مشكلات أو تتبّعات.

    في لوحة التحكم، اختر المشروع نفسه ونطاقًا زمنيًا يشمل الحدث التجريبي. تأكد
    من أن عوامل تصفية الخدمة والبيئة والإصدار تطابق الحدث.
  </Step>
</Steps>

## <span id="diagnose-project-setup">تشخيص إعداد المشروع</span>

اقرأ حالة الإعداد باستخدام أداة تشخيص المشروع (doctor). لا تستنتج حالة الإعداد من
الملفات المحلية أو من استعلام سجلات فارغ.

```bash theme={null}
: "${LOGBREW_PROJECT_ID:?set a project UUID}"

logbrew doctor --project "$LOGBREW_PROJECT_ID" --json
```

يُرجع الـ CLI تقريرًا يحتوي على `status` و`checks` و`next`. ورمز الخروج `0` لا
يعني أن كل الفحوص نجحت. اقرأ كل عنصر في `checks`. راجع
[قراءة تقرير تشخيص المشروع](/ar/reference/cli#read-a-project-doctor-report).

### استجابة الـ API المباشرة

يستدعي عملاء الـ API المسار `GET /api/projects/{project_id}/doctor` بمصادقة
الحساب. لا تقبل نقطة النهاية هذه معاملات استعلام ولا نص طلب. لا تستخدم مفتاح
الاستيعاب الخاص بالمشروع لهذه القراءة أبدًا.

تحتوي الاستجابة `200` على هذه المفاتيح: `project_id` و`state` و`setup_status`
و`setup_acknowledged` و`has_active_ingest_key` و`first_telemetry_seen_at`
و`last_seen_at` و`last_signal` و`next` و`next_action`. الطوابع الزمنية بصيغة
RFC3339 أو `null`. و`last_signal` ملخص آمن للعرض، وليس إشارة خامًا.

| `state` | `next_action.code` | `next_action.target` |
| - | - | - |
| `needs_ingest_key` | `create_ingest_key` | `project_ingest_keys` |
| `needs_setup` | `choose_setup_path` | `project_setup` |
| `needs_telemetry` | `send_first_telemetry` | `telemetry_ingest` |
| `ready` | `inspect_recent_telemetry` | `telemetry_reads` |

تفحص أداة التشخيص مفتاح الاستيعاب أولًا. المشروع الذي ليس له مفتاح استيعاب نشط
تكون حالته `needs_ingest_key`، أيًّا كانت حالة إعداده.

تكون قيمة `setup_status` إحدى القيم `created` أو `setup_started` أو `sdk_seen`
أو `first_telemetry_seen` أو `active`. ولا تكون `setup_acknowledged` بالقيمة
`true` إلا مع القيم الثلاث الأخيرة. تعطي `created` الحالة `needs_setup`. وتعطي
`setup_started` و`sdk_seen` الحالة `needs_telemetry`. وتعطي
`first_telemetry_seen` و`active` الحالة `ready`.

| الاستجابة | الخطوة التالية |
| - | - |
| `404`, `code: "not_found"` | المشروع غير الموجود، والمشروع المؤرشف، والمشروع الذي لا يستطيع حسابك قراءته تعطي كلها النتيجة نفسها. اقرأ معرّف المشروع مرة أخرى من `logbrew projects`. لا تجرّب معرّفات أخرى. |
| `405`, `code: "method_not_allowed"` | استخدم `GET` دون نص طلب ودون معاملات استعلام. |

إذا استمر فشل القراءة، [فأبلغ عن مشكلة](/ar/guides/report-a-problem). لا تُدرج
بيانات الاعتماد أو الترويسات أو نصوص الإشارات أو بيانات العملاء أو المسارات
المحلية أو الشيفرة المصدرية.

## <span id="archive-or-delete-a-project">أرشفة مشروع أو حذفه</span>

أرشف المشروع لإزالته من قائمة المشاريع النشطة:

```bash theme={null}
logbrew projects archive "<project_id>" --yes --json
```

يتطلب الأمر `--yes`. بعد الأرشفة، تتوقف مفاتيح الاستيعاب الخاصة بالمشروع عن
قبول بيانات قياس جديدة. مسار الـ API هو `DELETE /api/projects/{project_id}`.
ويُرجع `204` دون نص. اعرض المشاريع المؤرشفة باستخدام
`GET /api/projects/archived`. واستعد مشروعًا باستخدام
`POST /api/projects/{project_id}/restore`، الذي يُرجع `204` أيضًا.

لا تحذف المشروع نهائيًا إلا عندما تكون متأكدًا:

```bash theme={null}
logbrew projects delete "<project_id>" --confirm "<project_id>" --json
```

كرّر معرّف المشروع نفسه تمامًا بعد `--confirm`. الطلب المقبول يجعل المشروع غير
نشط فورًا ويجدول حذفه النهائي. ولا يمكنك استعادة المشروع بعد ذلك.

## <span id="rotate-an-ingest-key-without-telemetry-loss">تدوير مفتاح الاستيعاب</span>

تشرح [إرشادات تدوير مفتاح الاستيعاب](/ar/guides/rotate-ingest-key) إجراءات
الاستبدال والنشر والاختبار والإبطال.


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