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

# طلبات Telemetry API واستجاباتها ورموز أخطائها

> استخدم API قابلية الملاحظة (Observability) في LogBrew لاستيعاب بيانات القياس عن بُعد والقراءات المحددة النطاق والتحليلات وتحديث المشكلات والأخطاء المقروءة آليًا.

يعمل Telemetry API بتنسيق JSON عبر HTTP على `https://api.logbrew.co`. ترسل حزم
SDK العامة دفعاتها المُدارة إلى `POST /v1/events`. وترسل العملاء الأصلية المخصصة
أغلفة أصلية (native envelopes) إلى `POST /api/telemetry/ingest`. يتطلب مسارا
الاستيعاب كلاهما رمز Bearer للاستيعاب خاصًا بالمشروع.

تستخدم القراءات والتغييرات التي يملكها الحساب رمز Bearer للحساب. لا تستخدم أبدًا
رمز Bearer للحساب أو جلسة متصفح في إعدادات الـ SDK أو الاستيعاب. ولا ترسل أبدًا
رمز Bearer للاستيعاب إلى مسار قراءة.

## أرسل طلبًا محدود النطاق

استخدم قائمة التحقق هذه قبل أن يرسل العميل طلبًا:

1. اختر المسار وطريقة HTTP من جدول نقاط النهاية.
2. استخدم رمز Bearer الصحيح: رمز Bearer للاستيعاب لعمليات الاستيعاب، ورمز
   Bearer للحساب لكل ما عدا ذلك.
3. اختر نطاق المشروع الذي يدعمه المسار. لا توسّع النطاق بعد استجابة فارغة.
4. أضف فقط مفاتيح الاستعلام التي يقبلها المسار. راجع
   [عوامل تصفية الاستعلام](/ar/reference/telemetry-api-filters).
5. أرسل `Content-Type: application/json` عندما يكون للمسار نص JSON.
6. اقرأ حالة HTTP ونص الاستجابة قبل أن تعيد المحاولة.
7. أبقِ رموز Bearer وتذاكر الموجز ونصوص الاستجابات الكاملة خارج السجلات وخارج
   مطالبات الوكلاء.

## نقاط النهاية

### الاستيعاب

| الطريقة | المسار | الغرض |
| - | - | - |
| `POST` | `/v1/events` | استيعاب الدفعات التي تبنيها حزم LogBrew SDK العامة وترسلها. |
| `POST` | `/api/telemetry/ingest` | استيعاب أغلفة بيانات القياس عن بُعد الأصلية من عميل مخصص. |

دع الـ SDK يبني دفعات `/v1/events`. لا تنشئها يدويًا. للغلاف الأصلي، راجع
[دمج SDK](/ar/guides/sdk-ingestion).

### قراءات بيانات القياس عن بُعد

