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

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

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

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

اختر المسار وطريقة HTTP من جدول نقاط النهاية.
استخدم رمز Bearer الصحيح: رمز Bearer للاستيعاب لعمليات الاستيعاب، ورمز Bearer للحساب لكل ما عدا ذلك.
اختر نطاق المشروع الذي يدعمه المسار. لا توسّع النطاق بعد استجابة فارغة.
أضف فقط مفاتيح الاستعلام التي يقبلها المسار. راجع عوامل تصفية الاستعلام.
أرسل Content-Type: application/json عندما يكون للمسار نص JSON.
اقرأ حالة HTTP ونص الاستجابة قبل أن تعيد المحاولة.
أبقِ رموز Bearer وتذاكر الموجز ونصوص الاستجابات الكاملة خارج السجلات وخارج مطالبات الوكلاء.

نقاط النهاية

الاستيعاب

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

دع الـ SDK يبني دفعات /v1/events. لا تنشئها يدويًا. للغلاف الأصلي، راجع دمج SDK.

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

الطريقة	المسار	الغرض
`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 هذه المسارات ويتحقق من الاستجابة.

الطريقة	المسار	أمر 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، لا مفاتيح استعلام. راجع تحليلات المنتج.

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

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

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

مسارات الاستخدام والحصة والاشتراك وتسجيل الخروج موجودة في Account API.

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

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

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

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

يقبل كل مسار قراءة مفاتيح الاستعلام الخاصة به. الأسماء البديلة السهلة مثل project وtrace وuser ليست مفاتيح استعلام. تعيد مسارات القوائم افتراضيًا مصفوفة مجردة، وتعيد غلاف مؤشر مع pagination=cursor. تعيد قائمة عمليات النشر دائمًا كائن صفحة. راجع عوامل تصفية الاستعلام.

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

تعرض تنسيقات الاستجابة مثالًا واحدًا لكل عائلة استجابات.
تسرد أخطاء API رموز الأخطاء وإجراءات التعافي.

اقرأ 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 شيئًا. احصل على الحسابات التي يمكنك الإسناد إليها من اعرض المسؤولين. أي قيمة أخرى لـ assignee تفشل أيضًا مع 422 وvalidation_failed. الأولوية التي تضبطها بنفسك تبقى ثابتة. ودون أولوية تضبطها بنفسك، تتبع الأولوية خطورة المشكلة: error وcritical تعنيان high، وwarning تعني medium، وinfo تعني low. الحقل الذي له القيمة المطلوبة بالفعل لا يتغير. يمكنك إرسال الطلب نفسه مرة أخرى بعد انتهاء المهلة. انتهاء المهلة لا يثبت أن التغيير لم يحدث. اقرأ المشكلة مرة أخرى قبل أن ترسل تغييرًا مختلفًا.

حدّث مشكلة واحدة

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

الاستجابة هي المشكلة المحدَّثة. راجع أمثلة استجابات حالة المشكلة.

حدّث المشكلات دفعةً واحدة

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

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.

اعرض المسؤولين

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

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. راجع استجابة قائمة المسؤولين. يستطيع أي حساب يقرأ المشروع الحصول على هذه القائمة. إذا كان الحساب لا يستطيع قراءة المشروع، فسيفشل الطلب مع 404 وnot_found. عندما يفقد عضو الوصول إلى المشروع، تظهر المشكلات المُسندة إليه دون مسؤول. إذا استعاد العضو الوصول، فستُظهره المشكلات مرة أخرى، ما لم يغيّر أحد المسؤول أو يزله في الأثناء.

الملكية والمالكون المقترحون

يُرجع 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، وهو الافتراضي، لا يعرض إلا الحسابات.

تاريخ المشكلة

يُرجع 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 لقراءة الصفحة التالية.

الإشعارات

يُرجع 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.

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

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

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

​الاستيعاب

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

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

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

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

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

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

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

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

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

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

​حدّث مشكلة واحدة

​حدّث المشكلات دفعةً واحدة

​اعرض المسؤولين

​الملكية والمالكون المقترحون

​تاريخ المشكلة

​الإشعارات

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

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

نقاط النهاية

الاستيعاب

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

عمليات النشر

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

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

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

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

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

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

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

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

حدّث مشكلة واحدة

حدّث المشكلات دفعةً واحدة

اعرض المسؤولين

الملكية والمالكون المقترحون

تاريخ المشكلة

الإشعارات

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