| الطريقة | المسار | الغرض |
| - | - | - |
| `GET` | `/api/logs` | عرض السجلات المنظّمة. |
| `GET` | `/api/logs/{log_id}` | قراءة سجل واحد. |
| `GET` | `/api/logs/attributes` | عرض مسارات سمات السجلات وأنواعها التي يمكن لعامل التصفية البحث فيها. |
| `GET` | `/api/telemetry/issues` | عرض المشكلات المجمّعة. |
| `GET` | `/api/telemetry/issues/{issue_id}` | قراءة مشكلة مجمّعة واحدة. |
| `GET` | `/api/telemetry/issues/{issue_id}/events` | عرض مرات حدوث مشكلة مجمّعة واحدة. |
| `PATCH` | `/api/telemetry/issues/{issue_id}` | تحديث حالة مشكلة واحدة أو أولويتها أو المسؤول عنها. |
| `POST` | `/api/telemetry/issues/bulk` | تحديث حالة 1 إلى 100 مشكلة في مشروع واحد أو أولويتها أو المسؤول عنها. |
| `GET` | `/api/telemetry/issues/assignees` | عرض الحسابات والفرق التي يمكن إسناد المشكلات إليها في مشروع واحد. |
| `GET` | `/api/telemetry/issues/{issue_id}/owners` | عرض المالكين المقترحين لمشكلة واحدة. |
| `GET`، `PUT` | `/api/telemetry/issues/ownership` | قراءة قواعد الملكية ونص CODEOWNERS لمشروع واحد، أو ضبطها. |
| `GET` | `/api/telemetry/issues/{issue_id}/activity` | قراءة تاريخ التغييرات لمشكلة واحدة. |
| `GET` | `/api/telemetry/issues/notifications` | عرض المشكلات التي أسندها آخرون إليك أو إلى فرقك. |
| `POST` | `/api/telemetry/issues/notifications/read` | وضع علامة مقروءة على إشعارات مشكلاتك. |
| `PUT` | `/api/telemetry/issues/{issue_id}/triage-rule` | ضبط قاعدة الخطورة لمشكلة. |
| `PUT` | `/api/logs/{log_id}/triage-rule` | ضبط قاعدة الخطورة وحالة التجاهل للسجلات التي تطابق سجلًا. |
| `GET` | `/api/telemetry/traces` | اكتشاف التتبّعات في نطاق مشروع. |
| `GET` | `/api/telemetry/traces/{trace_id}` | عرض الـ Spans لتتبّع واحد. |
| `GET` | `/api/telemetry/traces/{trace_id}/summary` | قراءة ملخص محدود لتتبّع واحد. |
| `GET` | `/api/telemetry/actions` | عرض إجراءات المنتج. |
| `GET` | `/api/telemetry/metrics` | عرض عيّنات المقاييس. |
| `GET` | `/api/telemetry/metrics/series` | قراءة مقياس واحد كفواصل زمنية. |
| `GET` | `/api/telemetry/releases` | عرض ملخصات الإصدارات. |
| `GET` | `/api/telemetry/summary/volume` | قراءة أعداد الإشارات لمشروع واحد كفواصل زمنية. |

### عمليات النشر

| الطريقة | المسار | أمر CLI |
| - | - | - |
| `PUT` | `/api/telemetry/deployments/{deployment_id}` | `logbrew deploy` |
| `GET` | `/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>` | لا يوجد |
| `GET` | `/api/telemetry/deployments?project_id=<project-uuid>` | لا يوجد |

دوّن عملية النشر من أتمتة الإصدار بعد نجاحها أو فشلها. يحتوي نص `PUT` على
`project_id` و`release` و`environment` و`service_name` و`status`
(`succeeded` أو `failed`) و`started_at` و`finished_at` و`commit_sha` اختياري.
استخدم قيم `release` و`environment` و`service_name` نفسها التي يرسلها الـ SDK.
يجب أن يملك الحساب المشروع.

`deployment_id` معرّفك الخاص لعملية النشر. إعادة المحاولة بالمعرّف نفسه والنص نفسه
تعيد عملية النشر المخزّنة. والمعرّف نفسه مع نص مختلف يفشل مع `409`
و`idempotency_conflict`. استخدم معرّفًا جديدًا لعملية نشر مختلفة.

### عمليات التحقيق

يعيد كل مسار تحقيق حزمة أدلة محدودة لعنصر واحد. يقرأ أمر `logbrew explain` في
[CLI](/ar/reference/cli) هذه المسارات ويتحقق من الاستجابة.

| الطريقة | المسار | أمر CLI |
| - | - | - |
| `GET` | `/api/logs/{log_id}/investigation` | `logbrew explain log` |
| `GET` | `/api/telemetry/issues/{issue_id}/investigation` | `logbrew explain issue` |
| `GET` | `/api/telemetry/issues/{issue_id}/correction-verification` | `logbrew investigate issue <issue_id> verify` |
| `GET` | `/api/telemetry/traces/{trace_id}/investigation` | `logbrew explain trace` |
| `GET` | `/api/telemetry/traces/{trace_id}/spans/{span_id}/investigation` | `logbrew explain span` |
| `GET` | `/api/telemetry/actions/{action_id}/investigation` | `logbrew explain action` |
| `GET` | `/api/telemetry/metrics/investigation` | `logbrew explain metric` |
| `GET` | `/api/telemetry/releases/investigation` | `logbrew explain release` |

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

| الطريقة | المسار | أمر CLI |
| - | - | - |
| `GET` | `/api/telemetry/analytics/overview` | `logbrew analytics overview` |
| `GET` | `/api/telemetry/analytics/properties` | `logbrew analytics properties` |
| `POST` | `/api/telemetry/analytics/funnel` | `logbrew analytics funnel` |
| `POST` | `/api/telemetry/analytics/retention` | `logbrew analytics retention` |
| `POST` | `/api/telemetry/analytics/lifecycle` | `logbrew analytics lifecycle` |
| `POST` | `/api/telemetry/analytics/paths` | `logbrew analytics paths` |
| `POST` | `/api/telemetry/analytics/segments/compare` | `logbrew analytics compare` |

تأخذ مسارات التحليلات `POST` نص JSON، لا مفاتيح استعلام. راجع
[تحليلات المنتج](/ar/concepts/product-analytics).

### الموجز المباشر

| الطريقة | المسار | الغرض |
| - | - | - |
| `POST` | `/api/feed/ticket` | إنشاء تذكرة قصيرة العمر للموجز المباشر باستخدام رمز Bearer للحساب. |
| `GET` | `/api/feed/live?ticket=<ticket>` | فتح اتصال WebSocket بتلك التذكرة. |

### الحساب وتسجيل الدخول

مسارات الاستخدام والحصة والاشتراك وتسجيل الخروج موجودة في
[Account API](/ar/reference/account-api).

## رموز حالة النجاح

| العملية | حالة النجاح |
| - | - |
| الاستيعاب والقراءات وتحديثات المشكلات والقواعد وعمليات النشر والتحليلات وتذاكر الموجز | `200 OK` |
| اتصال الموجز المباشر | `101 Switching Protocols`، ثم رسائل WebSocket |

الاستجابة `200` لا تثبت أن الأدلة كاملة. اقرأ حقول التغطية والاقتطاع والحالة في
الاستجابة.

## عوامل تصفية الاستعلام وترقيم الصفحات

يقبل كل مسار قراءة مفاتيح الاستعلام الخاصة به. الأسماء البديلة السهلة مثل
`project` و`trace` و`user` ليست مفاتيح استعلام. تعيد مسارات القوائم افتراضيًا
مصفوفة مجردة، وتعيد غلاف مؤشر مع `pagination=cursor`. تعيد قائمة عمليات النشر
دائمًا كائن صفحة. راجع
[عوامل تصفية الاستعلام](/ar/reference/telemetry-api-filters).

## الاستجابات والأخطاء

* تعرض [تنسيقات الاستجابة](/ar/reference/telemetry-response-shapes)
  مثالًا واحدًا لكل عائلة استجابات.
* تسرد [أخطاء API](/ar/reference/api-errors) رموز الأخطاء وإجراءات التعافي.

اقرأ `code` قبل الرسالة المخصصة للبشر. استخدم `next_action` لسلوك البرنامج،
و`next` للإرشاد البشري. لا تحلّل صياغة `error` أو `next`.

## حدّث المشكلات

تستخدم هذه الطلبات رمز Bearer للحساب. وهو مختلف عمدًا عن
`LOGBREW_INGEST_BEARER`. يجب أن يملك الحساب صلاحية إدارة المشكلات في مشروع
المشكلة. إن لم يملكها، يفشل الطلب مع `403` و`forbidden`. تغطي الصلاحية نفسها
تغييرات الحالة والأولوية والمسؤول، وقواعد المشكلات والسجلات.

يضبط كل طلب حقلًا واحدًا أو أكثر من هذه الحقول:

| الحقل | القيم |
| - | - |
| `status` | `unresolved` أو `resolved` أو `archived`. و`ignored` اسم أقدم لـ `archived`. |
| `priority` | `high` أو `medium` أو `low`. |
| `assignee` | معرّف مستخدم، أو `me` للحساب المسجَّل الدخول، أو `team:<team_id>` لفريق، أو `none` لإزالة المسؤول. |

الطلب الذي لا يحتوي على أيٍّ من هذه الحقول يفشل مع `422` و`validation_failed`.

للمشكلة مسؤول واحد أو لا مسؤول لها، والمسؤول حساب أو فريق. يجب أن يستطيع الحساب
قراءة المشروع، ويجب أن يتبع الفريق مؤسسة المشروع. وإلا يفشل الطلب مع `422`
و`validation_failed`، ولا يغيّر LogBrew شيئًا. احصل
على الحسابات التي يمكنك الإسناد إليها من [اعرض المسؤولين](#list-assignees). أي
قيمة أخرى لـ `assignee` تفشل أيضًا مع `422` و`validation_failed`.

الأولوية التي تضبطها بنفسك تبقى ثابتة. ودون أولوية تضبطها بنفسك، تتبع الأولوية
خطورة المشكلة: `error` و`critical` تعنيان `high`، و`warning` تعني `medium`،
و`info` تعني `low`.

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

### <span id="update-one-issue">حدّث مشكلة واحدة</span>

أضف `response_version=4` لتحصل على `archived` والأولوية والمسؤول في الاستجابة.
في الإصدار 4، تكون قيمة `assignee` إما
`{ "type": "user", "user_id", "name", "email" }`، أو
`{ "type": "team", "team_id", "slug", "name" }`، أو `null`. ويعرض الإصدار 3
الفريق المسؤول بالقيمة `null`.

```bash theme={null}
curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID?response_version=4" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "archived", "priority": "low", "assignee": "me" }'
```

الاستجابة هي المشكلة المحدَّثة. راجع
[أمثلة استجابات حالة المشكلة](/ar/reference/telemetry-response-shapes#issue-status-response-examples).

### <span id="update-issues-in-bulk">حدّث المشكلات دفعةً واحدة</span>

أرسل `project_id` ومن 1 إلى 100 معرّف مشكلة مختلف من ذلك المشروع:

```bash theme={null}
curl -X POST "$LOGBREW_API_URL/api/telemetry/issues/bulk" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{
    "project_id": "<project-uuid>",
    "issue_ids": ["<issue-uuid-1>", "<issue-uuid-2>"],
    "assignee": "<user-uuid>"
  }'
```

يطبّق الطلب التغيير نفسه على كل مشكلة. تحتوي الاستجابة على `project_id`
و`results`، مع نتيجة واحدة لكل معرّف مشكلة، بترتيب الطلب. لكل نتيجة `issue_id`
و`outcome` و`issue`. قيمة `issue` هي المشكلة الحالية في إصدار الاستجابة 3، أو
`null` في حالة `not_found`. أضف `"response_version": 2` إلى نص الطلب لتحصل على
كل مشكلة بإصدار الاستجابة 4.

| `outcome` | المعنى |
| - | - |
| `updated` | طبّق LogBrew التغيير. |
| `unchanged` | كانت للمشكلة القيم المطلوبة بالفعل. |
| `not_found` | ليس في المشروع مشكلة بهذا المعرّف. لم يغيّر LogBrew شيئًا بشأنها. |

القائمة الفارغة، أو أكثر من 100 معرّف، أو المعرّف المكرر، يفشل مع `422`
و`validation_failed`. قسّم المجموعة الأكبر إلى طلبات أكثر. إذا كان الحساب لا
يستطيع قراءة المشروع، فسيفشل الطلب مع `404` و`not_found`.

### <span id="list-assignees">اعرض المسؤولين</span>

أرسل معرّف المشروع لتحصل على كل حساب يمكن إسناد المشكلات إليه في ذلك المشروع:

```bash theme={null}
curl "$LOGBREW_API_URL/api/telemetry/issues/assignees?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"
```

تحتوي القائمة على كل حساب يستطيع قراءة المشروع. لكل إدخال `user_id` و`name`
و`email`. تكون قيمة `name` هي `null` عندما لا يكون للحساب اسم. أضف
`response_version=2` لتحصل أيضًا على `teams`: كل فريق في مؤسسة المشروع، مع
`team_id` و`slug` و`name`. راجع
[استجابة قائمة المسؤولين](/ar/reference/telemetry-response-shapes#assignee-list-response).
يستطيع أي حساب يقرأ المشروع الحصول على هذه القائمة. إذا كان الحساب لا يستطيع
قراءة المشروع، فسيفشل الطلب مع `404` و`not_found`.

عندما يفقد عضو الوصول إلى المشروع، تظهر المشكلات المُسندة إليه دون مسؤول. إذا
استعاد العضو الوصول، فستُظهره المشكلات مرة أخرى، ما لم يغيّر أحد المسؤول أو يزله
في الأثناء.

### <span id="ownership-and-suggested-owners">الملكية والمالكون المقترحون</span>

يُرجع `GET /api/telemetry/issues/ownership?project_id=<project-uuid>` الحقول
`rules` و`codeowners` و`updated_at` و`unresolved_owners`. يستطيع قراءتها أي حساب
يقرأ المشروع. ويستبدل `PUT` مع `project_id` و`rules` أو `codeowners` أو كليهما ذلك
النص، ويحتاج إلى صلاحية إدارة المشكلات. الحقل الذي لا ترسله يحتفظ بنصه، والسلسلة
الفارغة تمسحه. لا يتجاوز كل نص 128 KiB. والنص غير الصالح يفشل مع `422` ويذكر
السطر.

يُرجع `GET /api/telemetry/issues/{issue_id}/owners?response_version=2` الحقول
`suggested_assignee` و`owners` و`inputs`. لكل مالك `type` (`user` أو `team`)،
و`source` (`ownership_rule` أو `codeowners` أو `recent_activity`)، و`rule`
و`line` و`matched`. والإصدار 1، وهو الافتراضي، لا يعرض إلا الحسابات.

### <span id="issue-history">تاريخ المشكلة</span>

يُرجع `GET /api/telemetry/issues/{issue_id}/activity?response_version=2` الحقل
`activity`، الأحدث أولًا، و`next_cursor`. لكل إدخال `type` (`status` أو
`priority` أو `assigned` أو `unassigned` أو `severity_rule` أو `first_seen`)،
و`value` و`actor_id` و`actor` و`assignee_id` و`assignee` و`team` و`at`. قيمة
`limit` من 1 إلى 200، و50 افتراضيًا. أرسل `cursor_time` و`cursor_id` من
`next_cursor` لقراءة الصفحة التالية.

### <span id="notifications">الإشعارات</span>

يُرجع `GET /api/telemetry/issues/notifications` الحقول `notifications` و`unread`
و`read_at` و`next_cursor`. كل إشعار هو إسناد مشكلة إليك أو إلى فريقك من حساب
آخر. ويحرّك `POST
/api/telemetry/issues/notifications/read` مع كائن JSON فارغ، أو مع `read_at`،
علامة القراءة الخاصة بك. ولا تعود العلامة إلى الوراء أبدًا.

### اضبط قواعد المشكلات والسجلات

تغيّر القاعدة طريقة عرض LogBrew للإشارات المطابقة. ولا تحذف البيانات. تبقى قيمة
`severity` الملتقطة دون تغيير، وتعرض الاستجابة القاعدة في `triage`.

| الطلب | نص JSON |
| - | - |
| `PUT /api/telemetry/issues/{issue_id}/triage-rule` | `{ "severity": "<value>" }` |
| `PUT /api/logs/{log_id}/triage-rule` | `{ "severity": "<value>", "ignored": true }` |

قيمة `severity` هي `info` أو `warning` أو `error` أو `critical` أو `source`.
تزيل `source` التجاوز وتعرض الخطورة الملتقطة مرة أخرى. في قاعدة السجل، يخفي
`ignored: true` السجلات المطابقة من قائمة السجلات الافتراضية. اقرأها باستخدام
`status=ignored` أو `status=all`. تنطبق القاعدة على الإشارات المطابقة المحتفَظ
بها والمستقبلية. أي قيمة أخرى تفشل مع `422` و`validation_failed`.

<Warning>
  لا ترسل إصدارات فارغة. يرفضها LogBrew لتبقى متابعة الإصدارات موثوقة.
</Warning>


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