> ## 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.
# تنسيق استجابات API وأمثلة استجابات JSON
> اقرأ استجابات LogBrew API لقوائم بيانات القياس عن بُعد وصفحات المؤشر والأحداث المباشرة والتغييرات وحالات النجاح والخطأ.
تعرض هذه الصفحة مثالًا واحدًا لكل عائلة استجابات في [Telemetry API](/ar/reference/telemetry-api). كل القيم مصطنعة. لرموز الأخطاء وطرق التعافي، راجع [أخطاء API](/ar/reference/api-errors).
## اقرأ الاستجابة
اقرأ كل استجابة بهذا الترتيب:
1. اقرأ حالة HTTP.
2. تأكد أن للنص الشكل الذي يحدده المسار.
3. تأكد أن كل `project_id` يقع داخل نطاق المشروع المطلوب.
4. أبقِ قيم التعداد (enum) المعيارية والمعرّفات دون تغيير.
5. اتبع `next_action` فقط عندما يدعم العميل قيمتي `code` و`target` الخاصتين به.
6. تعامل مع `null` والحقل المحذوف والقائمة الفارغة على أنها حالات مختلفة.
قد تحتوي الاستجابة `200 OK` على قائمة فارغة. قائمة السجلات الفارغة تعني أنه لم يطابق أي سجل الطلب. ولا تعني أن المشكلات أو التتبّعات أو الإجراءات فارغة أيضًا. لا تربط الإشارات لأن طوابعها الزمنية متقاربة. اتبع تتبّعًا فقط عندما تحتوي الاستجابة على `trace_id` الخاص به تمامًا.
الاستجابة `404` والقائمة الفارغة نتيجتان مختلفتان. يعيد مسار القائمة `[]` عندما لا يطابق أي قيد. ويعيد مسار التفاصيل `404` مع `code: not_found` عندما لا يجد قيدًا يمكن قراءته. لا تثبت أي من النتيجتين أن الاستيعاب فشل.
## ما يجب إرساله
فائدة الاستجابات بقدر فائدة بيانات القياس عن بُعد التي ترسلها. أرسل هذه القيم في كل غلاف أو إعداد SDK:
* `release` و`environment`.
* أسماء ثابتة للخدمات والإجراءات والمقاييس.
* سياق التتبّع عندما تنتمي السجلات والـ Spans والإجراءات والمشكلات إلى الطلب نفسه.
* قيم الخطورة المعيارية: `info` و`warning` و`error` و`critical`.
* سمات تساعد في تصحيح الأخطاء، دون أسرار أو بيانات شخصية غير ضرورية.
راجع [دمج SDK](/ar/guides/sdk-ingestion) و[التحكم في البيانات الملتقطة](/ar/guides/safe-capture).
## استجابة الاستيعاب
تقرأ حزم SDK العامة استجابة `POST /v1/events` نيابةً عنك. لا تحتاج شيفرة التطبيق إلى معالجتها.
### استجابة دفعة SDK
تعيد دفعة SDK الناجحة `200 OK` مع الأعداد المقبولة لكل تدفق:
```json theme={null}
{
"issues": 1,
"logs": 2,
"trace_spans": 3,
"actions": 1,
"metrics": 1,
"already_accepted": 0,
"context_updated": true,
"next": "review accepted telemetry in logs, issues, traces, actions, metrics, or live feed",
"next_action": {
"code": "review_ingested_telemetry",
"target": "telemetry_reads"
}
}
```
| الحقل | المعنى |
| - | - |
| `issues`، `logs`، `trace_spans`، `actions`، `metrics` | الأحداث التي قبلها LogBrew من هذه الدفعة. |
| `already_accepted` | الأحداث التي قبل LogBrew معرّفاتها سابقًا. لا يخزّنها LogBrew مرة أخرى. |
| `context_updated` | `true` عندما تحدّث الدفعة سياق الإصدار أو البيئة. |
تغطي الأعداد هذه الدفعة فقط. إعادة محاولة دفعة قبلها LogBrew سابقًا تعيد `0` لكل تدفق، وعدد الأحداث في `already_accepted`. أبقِ معرّفات الأحداث الأصلية عندما تعيد المحاولة.
### استجابة الغلاف الأصلي
يعيد `POST /api/telemetry/ingest` الاستجابة `200 OK` مع أعداد العناصر المقبولة لكل تدفق:
```json theme={null}
{
"issues": 0,
"logs": 1,
"trace_spans": 0,
"actions": 1,
"already_accepted": 0,
"next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
"next_action": {
"code": "review_ingested_telemetry",
"target": "telemetry_reads"
}
}
```
ليس في الاستجابة الأصلية حقل `metrics` أو `context_updated`. لا تضفهما. يعدّ `already_accepted` العناصر التي قبل LogBrew قيمة `id` الخاصة بها سابقًا لهذا المشروع. راجع [الغلاف الأصلي المباشر](/ar/guides/sdk-ingestion#required-envelope-fields).
### أخطاء الاستيعاب
الاستجابة `401` مع `code: ingest_key_invalid` تعني أن رمز Bearer للاستيعاب مُبطَل أو منتهي الصلاحية أو غير صالح للمشروع. في `POST /v1/events`، يعيد الطلب `401` مع `code: unauthorized` عندما يغيب رمز Bearer أو لا يكون مفتاح استيعاب. استخدم رمز Bearer الحالي للاستيعاب الخاص بالمشروع. لا تُعد المحاولة باستخدام رمز Bearer للحساب.
تعيد دفعة SDK المرفوضة `422` مع `code: validation_failed`:
```json theme={null}
{
"error": "SDK event ids must be unique within a batch",
"code": "validation_failed",
"next": "send release/environment context plus issue, log, span, action, or metric events from a current LogBrew SDK",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
من قيم `error` الأخرى `SDK event batch requires at least one event` و`SDK event type is not supported by this ingest route`. افحص إصدار الـ SDK وإعدادات النقل. لا ترسل دفعة فارغة. لا تغيّر أنواع الأحداث أو معرّفاتها لمجرد أن تجتاز الدفعة التحقق.
الطلب بطريقة غير `POST` يعيد `405` مع `code: method_not_allowed`. ونص JSON غير المقروء يعيد `code: invalid_json`.
## تنسيق استجابة قوائم بيانات القياس عن بُعد
تعيد مسارات القوائم افتراضيًا مصفوفة JSON مجردة. القائمة الفارغة الناجحة هي `[]`.
مع `pagination=cursor`، يعيد المسار غلافًا. يطابق مفتاح المجموعة نوع الإشارة:
| المسار | مفتاح المجموعة |
| - | - |
| `/api/logs` | `logs` |
| `/api/telemetry/issues` | `issues` |
| `/api/telemetry/issues/{issue_id}/events` | `events`، مع `issue_id` في المستوى الأعلى |
| `/api/telemetry/actions` | `actions` |
| `/api/telemetry/metrics` | `metrics` |
| `/api/telemetry/releases` | `releases` |
| `/api/telemetry/traces` | `traces`، مع `naming_quality` في المستوى الأعلى |
`next_cursor` كائن فيه حقول المتابعة، أو `null` في الصفحة الأخيرة. الصفوف مرتبة من الأحدث إلى الأقدم. راجع [ترقيم الصفحات بالمؤشر](/ar/reference/telemetry-api-filters#cursor-pagination).
### استجابة السجل
صفحة مؤشر للسجلات مع `limit=1`:
```json theme={null}
{
"logs": [
{
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"level": "warning",
"severity": "warning",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": false
},
"source": "runtime",
"message": "checkout retry scheduled",
"attributes": { "route": "/checkout" },
"occurred_at": "2026-06-01T12:00:00Z",
"environment": "production",
"release": "api@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
],
"next_cursor": {
"time": "2026-06-01T12:00:00Z",
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d"
}
}
```
تتضمن السجلات `level` للتوافق و`severity` للعرض. يحمل الحقلان كلاهما القيمة المعيارية. ويحمل `triage` نتيجة قاعدة الخطورة. راجع [استجابات قواعد الخطورة](#severity-rule-responses).
يكون `trace_id` و`span_id` بالقيمة `null` عندما لا يكون للسجل رابط تتبّع. عندها تكون قيمة `next_action` هي `inspect_related_logs` والهدف `telemetry_logs`. تستخدم السجلات والمشكلات والإجراءات زوجَي `next_action` نفسيهما.
يعيد `GET /api/logs/{log_id}` سجلًا واحدًا بالشكل نفسه.
### استجابة المشكلة
يعيد `GET /api/telemetry/issues/{issue_id}` مشكلة مجمّعة واحدة. وتعيد القائمة الكائنات نفسها. يستخدم هذا المثال نسخة الاستجابة الافتراضية 1:
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"fingerprint": "payment-error",
"severity": "error",
"triage": {
"effective_severity": "error",
"ignored": false,
"rule_applied": false
},
"title": "PaymentError",
"message": "payment provider timed out",
"stack_trace": null,
"attributes": {},
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
},
"status": "unresolved",
"occurrence_count": 2,
"first_seen_at": "2026-07-13T07:00:00Z",
"last_seen_at": "2026-07-13T08:00:00Z"
}
```
في النسخة 1، قيمة `status` هي `unresolved` أو `resolved` أو `ignored`. للمشكلة المؤرشفة، تكون قيمة `triage.ignored` هي `true`. لأزواج `next_action` والقراءات التي تليها، راجع [التحقيق في مشكلة](/ar/guides/investigate-an-issue).
`first_seen_at` و`last_seen_at` هما وقتا أول حدوث وأحدث حدوث. لا يتغيران عندما تتغير الحالة.
تظهر بعض الحقول فقط عندما تتوفر البيانات لدى LogBrew:
| الحقل | متى يظهر |
| - | - |
| `span_id` | للمشكلة رابط Span. وإلا يُحذف الحقل. |
| `diagnostics` | لأحدث حدوث نوع استثناء أو Breadcrumbs (أحداث قصيرة مسجَّلة قبل وقوع المشكلة). راجع [تاريخ مرات حدوث المشكلة](#issue-occurrence-history). |
| `symbolication` | في `GET /api/telemetry/issues/{issue_id}` فقط، عندما تكون للمشكلة هوية ملف بناء خاصة بالإصدار. راجع [خرائط المصدر لـ JavaScript](/ar/guides/source-maps). |
قيمة `symbolication.status` هي `resolved` أو `invalid_metadata` أو `artifact_not_found` أو `source_not_resolved` أو `unavailable`. لا تعيد القائمة ولا تغييرات الحالة ولا تغييرات القواعد الحقل `symbolication`.
مع `response_version=2`، للمشكلة الحقول نفسها، مع هذه التغييرات:
| الحقل | القيمة في النسخة 2 |
| - | - |
| `status` | `unresolved` أو `resolved` أو `archived`. تعرض النسخة 1 القيمة `archived` على أنها `ignored`. |
| `priority` | `high` أو `medium` أو `low`. |
| `priority_source` | `manual` عندما يضبط شخص الأولوية. `derived` عندما تتبع الأولوية الخطورة الفعلية. |
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "archived",
"severity": "error",
"priority": "low",
"priority_source": "manual"
}
```
يعرض هذا المثال بعض الحقول فقط. الأولوية المشتقة هي `high` لـ `error` و`critical`، و`medium` لـ `warning`، و`low` لـ `info`. وهي تستخدم `triage.effective_severity`، لذلك يمكن لقاعدة خطورة المشكلة أن تغيّرها.
مع `response_version=3`، للمشكلة كل حقول النسخة 2 بالإضافة إلى `assignee`. تكون قيمة `assignee` هي `null` عندما لا يكون للمشكلة مسؤول:
```json theme={null}
{
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "unresolved",
"priority": "high",
"priority_source": "derived",
"assignee": {
"user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"name": "Ada Example",
"email": "ada@example.com"
}
}
```
| الحقل | المعنى |
| - | - |
| `assignee.user_id` | معرّف المستخدم المسؤول. أرسله في `assignee` ضمن عامل تصفية أو تغيير. |
| `assignee.name` | اسم المسؤول، أو `null` عندما لا يكون للحساب اسم. |
| `assignee.email` | عنوان البريد الإلكتروني للمسؤول. |
لا تعرض المشكلة أي مسؤول عندما يفقد العضو المُسند إليه صلاحية قراءة المشروع.
مع `response_version=4`، يحمل `assignee` أيضًا الحقل `type`. المسؤول من نوع `user` له `user_id` و`name` و`email` كما في النسخة 3. والمسؤول من نوع `team` له `team_id` و`slug` و`name`. تعرض النسخة 3 الفريق المسؤول على أنه `null`. يطلب CLI النسخة 4:
```json theme={null}
{
"assignee": {
"type": "team",
"team_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"slug": "payments",
"name": "Payments"
}
}
```
أي قيمة أخرى لـ `response_version` تعيد `422` مع `code: validation_failed`. وتستخدم صفحة المؤشر النسخة نفسها لكل مشكلة في `issues`.
### استجابة قائمة المسؤولين
يعيد `GET /api/telemetry/issues/assignees?project_id=` كل حساب يمكن إسناد المشكلات إليه في المشروع:
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"assignees": [
{
"user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"name": "Ada Example",
"email": "ada@example.com"
},
{
"user_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
"name": null,
"email": "sam@example.com"
}
]
}
```
أضف `response_version=2` لتحصل أيضًا على `teams`: كل فرق مؤسسة المشروع، مع `team_id` و`slug` و`name`.
إذا لم يستطع الحساب قراءة المشروع، يعيد المسار `404` مع `code: not_found`.
### استجابة الإجراء
```json theme={null}
{
"id": "d8ee3a6f-3918-440b-96cb-14166419399a",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "checkout_failed",
"distinct_id": "user_123",
"session_id": "session_456",
"occurred_at": "2026-06-01T12:00:00Z",
"properties": { "surface": "checkout" },
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
```
يتبع `distinct_id` جهة فاعلة واحدة أو جلسة واحدة. تعامل مع `distinct_id` و`session_id` على أنهما معرّفان مبهمان. يكون `session_id` و`trace_id` بالقيمة `null` عندما يكونان مفقودين. ويُحذف `span_id` عندما يكون مفقودًا. ليس للإجراء خطورة. راجع [التقاط أحداث المنتج](/ar/guides/product-events).
### استجابة المقياس
```json theme={null}
{
"id": "6f1c2d3e-4a5b-4c6d-8e7f-901234567890",
"event_id": "metric-1",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "http.server.duration",
"kind": "histogram",
"value": 12.5,
"unit": "ms",
"temporality": "delta",
"attributes": {},
"occurred_at": "2026-07-13T08:00:00Z",
"environment": "production",
"release": "checkout@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
```
كل عنصر عيّنة واحدة. لا تستخدم عدد العيّنات عددًا للأحداث أو المستخدمين. تكون `unit` و`temporality` و`trace_id` و`span_id` بالقيمة `null` عندما تكون مفقودة. القيمة `null` ليست صفرًا.
### استجابة الإصدار
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"release": "api@1.2.3",
"environment": "production",
"service_name": "checkout-api",
"issue_count": 3,
"log_count": 824,
"trace_span_count": 421,
"action_count": 19,
"metric_count": 87,
"first_seen_at": "2026-06-01T12:00:00Z",
"last_seen_at": "2026-06-01T12:15:00Z",
"trace_health": {
"status": "errors_observed",
"trace_count": 42,
"error_trace_count": 3,
"error_rate_basis_points": 714
},
"next_action": {
"code": "inspect_release_issues",
"target": "telemetry_issues"
}
}
```
يغطي الصف الواحد مشروعًا واحدًا وإصدارًا واحدًا وبيئة واحدة وخدمة واحدة. وتصف أعداده هذا الصف فقط.
قيمة `trace_health.status` هي `unknown` عندما لا تكون للصف تتبّعات، وإلا فهي `no_errors_observed` أو `errors_observed`. و`error_rate_basis_points` هي نسبة التتبّعات التي فيها Span خطأ، من `0` إلى `10000`. وهي ليست معدل أخطاء لكل الطلبات.
يشير `next_action` إلى أول نوع إشارة له بيانات، بهذا الترتيب:
| `code` | `target` |
| - | - |
| `inspect_release_issues` | `telemetry_issues` |
| `inspect_release_traces` | `trace_explorer` |
| `inspect_release_logs` | `telemetry_logs` |
| `inspect_release_actions` | `telemetry_actions` |
| `inspect_release_metrics` | `telemetry_metrics` |
| `review_release_telemetry` | `telemetry_reads` |
راجع [الإصدارات](/ar/concepts/releases).
### استجابة اكتشاف التتبّعات
يعيد `GET /api/telemetry/traces?pagination=cursor` صفًا واحدًا لكل تتبّع، بالإضافة إلى إيصال `naming_quality` للصفحة المُعادة:
```json theme={null}
{
"traces": [
{
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"project_ids": ["123e4567-e89b-12d3-a456-426614174000"],
"root_span_name": "POST /checkout",
"root_service_name": "checkout-api",
"root_operation": "http.server",
"span_count": 3,
"error_span_count": 1,
"service_count": 1,
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 45,
"services": ["checkout-api"],
"releases": ["checkout@1.2.3"],
"environments": ["production"],
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
],
"next_cursor": null,
"naming_quality": {
"evaluated_traces": 1,
"meaningful_name_traces": 1,
"generic_name_traces": 0,
"unmatched_route_traces": 0,
"generic_operation_traces": 0,
"truncated": false,
"next_action": null
}
}
```
يغطي `naming_quality` الصفحة المُعادة فقط. وهو ليس درجة على مستوى الحساب كله. `truncated: true` تعني أن هناك صفحة أخرى. عندما يكون في الصفحة اسم عام أو مسار غير مطابق أو عملية عامة، تكون قيمة `next_action` هي `improve_trace_naming` والهدف `sdk_configuration`. ودون `pagination=cursor`، يعيد المسار مصفوفة مجردة من التتبّعات دون `naming_quality`.
يحمل `next_cursor` الحقلين `time` و`trace_id`. أرسلهما في `cursor_time` و`cursor_trace_id`.
يعيد `GET /api/telemetry/traces/{trace_id}` الـ Spans لتتبّع واحد. ويعيد `GET /api/telemetry/traces/{trace_id}/summary` الـ Span الجذري وSpans الأخطاء والخدمات والمدة وأبطأ مسار، دون سمات الـ Spans الخام. الاستجابة `404` للملخص تعني أنه لم يطابق أي تتبّع النطاق الكامل. لا تُعد المحاولة دون عوامل التصفية. راجع [استجابات Spans التتبّع وملخصه](#trace-spans-and-summary-responses).
### القوائم الفارغة والقيود المفقودة
قد لا تكون لقراءة القائمة نتائج مطابقة. أما قراءة التفاصيل فلها عقد مختلف:
| الطلب | النجاح | لا يوجد قيد يمكن قراءته |
| - | - | - |
| `GET /api/logs/{log_id}` | `200` مع [سجل](#log-response) واحد | `404` مع `code: not_found` |
| `GET /api/telemetry/issues/{issue_id}` | `200` مع [مشكلة](#issue-response) واحدة | `404` مع `code: not_found` |
| `GET /api/telemetry/issues/{issue_id}/events` | `200` مع مرات الحدوث | `404` مع `code: not_found` في الصفحة الأولى |
| `GET /api/telemetry/traces/{trace_id}` | `200` مع الـ Spans | `200` مع `[]` |
| `GET /api/telemetry/traces/{trace_id}/summary` | `200` مع ملخص واحد | `404` مع `code: not_found` |
يعيد السجل المفقود هذه الاستجابة `404`:
```json theme={null}
{
"error": "log not found",
"code": "not_found",
"next": "check the resource id or filters and retry",
"next_action": {
"code": "check_resource",
"target": "resource"
}
}
```
تستخدم المشكلة المفقودة `"error": "issue not found"`. ويستخدم ملخص التتبّع المفقود `"error": "trace not found"`. المعرّف غير المعروف والمعرّف الذي لا يستطيع الحساب قراءته يعيدان الاستجابة نفسها.
القائمة التي فيها `project_id` واحد لا يستطيع الحساب قراءته تعيد `200` مع قائمة فارغة. تحقق من معرّف المشروع قبل أن تبلّغ بعدم وجود بيانات.
### تحديدات المشاريع المرفوضة
تقبل قوائم السجلات والمشكلات والإجراءات والمقاييس والإصدارات والتتبّعات مشروعًا واحدًا عبر `project_id`، أو من 2 إلى 50 مشروعًا عبر `project_ids`. ويقبل فهرس سمات السجلات المُحدِّدات نفسها. أما تاريخ مرات حدوث المشكلة فلا يقبلها.
الطلب الذي فيه `project_id` و`project_ids` معًا يعيد `422`:
```json theme={null}
{
"error": "project_id and project_ids are mutually exclusive",
"code": "validation_failed",
"next": "use project_id for one project, project_ids=uuid,uuid for two to fifty projects, or omit both for all readable projects",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
يعيد `project_ids` أيضًا `422` مع `code: validation_failed` عندما يحتوي على UUID غير صالح، أو معرّف مكرر، أو أقل من 2 أو أكثر من 50 معرّفًا.
إذا لم يستطع الحساب قراءة مشروع واحد في مجموعة `project_ids`، يعيد الطلب كله `404`. ولا يعيد المشاريع الأخرى نتيجةً جزئية:
```json theme={null}
{
"error": "project selection not found",
"code": "not_found",
"next": "refresh readable projects and retry with only project IDs you can read",
"next_action": {
"code": "check_resource",
"target": "resource"
}
}
```
اعرض الخطأ، لا قائمة فارغة ولا عددًا صفريًا. اقرأ قائمة المشاريع مرة أخرى. لا تحذف مشروعًا بصمت، ولا تُعد المحاولة عبر كل المشاريع. بيانات الاعتماد المفوَّضة، مثل اتصال MCP (grant)، تعيد `403` مع `code: forbidden` لمشروع خارج نطاق اتصالها. راجع [نطاق المشروع](/ar/reference/telemetry-api-filters#project-scope).
### أخطاء المؤشر
تستخدم السجلات والمشكلات والإجراءات والمقاييس ومرات حدوث المشكلات `cursor_time` و`cursor_id`. يعيد المؤشر المرفوض `422` مع `code: validation_failed`. ولا تعني هذه الأخطاء أن القائمة فارغة.
| الطلب | `error` |
| - | - |
| `pagination=cursor` مع حقل واحد فقط من حقلي المؤشر | `cursor_time and cursor_id must be sent together` |
| `cursor_time` ليس طابعًا زمنيًا بتنسيق RFC3339 | `cursor_time must be an RFC3339 timestamp` |
| حقول المؤشر دون `pagination=cursor`، أو بقيمة أخرى لـ `pagination` | `pagination must be cursor when cursor pagination is requested` |
مثلًا:
```json theme={null}
{
"error": "cursor_time and cursor_id must be sent together",
"code": "validation_failed",
"next": "send pagination=cursor alone for the first page, then send cursor_time and cursor_id together from next_cursor",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
انسخ `next_cursor` كاملًا من الصفحة السابقة. لا تضع الوقت الحالي مكان `cursor_time`. إذا فقدت المؤشر، فابدأ من جديد مع `pagination=cursor` وعوامل التصفية الأصلية. مفتاح الاستعلام غير المعروف أو القيمة من نوع خاطئ يعيدان `422` مع `"error": "invalid query parameters"`.
### استجابات مؤشر الإصدارات
لمؤشر الإصدارات 5 حقول. الطلب الناجح الذي ليس له نتائج مطابقة يعيد `200`:
```json theme={null}
{
"releases": [],
"next_cursor": null
}
```
عندما لا تكون قيمة `next_cursor` هي `null`، أرسل القيم الخمس كلها في الطلب التالي:
| حقل `next_cursor` | معامل الاستعلام |
| - | - |
| `time` | `cursor_time` |
| `project_id` | `cursor_project_id` |
| `release` | `cursor_release` |
| `environment` | `cursor_environment` |
| `service_name` | `cursor_service_name` |
يحدد `cursor_project_id` موضعًا. ولا يحل محل `project_id` أو `project_ids`. أبقِ معاملات المشروع والتصفية الأصلية. رمّز كل قيمة لعنوان URL.
مع `pagination=cursor`، يعيد المؤشر الجزئي أو قيمة الإصدار أو البيئة أو الخدمة الفارغة `422` مع `"error": "all release cursor fields must be sent together"`. وتعيد قيمة `cursor_time` غير الصالحة وغياب `pagination=cursor` الأخطاء نفسها التي تعيدها [المؤشرات الأخرى](#cursor-errors).
### أخطاء اكتشاف التتبّعات
تنطبق هذه الأخطاء على `GET /api/telemetry/traces`. يعيد كل منها `422` مع `code: validation_failed`. الطلب المرفوض ليس نتيجة فارغة.
| الطلب | `error` |
| - | - |
| `status` بقيمة غير `error` أو `ok` | `trace status must be error or ok` |
| `min_duration_ms` أقل من `0` | `minimum trace duration must not be negative` |
| حقل مؤشر واحد فقط، أو `cursor_trace_id` فارغ | `cursor_time and cursor_trace_id must be sent together` |
| `cursor_time` ليس طابعًا زمنيًا بتنسيق RFC3339 | `cursor_time must be an RFC3339 timestamp` |
| حقول المؤشر دون `pagination=cursor` | `pagination must be cursor when cursor pagination is requested` |
لتضمين حالتي التتبّع كلتيهما، احذف `status`. للصفحة التالية، انسخ `next_cursor.time` إلى `cursor_time` و`next_cursor.trace_id` إلى `cursor_trace_id`. لا ترسل `cursor_id` لصفحة تتبّعات. راجع [عوامل تصفية التتبّعات](/ar/reference/telemetry-api-filters#trace-filters).
### تاريخ مرات حدوث المشكلة
يقرأ `GET /api/telemetry/issues/{issue_id}/events` مرات حدوث مشكلة مجمّعة واحدة. استخدم رمز Bearer للحساب ومعرّف المشكلة المجمّعة. يقبل المسار فقط `pagination` و`cursor_time` و`cursor_id` و`limit`. ولا يقبل عوامل التصفية حسب المشروع أو الوقت أو الإصدار أو البيئة أو الخطورة.
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/events" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "pagination=cursor" \
--data-urlencode "limit=1"
```
صفحة أولى فيها حدوث واحد ومؤشر متابعة:
```json theme={null}
{
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"events": [
{
"id": "db619770-1f7c-4bd5-8310-9f171df8af47",
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"severity": "error",
"title": "Checkout failed",
"message": "Checkout could not complete",
"stack_trace": null,
"attributes": {
"exception": {
"type": "CheckoutError",
"mechanism": { "type": "javascript.error", "handled": false }
},
"breadcrumbs": [
{
"timestamp": "2026-06-01T11:54:59Z",
"category": "checkout",
"message": "Checkout started"
}
]
},
"diagnostics": {
"schema_version": 1,
"exception": {
"type": "CheckoutError",
"mechanism": { "type": "javascript.error", "handled": false }
},
"breadcrumbs": [
{
"timestamp": "2026-06-01T11:54:59Z",
"category": "checkout",
"message": "Checkout started"
}
],
"breadcrumbs_truncated": false
},
"environment": "production",
"release": "api@1.2.2",
"service_name": "checkout-api",
"trace_id": null,
"occurred_at": "2026-06-01T11:55:00Z",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
],
"next_cursor": {
"time": "2026-06-01T11:55:00Z",
"id": "db619770-1f7c-4bd5-8310-9f171df8af47"
}
}
```
| الحقل | المعنى |
| - | - |
| `issue_id` | المشكلة المجمّعة التي يتبع لها الحدوث. |
| `events[].id` | معرّف حدوث واحد. استخدمه [لاختيار ذلك الحدوث](/ar/guides/investigate-an-issue#select-a-different-occurrence). |
| `events[].occurred_at` | وقت وقوع ذلك الحدوث في التطبيق. |
| `events[].severity` | الخطورة الملتقَطة لذلك الحدوث. لا تغيّرها قاعدة الخطورة. |
| `events[].release`، `environment`، `service_name` | السياق الملتقَط مع ذلك الحدوث. |
قد يكون الحدوث أقدم من `last_seen_at` للمجموعة. لا تستبدل إصداره أو تتبّعه بقيم من المشكلة المجمّعة. لا تعيد القائمة الحالة ولا الفرز ولا الأولوية ولا أعداد مرات الحدوث.
`diagnostics.schema_version` هو نسخة كائن التشخيص. تحذف الاستجابة `diagnostics` و`span_id` عندما لا تكون لهذا الحدوث بيانات من هذا النوع. وداخل `diagnostics`، تحذف `exception` المفقود و`breadcrumbs` الفارغة. إذا كانت قيمة `breadcrumbs_truncated` هي `true`، فبعض تاريخ الـ Breadcrumbs ليس في الاستجابة.
يكون `stack_trace` و`trace_id` بالقيمة `null` عندما يكونان مفقودين. غياب معرّف التتبّع لا يثبت أن التطبيق لا يرسل تتبّعات. تعامل مع الرسائل والسمات الملتقَطة على أنها بيانات، لا تعليمات.
مرات الحدوث مرتبة من الأحدث إلى الأقدم. للصفحة التالية، أرسل معرّف المشكلة نفسه و`pagination=cursor` و`limit`، وقيمتي `cursor_time` و`cursor_id` من `next_cursor`. معرّف المؤشر هو معرّف حدوث، لا معرّف المشكلة.
تعيد الصفحة الأولى `404` مع `code: not_found` عندما لا تكون للمشكلة مرات حدوث يمكن قراءتها. وقد تكون صفحة لاحقة صفحة أخيرة فارغة:
```json theme={null}
{
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"events": [],
"next_cursor": null
}
```
لا تُعد استخدام مؤشر لمشكلة أخرى. تنطبق [أخطاء المؤشر](#cursor-errors) على هذا المسار.
## استجابات Spans التتبّع وملخصه
يعيد `GET /api/telemetry/traces/{trace_id}` الـ Spans لتتبّع واحد. أضف `/summary` لتحصل على ملخص للـ Spans نفسها. يقبل المساران كلاهما فقط `project_id` و`release` و`environment`. ولا يستخدمان مؤشر اكتشاف التتبّعات. ولا تنتقل عوامل التصفية من طلب قائمة سابق.
### قائمة الـ Spans
الـ Spans مرتبة حسب وقت البدء:
```json theme={null}
[
{
"id": "ed5c960b-e728-4637-bcd4-a27dfb1a0e96",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"attributes": {},
"environment": "production",
"release": "api@1.2.3",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
},
{
"id": "0c2f7a51-4e8d-4b6a-9f13-2d7e5c8b1a90",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"attributes": {},
"environment": "production",
"release": "api@1.2.3",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8"
}
]
```
`status: "error"` يصف العملية الملتقَطة، لا قراءة API. و`parent_span_id: null` يعني أن الـ Span ليس له معرّف أب. و`status: null` يعني أن الـ Span لم يبلّغ عن حالة.
### ملخص التتبّع
ملخص الـ Spans نفسها، وعددها 2:
```json theme={null}
{
"trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
"span_count": 2,
"error_span_count": 2,
"service_count": 1,
"project_count": 1,
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"root_span": {
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
"slowest_child_span": {
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
},
"slowest_path": [
{
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
{
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
}
],
"error_spans": [
{
"span_id": "b37ac82563149fed",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "error",
"started_at": "2026-06-01T12:00:00Z",
"duration_ms": 823,
"service_name": "checkout-api"
},
{
"span_id": "7a085853722dc6d2",
"parent_span_id": "b37ac82563149fed",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-06-01T12:00:00.100Z",
"duration_ms": 640,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api",
"span_count": 2,
"error_span_count": 2,
"max_duration_ms": 823
}
],
"releases": ["api@1.2.3"],
"environments": ["production"]
}
```
| الحقل | المعنى |
| - | - |
| `duration_ms` | الوقت من أبكر بداية Span إلى آخر نهاية Span. وهو ليس مجموع مُدد الـ Spans. |
| `root_span` | أبكر Span ليس أبوه في التتبّع. وهو نقطة بداية، لا سبب مثبت. |
| `slowest_child_span` | أطول Span له معرّف أب، أو `null`. |
| `slowest_path` | سلسلة الآباء المعروفة من الـ Span الجذري إلى `slowest_child_span`. وتكون `[]` عندما تكون قيمة `slowest_child_span` هي `null`. |
| `error_spans` | أطول Spans الأخطاء، 5 على الأكثر. وقد تكون قيمة `error_span_count` أكبر. |
لا يعيد أي من المسارين مؤشرًا أو حقل اقتطاع. لا تضف قيمة `truncated` لا تحتويها الاستجابة.
### لا توجد Spans مطابقة
عندما لا يطابق أي Span معرّف التتبّع والنطاق، تعيد قائمة الـ Spans `200` مع `[]`. ويعيد الملخص `404` مع `"error": "trace not found"` و`code: not_found`. تحقق من معرّف التتبّع والنطاق. لا تحذف عوامل التصفية لتظهر نتيجة. لا تثبت أي من النتيجتين أن التطبيق لم يرسل بيانات قياس عن بُعد.
## تنسيق استجابة الأحداث المباشرة
يرسل الموجز المباشر الأحداث الجديدة. ولا يعيد إرسال الأحداث التي فاتت العميل أثناء انقطاع الاتصال. استخدم مسارات القوائم لقراءة القيود الموجودة.
### أنشئ تذكرة
أرسل `POST /api/feed/ticket` مع رمز Bearer للحساب. ليس للطلب نص.
```bash theme={null}
curl --request POST "https://api.logbrew.co/api/feed/ticket" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"
```
تحتوي الاستجابة `200 OK` على التذكرة في الحقل `ticket`:
```json theme={null}
{
"ticket": "",
"expires_in_seconds": 60,
"next": "connect with GET /api/feed/live?ticket= before the ticket expires",
"next_action": {
"code": "connect_live_feed",
"target": "live_feed"
}
}
```
التذكرة بيانات اعتماد قصيرة العمر. لا تكتبها في السجلات ولا تضعها في موجّه (prompt) وكيل. افتح الاتصال قبل انتهاء `expires_in_seconds`. تحدد مدة الصلاحية متى يمكن أن يبدأ الاتصال، لا المدة التي يبقى فيها مفتوحًا.
الاستجابة `401` تعني أن تسجيل الدخول إلى الحساب غير صالح. سجّل الدخول مرة أخرى قبل أن تطلب تذكرة. والطلب بطريقة غير `POST` يعيد `405` مع `code: method_not_allowed`.
### افتح الاتصال
اربط عميل WebSocket بالعنوان `wss://api.logbrew.co/api/feed/live?ticket=`. رمّز التذكرة لعنوان URL. لا تضع رمز Bearer للحساب ولا رمز Bearer للاستيعاب في عنوان URL. الاستجابة `401` تعني أن التذكرة أو تسجيل الدخول إلى الحساب غير صالح. أنشئ تذكرة جديدة بعد أن تسجّل الدخول مرة أخرى.
| الاستجابة | السبب | الخطوة التالية |
| - | - | - |
| `422` مع `"error": "feed ticket is required"` | قيمة الاستعلام `ticket` مفقودة أو فارغة. | أنشئ تذكرة واتصل بها. |
| `401` مع `code: unauthorized` | التذكرة منتهية الصلاحية أو غير صالحة. | أنشئ تذكرة جديدة. لا تُعد المحاولة بالتذكرة نفسها. |
| `code: invalid_websocket_upgrade` | الطلب ليس ترقية WebSocket صالحة. | استخدم عميل WebSocket. |
| `405` مع `code: method_not_allowed` | الطلب لا يستخدم `GET`. | استخدم `GET` للاتصال. |
انتظر قبل أن تعيد الاتصال بعد خطأ. لا تُعد الاتصال في حلقة متقاربة.
### اقرأ الرسائل
كل رسالة غلاف بالشكل `{ "type": "...", "data": ... }`. اقرأ `type` قبل أن تحلّل `data`. تجاوز الأنواع التي لا يدعمها العميل.
| نوع الحدث | البيانات المحمولة |
| - | - |
| `native_log` | بيانات سجل، بشكل [استجابة السجل](#log-response). |
| `native_issue` | بيانات مشكلة مجمّعة، بشكل [استجابة المشكلة](#issue-response) في النسخة 1. |
| `native_trace_span` | Span واحد، بشكل عنصر [قائمة الـ Spans](#span-list). |
| `native_action` | بيانات إجراء منتج، بشكل [استجابة الإجراء](#action-response). |
| `project_created`، `project_updated`، `project_catalog_changed` | بيانات المشروع. اقرأ قائمة المشاريع مرة أخرى عندما تتغير. |
| `usage_updated`، `usage_limit_warning`، `usage_limit_blocked` | استخدام الحساب، بشكل [استخدام الحساب](/ar/reference/account-api#account-usage). |
```json theme={null}
{
"type": "native_log",
"data": {
"id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"level": "warning",
"severity": "warning",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": false
},
"source": "runtime",
"message": "checkout retry scheduled",
"attributes": { "route": "/checkout" },
"occurred_at": "2026-06-01T12:00:00Z",
"environment": "production",
"release": "api@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"sdk_name": "@logbrew/node",
"sdk_version": "0.1.8",
"next_action": {
"code": "inspect_trace",
"target": "trace_summary"
}
}
}
```
يستخدم الحدث `native_issue` النسخة 1 من استجابة المشكلة: تظهر المشكلة المؤرشفة بالقيمة `ignored`، وليس للحدث أولوية. المقاييس والإصدارات ليست من أنواع الأحداث المباشرة. اقرأها بمسارات قوائمها. لا تختار التذكرة مشروعًا. تحقق من `project_id` لكل حدث قبل أن تعرضه في عرض مشروع. يستخدم `logbrew watch --json` هذا الموجز. راجع [مرجع CLI](/ar/reference/cli).
### تعامل مع الاتصال المغلق
| رمز الإغلاق | السبب | الخطوة التالية |
| - | - | - |
| `1013` | `live feed fell behind; reconnect to resync` | انتظر، ثم أعد الاتصال بتذكرة جديدة. اقرأ مسارات القوائم مرة أخرى لتحصل على القيود التي فاتتك. |
| `1008` | `live feed access changed; sign in again` | أوقف إعادة الاتصال. سجّل الدخول مرة أخرى قبل أن تنشئ تذكرة جديدة. |
قد لا يكون لحالات الانقطاع الأخرى سبب من LogBrew. بعد أن تعيد الاتصال، اقرأ مسارات القوائم مرة أخرى وطابق القيود حسب المعرّف.
## أمثلة استجابات حالة المشكلة
يعيد `PATCH /api/telemetry/issues/{issue_id}` مع `{ "status": "resolved" }` الاستجابة `200 OK` مع المشكلة المجمّعة المحدَّثة، بشكل [استجابة المشكلة](#issue-response) نفسه. يختار مفتاح الاستعلام `response_version` النسخة. ولا يعيد المسار علامة نجاح.
يضبط النص حقلًا واحدًا أو أكثر من `status` و`priority` و`assignee`. يقبل `status` القيم `unresolved` أو `resolved` أو `archived`. و`ignored` اسم أقدم لـ `archived`. راجع [حدّث مشكلة واحدة](/ar/reference/telemetry-api#update-one-issue).
تحقق من `id` و`status` و`priority` في الاستجابة قبل أن تعرض النجاح. لا تبنِ النتيجة من القيم المرسلة. تغيير الحالة لا يحذف مرات الحدوث، ولا يغيّر `first_seen_at` و`last_seen_at`. ولا يغيّر `severity` أو قاعدة الخطورة.
يعيد التغيير المرفوض `422` مع `code: validation_failed`:
```json theme={null}
{
"error": "issue status must be unresolved, resolved, or archived",
"code": "validation_failed",
"next": "use status=unresolved, status=resolved, or status=archived",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
| النتيجة | السبب |
| - | - |
| `422`، `issue update requires status, priority, or assignee` | ليس في النص أي من الحقول الثلاثة. |
| `422`، `issue priority must be high, medium, or low` | قيمة الأولوية غير مدعومة. |
| `422`، `issue assignee must be me, none, a user ID, or team:` | قيمة المسؤول غير مدعومة. |
| `422`، `issue assignee cannot read this project` | ليس للمسؤول صلاحية وصول إلى المشروع. لا يغيّر LogBrew شيئًا. |
| `422`، `issue assignee team is not a team of this project's organization` | الفريق لا يتبع مؤسسة المشروع. لا يغيّر LogBrew شيئًا. |
| `403` مع `code: forbidden` | لا يستطيع الحساب إدارة المشكلات في المشروع. |
| `404` مع `code: not_found` | لا يستطيع الحساب قراءة المشكلة، أو المشكلة غير موجودة. |
الحقل الذي له القيمة المطلوبة بالفعل لا يتغير. بعد انتهاء المهلة أو ضياع الاستجابة، أرسل الطلب نفسه مرة أخرى، أو اقرأ المشكلة أولًا. لا ترسل تغييرًا مختلفًا قبل أن تقرأ الحالة الحالية. راجع [عمليات الكتابة](/ar/reference/api-errors#writes).
يعيد `POST /api/telemetry/issues/bulk` الاستجابة `200 OK` مع نتيجة واحدة لكل معرّف مشكلة مطلوب، بترتيب الطلب. تستخدم كل مشكلة موجودة شكل النسخة 3. ولنتيجة `not_found` القيمة `issue: null`:
```json theme={null}
{
"project_id": "123e4567-e89b-12d3-a456-426614174000",
"results": [
{
"issue_id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"outcome": "updated",
"issue": {
"id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
"status": "archived",
"priority": "high",
"priority_source": "derived",
"assignee": null
}
},
{
"issue_id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"outcome": "not_found",
"issue": null
}
]
}
```
يعرض هذا المثال بعض حقول المشكلة فقط. قيمة `outcome` هي `updated` أو `unchanged` أو `not_found`. الطلب المكرر يعيد `unchanged` ولا يغيّر شيئًا. راجع [حدّث المشكلات دفعة واحدة](/ar/reference/telemetry-api#update-issues-in-bulk).
يفشل الطلب الجماعي كله في هذه الحالات:
| النتيجة | السبب |
| - | - |
| `422`، `issue_ids must name 1 to 100 issues` | القائمة فارغة أو فيها أكثر من 100 معرّف. |
| `422`، `issue_ids must not contain duplicates` | يتكرر معرّف أكثر من مرة. |
| `422` مع `code: invalid_json` | في النص حقل غير معروف. |
| `403` مع `code: forbidden` | لا يستطيع الحساب إدارة المشكلات في المشروع. |
| `404`، `project not found` | لا يستطيع الحساب قراءة المشروع. |
## نطاق طلبات التحليلات
تقرأ مسارات التحليلات ومسار سلسلة المقياس ومسار حجم الإشارات مشروعًا واحدًا ونطاقًا زمنيًا واحدًا. يحتاج كل طلب إلى `project_id` و`since`. يقبل `since` مدة مختصرة مثل `24h` أو `7d`، أو طابعًا زمنيًا بتنسيق RFC3339. ويقبل `until` طابعًا زمنيًا بتنسيق RFC3339، وقيمته الافتراضية وقت الطلب. يشمل النطاق `since` ولا يشمل `until`، ولا يمكن أن يزيد على 31 يومًا.
`service_name` و`release` و`environment` عوامل تصفية اختيارية بالمطابقة التامة. يجب أن تكون كل قيمة من 1 إلى 256 حرفًا بعد أن يزيل LogBrew المسافات من طرفيها. يضع مسار مقارنة الشرائح عوامل التصفية هذه داخل كل شريحة، لا في المستوى الأعلى.
إذا لم يستطع الحساب قراءة المشروع، تعيد هذه المسارات `200 OK` مع أعداد صفرية. ولا تعيد `404`. النتيجة الفارغة لا تؤكد صلاحية الوصول إلى المشروع. قارن `project_id` بالمشاريع التي يستطيع الحساب قراءتها. والطلب عبر اتصال MCP (grant) لا يشمل المشروع يعيد `403` و`forbidden`.
| المسار | قيم `response_version` | القيمة الافتراضية |
| - | - | - |
| `GET /api/telemetry/analytics/overview` | `1` أو `2` أو `3` | `1` |
| `GET /api/telemetry/analytics/properties` | `1` أو `2` | `1` |
| `POST /api/telemetry/analytics/segments/compare` | `1` أو `2` | `1` |
| `POST /api/telemetry/analytics/retention` | `1` أو `2` | `1` |
| `POST /api/telemetry/analytics/lifecycle` | `1` أو `2` | `1` |
| `POST /api/telemetry/analytics/funnel` | غير مقبول | المخطط `1` |
| `POST /api/telemetry/analytics/paths` | غير مقبول | المخطط `1` |
| `GET /api/telemetry/metrics/series` | غير مقبول | المخطط `1` |
| `GET /api/telemetry/summary/volume` | `1` | `1` |
تبدأ كل استجابة بالحقول `schema_version` و`query` و`purpose`. يعيد `query` النطاق الفعلي. ويحذف أي عامل تصفية لم ترسله. و`purpose` نص عادي يشرح السؤال الذي يجيب عنه المسار.
يُحذف المعدّل عندما يكون مقامه صفرًا. المعدّل المحذوف ليس `0` وليس `null`. اقرأ `coverage` قبل أن تثق بمعدّل.
### أخطاء النطاق المشتركة
تستخدم هذه الأخطاء HTTP `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| لا يوجد `project_id` | `product analytics project_id is required` |
| لا يوجد `since` | `product analytics since is required` |
| `since` ليس مدة ولا طابعًا زمنيًا بتنسيق RFC3339 | `invalid since value` |
| `until` ليس طابعًا زمنيًا بتنسيق RFC3339 | `product analytics until must be an RFC3339 timestamp` |
| `since` ليس أبكر من `until` | `product analytics since must be earlier than until` |
| النطاق أطول من 31 يومًا | `product analytics range must not exceed 31 days` |
| عامل تصفية فارغ، أو عامل تصفية أطول من 256 حرفًا | `product analytics context filters must be non-empty and at most 256 characters` |
مثلًا، الطلب الذي ليس فيه `project_id` يعيد:
```json theme={null}
{
"error": "product analytics project_id is required",
"code": "validation_failed",
"next": "choose one owned project and send its project_id",
"next_action": { "code": "fix_request", "target": "request" }
}
```
يستخدم مسارا سلسلة المقياس وحجم الإشارات قواعد النطاق نفسها، مع نص `error` خاص بكل منهما. تسرد أقسامهما أدناه تلك الأخطاء.
يعيد مفتاح الاستعلام غير المعروف `422` مع استجابة [معاملات الاستعلام غير الصالحة](/ar/reference/api-errors#invalid-query-parameters). ويعيد حقل JSON غير المعروف، أو حقل JSON المطلوب المفقود، أو قيمة التعداد غير المدعومة `invalid_json`. راجع [JSON غير صالح](/ar/reference/api-errors#invalid-json). والطلب بطريقة HTTP خاطئة يعيد `405` و`method_not_allowed`. ويسمّي نص `next` فيه الطريقة والحقول المدعومة. راجع [طريقة غير مدعومة](/ar/reference/api-errors#unsupported-method).
## استجابة النظرة العامة لتحليلات المنتج
يعرض `GET /api/telemetry/analytics/overview` النشاط في مشروع واحد: حجم الإجراءات، والمستخدمين، والجلسات، وسلسلة زمنية، وأبرز الإجراءات، ومشاهدات الصفحات ومشاهدات الشاشات والتفاعلات المصنَّفة. استخدمه لتجد أسماء الأحداث الدقيقة لمسارات التحليلات الأخرى.
أرسل `response_version=3`. تعيد النسختان 1 و2 الأعداد نفسها، لكن قيمة `estimation.method` فيهما رمز أقدم. لا تتحقق النسخة 1 من نوع الكيان عندما تعدّ المستخدمين معروفي الهوية. وتعدّ النسختان 2 و3 فقط الكيانات من النوع `user`، وتضيفان أعداد الكيانات مجهولة الهوية و`subject_coverage`.
يقرأ هذا الطلب ساعة واحدة في فواصل زمنية مدة كل منها خمس دقائق، ويعيد صفين في كل قائمة من القوائم الأبرز:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "since=2026-06-01T11:00:00Z" \
--data-urlencode "until=2026-06-01T12:00:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "top_limit=2" \
--data-urlencode "response_version=3"
```
### نجاح النظرة العامة
في هذه النتيجة المصطنعة، للمشروع 120 إجراءً في فاصلين زمنيين من الفواصل الاثني عشر. يأتي عشرون إجراءً من كيانات مجهولة الهوية. لكل إجراء معرّف جلسة. ولنصف الإجراءات معرّف تتبّع.
```json theme={null}
{
"schema_version": 3,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "5m",
"interval_seconds": 300,
"top_limit": 2
},
"purpose": "Shows what people do in one project through action volume, active identified users, separately labeled anonymous subjects, explicit sessions, activity over time, top actions, and versioned page-view, screen-view, interaction, surface, and exact event-name breakdowns. Exact classified event names can be used as ordered funnel steps. It never infers people from anonymous events or relabels arbitrary unclassified telemetry as product behavior.",
"analysis_level": "user_and_session",
"summary": {
"actions": 120,
"active_identified_users": 18,
"active_anonymous_subjects": 7,
"sessions": 24,
"distinct_action_names": 3,
"actions_per_identified_user": 5.555555555555555,
"actions_per_session": 5.0
},
"coverage": {
"identified_actions": 100,
"anonymous_actions": 20,
"subject_coverage": {
"index_version": 1,
"identified_user_events": 100,
"anonymous_subject_events": 20,
"legacy_unknown_kind_events": 0,
"missing_subject_events": 0,
"historical_unindexed_events": 0
},
"sessionized_actions": 120,
"traced_actions": 60,
"identification_rate": 0.8333333333333334,
"sessionization_rate": 1.0,
"trace_link_rate": 0.5,
"expected_buckets": 12,
"returned_points": 2,
"returned_top_actions": 2,
"top_actions_truncated": true,
"first_seen_at": "2026-06-01T11:00:10Z",
"last_seen_at": "2026-06-01T11:09:50Z",
"limitations": [
"Typed anonymous subjects are counted separately and never contribute to active identified-user counts.",
"Actions without a trace ID cannot link product behavior directly to trace investigation."
]
},
"estimation": {
"unique_counts_are_approximate": true,
"method": "approximate_distinct",
"description": "Active identified-user, anonymous-subject, session, distinct action-name, distinct surface, and distinct exact event-name counts are approximate distinct counts. Event totals and capture-coverage counts are exact within the selected, fully evaluated query window."
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T11:05:00Z",
"actions": 50,
"active_identified_users": 8,
"sessions": 10,
"identified_actions": 40,
"sessionized_actions": 50,
"traced_actions": 25
},
{
"bucket_start": "2026-06-01T11:05:00Z",
"bucket_end": "2026-06-01T11:10:00Z",
"actions": 70,
"active_identified_users": 12,
"sessions": 14,
"identified_actions": 60,
"sessionized_actions": 70,
"traced_actions": 35
}
],
"top_actions": [
{
"name": "checkout_started",
"actions": 50,
"active_identified_users": 12,
"sessions": 14,
"share_of_actions": 0.4166666666666667
},
{
"name": "purchase_completed",
"actions": 40,
"active_identified_users": 9,
"sessions": 10,
"share_of_actions": 0.3333333333333333
}
],
"classified_activity": {
"summary": {
"events": 110,
"page_views": 50,
"screen_views": 20,
"interactions": 40,
"distinct_surfaces": 4,
"distinct_event_names": 5,
"active_identified_users": 17,
"active_anonymous_subjects": 6,
"sessions": 23
},
"coverage": {
"classified_actions": 60,
"unclassified_actions": 60,
"action_classification_rate": 0.5,
"surfaced_events": 110,
"named_events": 110,
"identified_events": 90,
"subject_coverage": {
"index_version": 1,
"identified_user_events": 90,
"anonymous_subject_events": 20,
"legacy_unknown_kind_events": 0,
"missing_subject_events": 0,
"historical_unindexed_events": 0
},
"sessionized_events": 110,
"traced_events": 55,
"surface_rate": 1.0,
"event_name_rate": 1.0,
"identification_rate": 0.8181818181818182,
"sessionization_rate": 1.0,
"trace_link_rate": 0.5,
"expected_buckets": 12,
"returned_points": 2,
"returned_top_surfaces": 2,
"returned_top_events": 2,
"top_surfaces_truncated": true,
"top_events_truncated": true,
"first_seen_at": "2026-06-01T11:00:20Z",
"last_seen_at": "2026-06-01T11:09:40Z",
"limitations": [
"Only events carrying supported version-1 analytics annotations appear in classified activity; arbitrary actions and technical spans are not relabeled.",
"Historical or unannotated actions contribute to the action summary but not to classified screen-view or interaction breakdowns.",
"Classified events with typed anonymous subjects are counted separately and never contribute to identified-user counts.",
"Classified events without a trace ID cannot link product behavior directly to trace investigation."
]
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T11:05:00Z",
"events": 45,
"page_views": 20,
"screen_views": 10,
"interactions": 15
},
{
"bucket_start": "2026-06-01T11:05:00Z",
"bucket_end": "2026-06-01T11:10:00Z",
"events": 65,
"page_views": 30,
"screen_views": 10,
"interactions": 25
}
],
"top_surfaces": [
{
"kind": "page_view",
"surface": "/checkout/:step",
"events": 40,
"active_identified_users": 12,
"sessions": 14,
"share_of_classified_events": 0.36363636363636365
},
{
"kind": "screen_view",
"surface": "Checkout",
"events": 20,
"active_identified_users": 9,
"sessions": 10,
"share_of_classified_events": 0.18181818181818182
}
],
"top_events": [
{
"kind": "page_view",
"event_name": "/checkout/:step",
"events": 40,
"active_identified_users": 12,
"sessions": 14,
"share_of_classified_events": 0.36363636363636365
},
{
"kind": "interaction",
"event_name": "checkout_started",
"events": 30,
"active_identified_users": 10,
"sessions": 12,
"share_of_classified_events": 0.2727272727272727
}
]
},
"next_action": {
"code": "build_product_funnel",
"target": "/api/telemetry/analytics/funnel",
"reason": "Use two through eight exact keys from classified_activity.top_events to measure ordered conversion and drop-off for explicit sessions or opaque identified users."
}
}
```
### اقرأ النظرة العامة
مجموع أعداد `subject_coverage` الخمسة يساوي إجمالي الأحداث في قسمها. وحده `identified_user_events` يُحسب ضمن المستخدمين. و`anonymous_actions` يساوي `summary.actions` ناقص `identified_actions`.
يحتوي `series` فقط على الفواصل الزمنية التي فيها نشاط. و`expected_buckets` هو عدد الفواصل الزمنية الممكنة في النطاق. لا ترسم الفاصل الزمني المفقود صفرًا مقيسًا إلا إذا ذكر مخططك هذه القاعدة. تتوافق الفواصل الزمنية مع حدود الفواصل بتوقيت UTC. والنطاق الذي يبدأ داخل فاصل زمني يشمل ذلك الفاصل الجزئي.
يعدّ `classified_activity` مشاهدات الصفحات ومشاهدات الشاشات والتفاعلات. مشاهدات الشاشات والتفاعلات إجراءات أيضًا. أما مشاهدات الصفحات فليست إجراءات. لا تجمع `summary.actions` مع `classified_activity.summary.events`.
انسخ `kind` و`event_name` من `classified_activity.top_events` إلى خطوات قمع التحويل، ومُحدِّدات الاحتفاظ بالمستخدمين، ومُحدِّدات دورة الحياة، والأحداث المرجعية للمسارات، وأهداف الشرائح. القيمة `true` في `top_events_truncated` تعني وجود أسماء أقل حجمًا. زِد `top_limit` حتى 20 لترى المزيد.
قيمة `analysis_level` هي `no_data` أو `event_only` أو `user_level` أو `user_and_session`. إذا لم تكن للمشروع إجراءات ولا أحداث مصنَّفة، فقيمة `next_action.code` هي `capture_product_activity`. راجع [تحليلات المنتج](/ar/concepts/product-analytics#use-the-analytics-api).
### أخطاء النظرة العامة
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد النظرة العامة `422` و`validation_failed` لهذه القيم:
| القيمة | `error` |
| - | - |
| `response_version` بقيمة غير `1` أو `2` أو `3` | `product analytics response_version must be 1, 2, or 3` |
| `top_limit` خارج النطاق من `1` إلى `20` | `product analytics top_limit must be between 1 and 20` |
| `interval` بقيمة غير `auto` أو `1m` أو `5m` أو `15m` أو `1h` أو `6h` أو `1d` | `product analytics interval is not supported` |
| `interval` صريح يحتاج إلى أكثر من 500 فاصل زمني | `product analytics interval would exceed 500 buckets` |
القيمة الافتراضية لـ `interval` هي `auto`. وهي تختار أصغر فاصل زمني يحتاج إلى 300 فاصل على الأكثر. والقيمة الافتراضية لـ `top_limit` هي `10`.
## استجابة قمع التحويل المرتب
يقيس `POST /api/telemetry/analytics/funnel` الإكمال المرتب عبر خطوتين إلى 8 خطوات. انسخ كل قيمة `kind` و`event_name` كما هي تمامًا من `classified_activity.top_events` في النظرة العامة. اسم الإجراء المشابه ليس تطابقًا. يعدّ نص الطلب هذا الجلسات التي تشاهد `/pricing` ثم تكمل التسجيل خلال ساعة واحدة:
```json theme={null}
{
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"since": "2026-08-01T00:00:00Z",
"until": "2026-08-02T00:00:00Z",
"environment": "production",
"analysis_unit": "session",
"conversion_window_seconds": 3600,
"steps": [
{ "kind": "page_view", "event_name": "/pricing" },
{ "kind": "interaction", "event_name": "signup_completed" }
]
}
```
قيمة `analysis_unit` هي `session` أو `identified_user`. القيمة الافتراضية `session`. وقيمة `kind` للخطوة هي `page_view` أو `screen_view` أو `interaction`. لا يقبل مسار قمع التحويل `response_version`.
### نجاح قمع التحويل
استجابة `200 OK`:
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"since": "2026-08-01T00:00:00Z",
"until": "2026-08-02T00:00:00Z",
"environment": "production",
"analysis_unit": "session",
"conversion_window_seconds": 3600
},
"purpose": "Shows where explicit sessions or typed opaque user subjects enter, progress, and drop off across two through eight versioned page-view, screen-view, or interaction events. Steps must occur in order with strictly increasing timestamps inside the selected conversion window; raw session and subject identifiers are never returned.",
"summary": {
"candidate_units": 60,
"entered_units": 50,
"completed_units": 15,
"entry_rate": 0.8333333333333334,
"overall_conversion_rate": 0.3
},
"coverage": {
"classified_events": 200,
"named_events": 180,
"unnamed_events": 20,
"unit_identified_events": 160,
"selected_step_events": 120,
"usable_selected_step_events": 100,
"excluded_selected_step_events": 20,
"event_name_rate": 0.9,
"selected_unit_coverage_rate": 0.8333333333333334,
"limitations": [
"Only supported version-1 classified events with exact derived names participate; arbitrary actions and technical spans are never relabeled.",
"A unit reaches later steps only when timestamps strictly increase and the final match remains inside conversion_window_seconds from its first match.",
"Historical or surface-less classified events without a derived event name cannot match exact funnel steps.",
"Requested-step events without an explicit session ID are excluded from ordered unit counts.",
"Session funnels count visits or app sessions, not unique people; use analysis_unit=identified_user only when typed user-subject coverage is sufficient."
]
},
"steps": [
{
"position": 1,
"kind": "page_view",
"event_name": "/pricing",
"units": 50,
"conversion_from_first": 1.0,
"drop_off_to_next_units": 35,
"drop_off_to_next_rate": 0.7
},
{
"position": 2,
"kind": "interaction",
"event_name": "signup_completed",
"units": 15,
"conversion_from_previous": 0.3,
"conversion_from_first": 0.3
}
],
"next_action": {
"code": "compare_funnel_contexts",
"target": "/api/telemetry/analytics/funnel",
"reason": "Compare the same exact steps across bounded releases, environments, or services to locate material conversion changes."
}
}
```
المعدّلات كسور من 0 إلى 1. اقرأ `coverage` قبل أن تثق بمعدّل. و`selected_unit_coverage_rate` هي نسبة أحداث الخطوات المختارة التي استطاع LogBrew استخدامها. لا تعيد الاستجابة الهويات الخام. راجع [تحليلات المنتج](/ar/concepts/product-analytics#measure-a-funnel).
### اقرأ التحويل والتغطية
`entry_rate` يساوي `entered_units` مقسومًا على `candidate_units`: 50 من 60. و`overall_conversion_rate` يساوي `completed_units` مقسومًا على `entered_units`: 15 من 50، أي 30%. وهو ليس 15 مقسومًا على كل الوحدات المرشّحة. لا توضح هذه الأعداد سبب توقف الوحدات.
تعدّ التغطية الأحداث، لا الجلسات. هنا يطابق 120 حدثًا خطوةً ما، و20 منها ليس لها معرّف جلسة. تستبعد النتيجة هذه الأحداث العشرين من أعداد الجلسات. لا تتعامل معها على أنها 20 جلسة فاشلة.
ليس للخطوة الأولى `conversion_from_previous`. وليس للخطوة الأخيرة `drop_off_to_next_units` ولا `drop_off_to_next_rate`.
تصل الوحدة إلى خطوة لاحقة فقط عندما تتزايد أوقات الخطوات تزايدًا صارمًا. لا يمكن للأحداث ذات الطابع الزمني نفسه أن تحقق خطوتين متتاليتين. ويجب أن تقع الخطوة الأخيرة خلال `conversion_window_seconds` من الخطوة الأولى.
وضع الجلسات يعدّ الجلسات، لا الأشخاص. استخدم `identified_user` فقط للأحداث التي تحمل معرّف كيان مبهمًا من النوع `user`. يمكن لهذا الوضع أن يربط أحداثًا من جلسات مختلفة داخل فترة التحويل. أبقِ الوحدة نفسها والخطوات نفسها عندما تقارن النتائج.
القيمة الافتراضية لـ `conversion_window_seconds` هي 24 ساعة أو طول النطاق، أيهما أقصر. والحد الأقصى هو طول النطاق بالثواني الكاملة، مقرَّبًا إلى الأعلى.
### نتائج قمع التحويل الفارغة
الاستجابة الفارغة الناجحة تسرد مع ذلك الخطوات المطلوبة مع `units` صفرية. إذا لم تكن هناك وحدات مرشّحة، يحذف `summary` الحقلين `entry_rate` و`overall_conversion_rate`. لا يعيد المسار `404` لأن أي حدث لم يطابق.
اقرأ `coverage` و`next_action` لتجد السبب:
| `next_action.code` | السبب |
| - | - |
| `capture_product_activity` | لا توجد أحداث مصنَّفة في النطاق. |
| `choose_captured_funnel_steps` | لا يطابق أي حدث خطوة مطلوبة. |
| `sessionize_product_activity` | توجد أحداث للخطوات، لكن ليس لأي منها معرّف جلسة. |
| `identify_product_users` | توجد أحداث للخطوات، لكن ليس لأي منها كيان من النوع `user`. |
| `verify_funnel_entry` | لم تدخل أي وحدة عند الخطوة 1. |
| `investigate_funnel_drop_off` | دخلت وحدات، لكن لم تكمل أي وحدة كل الخطوات. |
| `compare_funnel_contexts` | أكملت وحدة واحدة على الأقل قمع التحويل. |
### طلبات قمع التحويل المرفوضة
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد هذه الطلبات `422` و`validation_failed`. أقل من خطوتين أو أكثر من 8 خطوات:
```json theme={null}
{
"error": "product analytics funnel requires two through eight ordered steps",
"code": "validation_failed",
"next": "send a steps array containing 2 through 8 exact classified event selectors",
"next_action": { "code": "fix_request", "target": "request" }
}
```
قيمة `conversion_window_seconds` تساوي `0`، أو قيمة أكبر من طول النطاق:
```json theme={null}
{
"error": "product analytics funnel conversion window must fit inside the query range",
"code": "validation_failed",
"next": "use conversion_window_seconds from 1 through the selected range length",
"next_action": { "code": "fix_request", "target": "request" }
}
```
قيمة `event_name` الفارغة، أو الأطول من 256 حرفًا، أو التي تحتوي على حرف تحكم تعيد `product analytics funnel event_name must be non-empty, control-free, and at most 256 characters`. ويجب أن تكون خطوة `interaction` أيضًا اسم إجراء صالحًا. وإلا فالخطأ هو `product analytics interaction event_name must be a bounded stable action name`.
صحّح الطلب قبل أن ترسله مرة أخرى. لا تحذف خطوات ولا تغيّر وحدة التحليل لمجرد أن تحصل على نتيجة غير فارغة.
## التحليل بأحداث محددة والتحليل التلقائي
يقبل الاحتفاظ بالمستخدمين ودورة الحياة شكلين للطلب. استخدم `response_version` لتختار الشكل الذي يجيب عن سؤالك:
| التحليل | `response_version` | مُحدِّدات الأحداث |
| - | - | - |
| الاحتفاظ بالمستخدمين لأحداث محددة | `1`، أو محذوف | أرسل `start_event` و`return_event` كليهما. |
| دورة الحياة لحدث محدد واحد | `1`، أو محذوف | أرسل `event`. |
| الاحتفاظ بالمستخدمين أو دورة الحياة تلقائيًا | `2` | لا ترسل أي مُحدِّد أحداث. |
يحتوي المُحدِّد الدقيق على `kind` و`event_name`. قيمة `kind` هي `page_view` أو `screen_view` أو `interaction`. انسخ `event_name` من `classified_activity.top_events`. لا تخمّن اسم الحدث من نص زر.
يعدّ الشكلان كلاهما المستخدمين فقط: معرّفات الكيانات المبهمة من النوع `user`. لا تُحسب الكيانات مجهولة الهوية ولا الأحداث التي ليس لها معرّف كيان صالح للاستخدام مستخدمين. لا تعيد الاستجابات معرّفات الكيانات أبدًا.
الفواصل الزمنية الثابتة هي `hour` و`day` و`week` و`thirty_day`. وهي مُدد ثابتة. `thirty_day` تعني 30 يومًا، لا شهرًا تقويميًا. إذا حذفت `interval`، يستخدم API القيمة `hour` للنطاق الذي مدته 48 ساعة أو أقل، و`day` للنطاق الأطول.
### طلب الاحتفاظ بالمستخدمين لأحداث محددة
أرسل هذا النص إلى `POST /api/telemetry/analytics/retention`. وهو يسأل هل يكمل المستخدمون عملية إتمام شراء أخرى بعد أول عملية إتمام شراء لهم في النطاق:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 1,
"interval": "day",
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range",
"start_event": { "kind": "interaction", "event_name": "checkout_completed" },
"return_event": { "kind": "interaction", "event_name": "checkout_completed" }
}
```
أول حدث بداية مطابق في النطاق هو نقطة البداية لكل مستخدم. يجب أن تقع العودة بعد نقطة البداية هذه تمامًا وقبل `until`. ويمكن أن يكون المُحدِّدان الحدث نفسه.
| الحقل | القيم | القيمة الافتراضية |
| - | - | - |
| `interval_count` | من `1` إلى `31` فترة | `10` |
| `mode` | `return_on` يعدّ العودة داخل كل فترة بعينها. و`return_on_or_after` يعدّ العودة عند بداية كل فترة أو بعدها. | `return_on` |
| `cohort_mode` | `first_in_range` | `first_in_range` |
### نجاح الاحتفاظ بالمستخدمين لأحداث محددة
في هذا المثال المصطنع، يُتم مستخدمان عملية الشراء. يُتم المستخدم الأول الشراء الساعة 12:00 يوم 1 يونيو، ثم مرة أخرى الساعة 13:00. ويُتم المستخدم الثاني الشراء الساعة 12:00 يوم 2 يونيو. وفي الساعة 13:00 يوم 2 يونيو، يشاهد المستخدم الثاني صفحة لكنه لا يُتم عملية شراء أخرى.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"start_event": { "kind": "interaction", "event_name": "checkout_completed" },
"return_event": { "kind": "interaction", "event_name": "checkout_completed" },
"interval": "day",
"interval_seconds": 86400,
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
},
"purpose": "Measures whether typed opaque user subjects return after their first matching start event inside the selected half-open query range. Returns must occur strictly after each subject's anchor. return_on measures one fixed subject-relative period; return_on_or_after measures from that period's threshold through the exclusive query upper bound. Eligibility-aware denominators prevent immature subjects from being reported as churned, cohorts are fixed buckets aligned to since, and raw subject identifiers are never returned.",
"summary": {
"cohort_subjects": 2,
"subjects_returned_after_start": 1,
"return_rate_after_start": 0.5,
"non_empty_cohorts": 2,
"periods_with_eligible_subjects": 1,
"fully_observed_periods": 0
},
"coverage": {
"classified_events": 4,
"named_events": 4,
"unnamed_events": 0,
"identified_events": 4,
"start_events": 3,
"usable_start_events": 3,
"excluded_start_events": 0,
"return_events": 3,
"usable_return_events": 3,
"excluded_return_events": 0,
"event_name_rate": 1.0,
"start_identity_coverage_rate": 1.0,
"return_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"first_in_range anchors each subject at its first matching start inside the selected range; it does not prove that event was the subject's first-ever historical start.",
"Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returns must match the exact selected kind and derived event name, occur strictly after the subject anchor, and remain before the exclusive query upper bound.",
"This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
"return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
]
},
"curve": [
{
"period": 0,
"threshold_seconds": 0,
"window_end_seconds": 86400,
"eligible_subjects": 1,
"retained_subjects": 1,
"weighted_retention_rate": 1.0,
"fully_observed_cohorts": 1,
"fully_observed_cohort_average_rate": 1.0,
"all_subjects_eligible": false
}
],
"cohorts": [
{
"cohort": 0,
"started_at": "2026-06-01T00:00:00Z",
"ended_at": "2026-06-02T00:00:00Z",
"subjects": 1,
"subjects_returned_after_start": 1,
"periods": [
{
"period": 0,
"eligible_subjects": 1,
"retained_subjects": 1,
"retention_rate": 1.0,
"all_subjects_eligible": true
}
]
},
{
"cohort": 1,
"started_at": "2026-06-02T00:00:00Z",
"ended_at": "2026-06-03T00:00:00Z",
"subjects": 1,
"subjects_returned_after_start": 0,
"periods": [
{
"period": 0,
"eligible_subjects": 0,
"retained_subjects": 0,
"all_subjects_eligible": false
}
]
}
],
"next_action": {
"code": "extend_retention_observation_window",
"target": "/api/telemetry/analytics/retention",
"reason": "Move since earlier, until later, or request fewer periods when a fully observed long-term comparison is required."
}
}
```
### اقرأ الاحتفاظ بالمستخدمين
تعدّ التغطية الأحداث المصنَّفة الأربعة كلها، لكن ثلاثة منها فقط تطابق كل مُحدِّد لإتمام الشراء. مشاهدة الصفحة لا تُحسب عودة. يكرر أحد المستخدمَين إتمام الشراء، لذلك قيمة `return_rate_after_start` هي `0.5`.
وحده المستخدم الأول لديه يوم كامل من الرصد بعد نقطة البداية. ويعود هذا المستخدم خلال اليوم، لذلك معدّل المنحنى `1.0`. أما المستخدم الثاني فلديه 12 ساعة فقط من الرصد. هذا المستخدم غير مؤهل للفترة 0، لذلك تحذف خلية المجموعة النموذجية الثانية `retention_rate`. لا تَعُدّ هذا المستخدم مفقودًا.
يقسم `weighted_retention_rate` كل المستخدمين المحتفَظ بهم على كل المستخدمين المؤهلين. و`fully_observed_cohort_average_rate` هو المتوسط البسيط لمعدّلات المجموعات النموذجية التي يكون كل مستخدم فيها مؤهلًا. المجموعات النموذجية فواصل زمنية ثابتة تبدأ عند `since`. ويحتوي `cohorts` فقط على المجموعات النموذجية التي فيها مستخدمون.
مع `mode: "return_on_or_after"`، يحذف المنحنى `window_end_seconds`.
### الاحتفاظ بالمستخدمين تلقائيًا
أرسل `response_version: 2` دون `start_event` أو `return_event`. كل مشاهدة صفحة أو مشاهدة شاشة أو تفاعل مدعوم يُحسب بدايةً وعودةً. تختار هذه النسخة مجموعة من الأحداث. ولا تختار تنسيق التقاط في الـ SDK.
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 2,
"interval": "day",
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
}
```
للاستجابة أشكال `summary` و`curve` و`cohorts` و`next_action` نفسها التي لاستجابة الأحداث المحددة. يعرض هذا المقتطف الحقول التي تتغير. في هذا المثال، للمستخدمَين نفسيهما ثلاثة أحداث وليس لهما مشاهدة صفحة:
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"activity_scope": "all_classified_activity",
"interval": "day",
"interval_seconds": 86400,
"interval_count": 1,
"mode": "return_on",
"cohort_mode": "first_in_range"
},
"purpose": "Measures whether typed opaque user subjects perform any later supported classified product activity after their first such activity inside the selected half-open range. It does not choose or infer a top event. Returns must occur strictly after the anchor, anonymous and unidentified subjects remain excluded from user counts, eligibility-aware denominators prevent immature subjects from being reported as churned, and raw identifiers are never returned.",
"coverage": {
"classified_events": 3,
"named_events": 3,
"unnamed_events": 0,
"identified_events": 3,
"start_events": 3,
"usable_start_events": 3,
"excluded_start_events": 0,
"return_events": 3,
"usable_return_events": 3,
"excluded_return_events": 0,
"event_name_rate": 1.0,
"start_identity_coverage_rate": 1.0,
"return_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"first_in_range anchors each subject at its first supported classified activity in the range; it does not prove that activity was the subject's first-ever product activity.",
"Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returns are any supported classified activity strictly after the subject anchor and before the exclusive query upper bound; no event is ranked, selected, or inferred.",
"This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
"return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
]
}
}
```
في الوضع التلقائي، يساوي كل من `start_events` و`return_events` قيمة `classified_events`. هذه الأعداد أحداث، لا مستخدمون.
### الاحتفاظ بالمستخدمين دون مستخدمين مؤهلين
قد لا يكون في النتيجة الناجحة مستخدمون ضمن المجموعات النموذجية. يعرض هذا المقتطف فترة واحدة مطلوبة دون مجموعات نموذجية:
```json theme={null}
{
"schema_version": 2,
"summary": {
"cohort_subjects": 0,
"subjects_returned_after_start": 0,
"non_empty_cohorts": 0,
"periods_with_eligible_subjects": 0,
"fully_observed_periods": 0
},
"curve": [
{
"period": 0,
"threshold_seconds": 0,
"window_end_seconds": 86400,
"eligible_subjects": 0,
"retained_subjects": 0,
"fully_observed_cohorts": 0,
"all_subjects_eligible": false
}
],
"cohorts": []
}
```
اقرأ `coverage` و`next_action`. فهما يميّزان النطاق الذي ليس فيه أحداث مصنَّفة (`capture_product_activity`) من الأحداث التي ليس لها مستخدمون (`identify_product_users` أو `identify_returning_users`). المعدّل المفقود ليس صفرًا مقيسًا.
### أخطاء الاحتفاظ بالمستخدمين
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد هذه الطلبات `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| النسخة 1 دون المُحدِّدين كليهما، أو النسخة 2 مع مُحدِّد، أو نسخة أخرى | `product analytics retention activity selection is contradictory` |
| `interval_count` خارج النطاق من `1` إلى `31` | `product analytics retention interval_count must be between 1 and 31` |
| حاصل ضرب فواصل المجموعات النموذجية في `interval_count` أكبر من 500 | `product analytics retention interval and interval_count would exceed 500 cohort matrix cells` |
يستخدم حد الخلايا النطاق والفترات، لا عدد المستخدمين. النطاق الذي مدته 30 يومًا مع `interval: "hour"` فيه 720 فاصلًا زمنيًا للمجموعات النموذجية. ومع `interval_count: 1`، ينتج 720 خلية، وهذا أكثر من 500:
```json theme={null}
{
"error": "product analytics retention interval and interval_count would exceed 500 cohort matrix cells",
"code": "validation_failed",
"next": "choose a wider interval, a shorter time range, or fewer retention periods",
"next_action": { "code": "fix_request", "target": "request" }
}
```
لاستخدام الاحتفاظ بالمستخدمين تلقائيًا، احذف المُحدِّدين كليهما. لا تغيّر الـ SDK لتصحيح طلب القراءة هذا.
### طلب دورة الحياة لحدث محدد
أرسل هذا النص إلى `POST /api/telemetry/analytics/lifecycle`. وهو يصنّف المستخدمين حسب حدث واحد، لا حسب كل نشاط في المشروع:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 1,
"interval": "day",
"history_period_count": 2,
"event": { "kind": "interaction", "event_name": "checkout_completed" }
}
```
يحدد `history_period_count` الفترات الكاملة قبل `since` التي يقرؤها LogBrew تاريخًا مرصودًا سابقًا. ويقبل من `2` إلى `31`. القيمة الافتراضية `2`. قد يكون المستخدم خاملًا لهذا الحدث بينما يمارس أنشطة أخرى.
### نجاح دورة الحياة لحدث محدد
يستخدم هذا المثال المصطنع يومين من التاريخ المرصود السابق ويومين للتحليل. الحروف تميّز مستخدمي المثال فقط. لا تعيد الاستجابة معرّفات المستخدمين.
| التاريخ، بتوقيت UTC | المستخدمون الذين يُتمّون الشراء |
| - | - |
| 30 مايو، التاريخ المرصود | B |
| 31 مايو، التاريخ المرصود | A وD |
| 1 يونيو، التحليل | A وB وC |
| 2 يونيو، التحليل | A وB |
يشاهد C أيضًا صفحة يوم 2 يونيو. هذا الحدث لا يطابق مُحدِّد إتمام الشراء.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"history_since": "2026-05-30T00:00:00Z",
"event": { "kind": "interaction", "event_name": "checkout_completed" },
"interval": "day",
"interval_seconds": 86400,
"history_period_count": 2,
"expected_buckets": 2
},
"purpose": "Classifies typed opaque user subjects for one exact product event in each fixed analysis period. new_within_observed_history means active now with no earlier matching event inside the bounded history window; returning means active now and in the immediately previous period; resurrected means active now, inactive in the previous period, and active earlier in observed history; dormant means active in the previous period but not now. These states are disjoint, incomplete buckets are marked, and raw subject identifiers are never returned.",
"summary": {
"observed_subjects": 4,
"analysis_active_subjects": 3,
"history_only_subjects": 1,
"returned_buckets": 2,
"fully_observed_buckets": 2,
"latest_fully_observed_period": 1,
"buckets_with_resurrection": 1,
"buckets_with_dormancy": 2
},
"coverage": {
"analysis_classified_events": 6,
"analysis_named_events": 6,
"analysis_unnamed_events": 0,
"analysis_identified_events": 6,
"selected_events": 5,
"usable_selected_events": 5,
"usable_selected_sessionized_events": 5,
"usable_selected_trace_linked_events": 5,
"excluded_selected_events": 0,
"history_selected_events": 3,
"usable_history_selected_events": 3,
"excluded_history_selected_events": 0,
"event_name_rate": 1.0,
"selected_identity_coverage_rate": 1.0,
"selected_sessionization_rate": 1.0,
"selected_trace_link_rate": 1.0,
"history_identity_coverage_rate": 1.0,
"limitations": [
"Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
"new_within_observed_history means no earlier selected event between history_since and the current bucket. It does not prove that a subject is a lifetime-new user.",
"Observed history contains exactly 2 complete fixed periods before since; activity before history_since is intentionally unknown.",
"Buckets are fixed-width and aligned to since. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
"Returning, resurrected, and dormant compare only the selected exact kind and derived event name. They do not infer intent, identity merges, or causality.",
"This resource does not provide arbitrary property breakdowns, reusable cohorts, group lifecycle, lifetime first-event lookup, or per-subject lists."
]
},
"buckets": [
{
"period": 0,
"started_at": "2026-06-01T00:00:00Z",
"ended_at": "2026-06-02T00:00:00Z",
"fully_observed": true,
"active_subjects": 3,
"new_within_observed_history_subjects": 1,
"returning_subjects": 1,
"resurrected_subjects": 1,
"dormant_subjects": 1,
"previous_active_subjects": 2,
"new_share_of_active": 0.3333333333333333,
"returning_share_of_active": 0.3333333333333333,
"resurrected_share_of_active": 0.3333333333333333,
"dormant_share_of_previous_active": 0.5,
"net_active_change": 1
},
{
"period": 1,
"started_at": "2026-06-02T00:00:00Z",
"ended_at": "2026-06-03T00:00:00Z",
"fully_observed": true,
"active_subjects": 2,
"new_within_observed_history_subjects": 0,
"returning_subjects": 2,
"resurrected_subjects": 0,
"dormant_subjects": 1,
"previous_active_subjects": 3,
"new_share_of_active": 0.0,
"returning_share_of_active": 1.0,
"resurrected_share_of_active": 0.0,
"dormant_share_of_previous_active": 0.3333333333333333,
"net_active_change": -1
}
],
"next_action": {
"code": "investigate_lifecycle_loss",
"target": "/api/telemetry/analytics/paths",
"reason": "The latest complete bucket lost more prior active subjects than it added through new-within-observed-history and resurrected activity; compare bounded journeys around the selected event."
}
}
```
### اقرأ دورة الحياة
في 1 يونيو، A عائد، وB مستعاد، وC جديد، وD خامل. وفي 2 يونيو، A وB عائدان، وC خامل لإتمام الشراء رغم مشاهدة الصفحة. صافي التغير في 2 يونيو هو `2 - 3 = -1`.
في كل فاصل زمني، مجموع المستخدمين الجدد والعائدين والمستعادين يساوي `active_subjects`. و`returning_subjects` زائد `dormant_subjects` يساوي `previous_active_subjects`. و`net_active_change` يساوي `active_subjects` ناقص `previous_active_subjects`.
لا تجمع الأعداد اليومية للنشطين لتحصل على المستخدمين الفريدين. هنا مجموع الأعداد اليومية 5، لكن قيمة `analysis_active_subjects` هي 3. يظهر أربعة مستخدمين فريدين عبر التاريخ المرصود والتحليل.
تكون قيمة `fully_observed` هي `false` للفاصل الزمني الأخير الذي ينتهي بعد `until`. وقد تتغير أعداده عندما يصبح رصد الفترة الكاملة ممكنًا. يقترح `next_action` تحقيقًا. ولا يبيّن سببًا.
### دورة الحياة تلقائيًا
أرسل `response_version: 2` دون مُحدِّد `event`. كل مشاهدة صفحة أو مشاهدة شاشة أو تفاعل مدعوم يُحسب نشاطًا:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"response_version": 2,
"interval": "day",
"history_period_count": 2
}
```
للاستجابة أشكال `summary` و`buckets` و`next_action` نفسها التي لاستجابة الأحداث المحددة. يعرض هذا المقتطف الحقول التي تتغير:
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-03T00:00:00Z",
"history_since": "2026-05-30T00:00:00Z",
"activity_scope": "all_classified_activity",
"interval": "day",
"interval_seconds": 86400,
"history_period_count": 2,
"expected_buckets": 2
},
"purpose": "Classifies typed opaque user subjects by any supported classified product activity in each fixed period. It does not choose or infer a top event. new_within_observed_history, returning, resurrected, and dormant remain disjoint; anonymous and unidentified subjects are excluded from user counts, incomplete buckets are marked, and raw identifiers are never returned."
}
```
في الوضع التلقائي، يساوي `coverage.selected_events` قيمة `coverage.analysis_classified_events`. والعنصر الخامس في `limitations` هو `Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.`
### دورة الحياة دون مستخدمين
إذا لم يكن في نطاق التحليل ولا في التاريخ المرصود مستخدمون صالحون للاستخدام، تكون `buckets` فارغة ويحذف `summary` الحقل `latest_fully_observed_period`:
```json theme={null}
{
"schema_version": 2,
"summary": {
"observed_subjects": 0,
"analysis_active_subjects": 0,
"history_only_subjects": 0,
"returned_buckets": 0,
"fully_observed_buckets": 0,
"buckets_with_resurrection": 0,
"buckets_with_dormancy": 0
},
"buckets": []
}
```
المستخدمون الذين يظهرون في التاريخ المرصود فقط قد ينتجون مع ذلك فواصل زمنية فيها مستخدمون خاملون عندما لا يكون في نطاق التحليل نشاط.
### أخطاء دورة الحياة
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد هذه الطلبات `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| النسخة 1 دون `event`، أو النسخة 2 مع `event`، أو نسخة أخرى | `product analytics lifecycle activity selection is contradictory` |
| `history_period_count` خارج النطاق من `2` إلى `31` | `product analytics lifecycle history_period_count must be between 2 and 31` |
| فترات التاريخ المرصود أطول من 62 يومًا إجمالًا | `product analytics lifecycle history must not exceed 62 days` |
| أكثر من 100 فاصل زمني للتحليل | `product analytics lifecycle interval would exceed 100 analysis buckets` |
مثلًا، عشر فترات `week` للتاريخ المرصود تحتاج إلى 70 يومًا:
```json theme={null}
{
"error": "product analytics lifecycle history must not exceed 62 days",
"code": "validation_failed",
"next": "use fewer history periods or a narrower fixed interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
### اقرأ نطاق التحليل المختار
لاستجابات الأحداث المحددة `schema_version: 1`. ويعيد `query` فيها المُحدِّدات ويحذف `activity_scope`. أما الاستجابات التلقائية فلها `schema_version: 2` و`query.activity_scope: "all_classified_activity"`. وتحذف المُحدِّدات. قد يغيّر مُحدِّد مختلف النتيجة دون أي تغيير في النشاط الملتقَط.
## استجابة سلسلة المقياس
يقرأ `GET /api/telemetry/metrics/series` اسم مقياس محددًا واحدًا في مشروع واحد. انسخ الاسم من `GET /api/telemetry/metrics`. يجمّع هذا الطلب عدّادًا تفاضليًا (delta counter) حسب الخدمة:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "name=jobs.completed" \
--data-urlencode "since=2026-06-01T12:00:00Z" \
--data-urlencode "until=2026-06-01T12:15:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "group_by=service_name"
```
### نجاح سلسلة المقياس
تحتوي هذه الاستجابة المصطنعة على سلسلة واحدة لعدّاد تفاضلي. تقع ثلاث عيّنات بالقيم `2` و`3` و`5` في الفاصل الزمني الأول. وتقع عيّنتان بالقيمتين `1` و`4` في الفاصل الزمني الأخير. لا تقع أي عيّنة في الفاصل الزمني الأوسط، لذلك ليس للاستجابة نقطة له.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "jobs.completed",
"since": "2026-06-01T12:00:00Z",
"until": "2026-06-01T12:15:00Z",
"interval": "5m",
"interval_seconds": 300,
"group_by": "service_name",
"series_limit": 10
},
"purpose": "Shows how one metric changes over time without changing its meaning: gauges use sampled state, delta counters use change volume and rate, histograms use distributions, and cumulative streams stay raw when reset-safe change is ambiguous.",
"coverage": {
"samples": 5,
"series": 1,
"returned_series": 1,
"points": 2,
"expected_buckets_per_series": 3,
"first_seen_at": "2026-06-01T12:00:10Z",
"last_seen_at": "2026-06-01T12:14:50Z",
"truncated": false
},
"series": [
{
"identity": {
"kind": "counter",
"unit": "{job}",
"temporality": "delta",
"group_by": "service_name",
"group_value": "checkout-worker"
},
"status": "ready",
"aggregation": {
"code": "delta_sum",
"description": "Primary value is the sum of recorded changes in each bucket; rate_per_second normalizes that change by bucket width."
},
"sample_count": 5,
"points": [
{
"bucket_start": "2026-06-01T12:00:00Z",
"bucket_end": "2026-06-01T12:05:00Z",
"sample_count": 3,
"value": 10.0,
"last": 5.0,
"min": 2.0,
"max": 5.0,
"average": 3.3333333333333335,
"sum": 10.0,
"rate_per_second": 0.03333333333333333,
"trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
},
{
"bucket_start": "2026-06-01T12:10:00Z",
"bucket_end": "2026-06-01T12:15:00Z",
"sample_count": 2,
"value": 5.0,
"last": 4.0,
"min": 1.0,
"max": 4.0,
"average": 2.5,
"sum": 5.0,
"rate_per_second": 0.016666666666666666,
"trace_exemplars": []
}
]
}
],
"next_action": {
"code": "inspect_metric_change",
"target": "trace_summary",
"reason": "Open a trace exemplar from an unusual bucket to connect the metric change to spans, errors, logs, and release context."
}
}
```
### اقرأ سلسلة المقياس
تسجّل النقطة الأولى 10 مهام مكتملة، لا 10 عيّنات. يقسم `rate_per_second` هذا التغير على الفاصل الزمني الذي مدته 300 ثانية. و`last` هو آخر تغير مُدوَّن، لا المجموع. راجع [معاني تجميع المقاييس](/ar/concepts/telemetry#read-the-metric-value).
يحدد نوع السلسلة وطبيعتها الزمنية (temporality) قيمة `aggregation.code` والإحصاءات في كل نقطة. تحذف النقطة الإحصاء الذي لا ينطبق. الإحصاء المفقود ليس صفرًا.
| النوع والطبيعة الزمنية | `status` | `aggregation.code` | `value` | إحصاءات أخرى |
| - | - | - | - | - |
| `gauge`، `instant` | `ready` | `gauge_last` | آخر عيّنة | `last`، `min`، `max`، `average` |
| `counter`، `delta` | `ready` | `delta_sum` | مجموع التغيرات | `last`، `min`، `max`، `average`، `sum`، `rate_per_second` |
| `histogram`، `delta` | `ready` | `distribution_p95` | قيمة p95 تقريبية | `min`، `max`، `average`، `sum`، `p50`، `p95`، `p99` |
| أي نوع، `cumulative` | `limited` | `raw_cumulative_last` | آخر عيّنة خام | `last`، `min`، `max` |
| أي زوج آخر | `limited` | `raw_last` | آخر عيّنة خام | `last`، `min`، `max` |
`limited` استجابة ناجحة، لا خطأ. وهي تضيف `aggregation.limitation` الذي يشرح سبب عرض LogBrew للقيم الخام فقط. و`ready` لا تثبت أن الالتقاط كامل.
اقرأ `coverage` قبل أن ترسم مخططًا:
* يعدّ `samples` عيّنات كل السلاسل المطابقة، ومنها السلاسل التي لا تعيدها الاستجابة.
* يعدّ `series` السلاسل المطابقة. ويعدّ `returned_series` و`points` البيانات المُعادة.
* تكون قيمة `truncated` هي `true` عندما يحذف `series_limit` السلاسل الأقل حجمًا.
* `expected_buckets_per_series` هو عدد الفواصل الزمنية الممكنة في النطاق.
لا تضف نقطة لفاصل زمني ليس فيه عيّنات. لا تُدرج صفرًا ولا تنسخ القيمة السابقة. تعيد كل نقطة حتى 3 قيم في `trace_exemplars`. تربط العيّنة النموذجية للتتبّع (trace exemplar) عيّنة واحدة بتتبّع. ولا تشرح كل عيّنة في الفاصل الزمني. إذا لم تكن لأي نقطة عيّنة نموذجية للتتبّع، فقيمة `next_action.target` هي `metric_samples`.
### نطاق سلسلة المقياس وأخطاؤها
`project_id` و`name` و`since` مطلوبة. يمكن أن يحتوي `name` على 200 حرف على الأكثر. قيمة `interval` هي `auto` أو `1m` أو `5m` أو `15m` أو `1h` أو `6h` أو `1d`. القيمة الافتراضية `auto`، وهي تختار أصغر فاصل زمني يحتاج إلى 300 فاصل على الأكثر. ولا يمكن أن يحتاج الفاصل الصريح إلى أكثر من 500 فاصل.
قيمة `group_by` هي `none` أو `service_name` أو `release` أو `environment`. القيمة الافتراضية `none`. دون تجميع، تبقى الأنواع والوحدات والطبائع الزمنية المختلفة في سلاسل منفصلة. يقبل `series_limit` من `1` إلى `20`. القيمة الافتراضية `10`.
النتيجة الفارغة تعيد `200` مع `series: []` و`samples` صفرية. ويحذف الكائن `coverage` الحقلين `first_seen_at` و`last_seen_at`. وهذا لا يثبت أن التطبيق لم يرسل المقياس قط. تحقق من المشروع واسم المقياس والنطاق الزمني.
حذف `name` يعيد `422`:
```json theme={null}
{
"error": "metric series name is required",
"code": "validation_failed",
"next": "send the exact metric name returned by /api/telemetry/metrics",
"next_action": { "code": "fix_request", "target": "request" }
}
```
الفواصل الزمنية التي مدتها دقيقة واحدة عبر سبعة أيام تعيد `422`:
```json theme={null}
{
"error": "metric series interval would exceed 500 buckets",
"code": "validation_failed",
"next": "use interval=auto or select a wider interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
أخطاء `422` الأخرى هي `metric series group_by is not supported` و`metric series interval is not supported` و`metric series_limit must be between 1 and 20`.
## استجابة تحليل المسارات
يجد `POST /api/telemetry/analytics/paths` الأحداث المسماة قبل حدث مختار واحد أو بعده في الجلسة نفسها. الحدث المختار هو الحدث المرجعي. انسخ `kind` و`event_name` الخاصين به من `classified_activity.top_events`. يعيد المسار `schema_version: 1`. ولا يقبل `response_version` أو `analysis_unit`.
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"direction": "following",
"anchor": { "kind": "page_view", "event_name": "/checkout" },
"depth": 2,
"collapse_repeated": true,
"path_limit": 2
}
```
`direction` و`anchor` مطلوبان.
### نجاح المسارات
في هذه النتيجة المصطنعة، تحتوي أربع جلسات على الحدث المرجعي. يمثّل المساران المُعادان ثلاثًا من هذه الجلسات. ولا يُعاد مسار واحد أدنى ترتيبًا.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"direction": "following",
"anchor": { "kind": "page_view", "event_name": "/checkout" },
"depth": 2,
"collapse_repeated": true,
"path_limit": 2
},
"purpose": "Shows the highest-volume named product-event sequences immediately before or after one exact version-1 page view, screen view, or interaction inside explicit sessions. Following paths use the earliest matching anchor in each session; preceding paths use the latest. Optional exact property predicates classify only the anchor, while surrounding events preserve the real session journey. Results aggregate exact bounded sequences and never return raw session or subject identifiers.",
"summary": {
"anchored_sessions": 4,
"represented_sessions": 3,
"unrepresented_sessions": 1,
"returned_paths": 2,
"paths_truncated": true
},
"coverage": {
"classified_events": 12,
"named_events": 12,
"unnamed_events": 0,
"sessionized_events": 10,
"unsessionized_events": 2,
"anchor_events": 5,
"usable_anchor_events": 4,
"excluded_anchor_events": 1,
"traced_anchor_events": 1,
"event_name_rate": 1.0,
"sessionization_rate": 0.8333333333333334,
"anchor_session_coverage_rate": 0.8,
"anchor_trace_link_rate": 0.2,
"ordered_event_cap_per_session": 1024,
"limitations": [
"Paths include only supported version-1 classified events with exact derived names; arbitrary actions, technical spans, and raw identity values are excluded.",
"Paths stay inside application-supplied session boundaries and the selected half-open time range; activity beyond either boundary is not inferred.",
"Each session retains at most 1024 direction-nearest named events before anchoring, so exceptionally noisy sessions can be omitted or truncated.",
"Classified events without an explicit opaque session ID cannot participate in session paths.",
"Trace exemplars prove only that a matching anchor carried the same trace ID. They do not prove root cause, and deeper investigation depends on retained spans for that trace.",
"Some matching anchors lack trace IDs, so trace-linked path evidence covers only the reported traced_anchor_events population."
]
},
"paths": [
{
"rank": 1,
"sessions": 2,
"share_of_anchored_sessions": 0.5,
"traced_sessions": 1,
"trace_link_rate": 0.5,
"trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
"nodes": [
{ "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
{ "relative_position": 1, "kind": "interaction", "event_name": "checkout.submitted" },
{ "relative_position": 2, "kind": "interaction", "event_name": "checkout.completed" }
]
},
{
"rank": 2,
"sessions": 1,
"share_of_anchored_sessions": 0.25,
"traced_sessions": 0,
"trace_link_rate": 0.0,
"trace_exemplars": [],
"nodes": [
{ "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
{ "relative_position": 1, "kind": "interaction", "event_name": "checkout.failed" }
]
}
],
"next_action": {
"code": "inspect_path_trace",
"target": "/api/telemetry/traces/{trace_id}/investigation",
"reason": "Open an exemplar from the material path to connect the product journey to retained spans, issues, logs, actions, metrics, and release context as evidence rather than a root-cause claim."
}
}
```
### اقرأ المسارات
يقسم `share_of_anchored_sessions` جلسات المسار على الجلسات الأربع كلها التي فيها الحدث المرجعي. النسبتان 50% و25%، لا 67% و33%. يعدّ `unrepresented_sessions` الجلسات التي فيها الحدث المرجعي ولا يمثّلها أي مسار مُعاد. و`paths_truncated: true` تعني أن النتيجة غير مكتملة.
تعدّ التغطية الأحداث، لا الجلسات. هنا تطابق خمسة أحداث الحدث المرجعي، لكن أحدها ليس له معرّف جلسة. لا يمكن لهذا الحدث أن يدخل في مسار. يعيد كل مسار حتى 3 عيّنات نموذجية للتتبّع. استخدم معرّف تتبّع من استجابتك أنت. رابط التتبّع لا يبيّن سبب إجراء المستخدم أو سبب الفشل.
| الحقل | المعنى |
| - | - |
| `following` | يبدأ عند أبكر حدث مرجعي مطابق في كل جلسة. موضع الحدث المرجعي `0`. وللعقد اللاحقة مواضع موجبة. |
| `preceding` | ينتهي عند آخر حدث مرجعي مطابق في كل جلسة. للعقد السابقة مواضع سالبة. وموضع الحدث المرجعي `0`. |
| `depth` | عدد العقد المجاورة للحدث المرجعي، دون احتساب الحدث المرجعي. من `1` إلى `8`. القيمة الافتراضية `4`. قد يكون للمسار عقد أقل. |
| `collapse_repeated` | يدمج العقد المتتالية التي لها النوع والاسم نفسيهما. القيمة الافتراضية `true`. |
| `path_limit` | الحد الأقصى للمسارات المُعادة، مرتبة حسب عدد الجلسات. من `1` إلى `20`. القيمة الافتراضية `10`. |
العقد مرتبة زمنيًا في الاتجاهين كليهما. المسار ليس إعادة تشغيل كاملة للجلسة. يقرأ LogBrew 1024 حدثًا مسمى على الأكثر لكل جلسة قبل أن يختار الحدث المرجعي: أبكر الأحداث لـ `following`، وأحدث الأحداث لـ `preceding`. وقد يُحذف الحدث المرجعي الذي يقع خارج هذا الحد.
### صفِّ الحدث المرجعي حسب خاصية
أرسل حتى أربعة عناصر في `property_filters`، لكل منها `key` و`value` محددان تمامًا. انسخ المفتاح من [فهرس الخصائص](#analytics-property-catalog). تنطبق عوامل التصفية على الحدث المرجعي فقط، لا على الأحداث المحيطة به. القيم حساسة لحالة الأحرف. عندما توجد عوامل تصفية، يعيدها `query`، ويبلّغ `coverage.anchor_property_filters` بما يلي:
| الحقل | المعنى |
| - | - |
| `context_events` | الأحداث المرجعية في النطاق قبل عوامل تصفية الخصائص. |
| `property_ready_events` | الأحداث المرجعية التي فيها كل مفتاح مطلوب. |
| `missing_property_events` | الأحداث المرجعية التي ينقصها مفتاح مطلوب واحد أو أكثر. |
| `matching_events` | الأحداث المرجعية التي تطابق قيمها كل عامل تصفية. |
| `nonmatching_value_events` | الأحداث المرجعية التي فيها كل مفتاح لكن بقيمة مختلفة. |
| `property_ready_rate` | `property_ready_events` مقسومًا على `context_events`. |
| `match_rate` | `matching_events` مقسومًا على `property_ready_events`. |
المفاتيح المفقودة والقيم المختلفة تحتاج إلى إصلاحات مختلفة. لا تجمعها معًا. يُحذف الكائن عندما لا يكون في الطلب عامل تصفية للخصائص.
### المسارات الفارغة والطلبات المرفوضة
قد تكون مصفوفة `paths` الفارغة استجابة `200` ناجحة. اقرأ `summary` و`coverage` و`next_action`. تميّز هذه الرموز بين الأسباب: `capture_product_activity` و`choose_captured_path_anchor` و`capture_anchor_properties` و`improve_anchor_property_coverage` و`verify_anchor_property_values` و`sessionize_product_activity` و`narrow_or_move_path_anchor`.
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد هذه الطلبات `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| `depth` خارج النطاق من `1` إلى `8` | `product analytics path depth must be between 1 and 8` |
| `path_limit` خارج النطاق من `1` إلى `20` | `product analytics path_limit must be between 1 and 20` |
| أكثر من أربعة عوامل تصفية للخصائص | `product analytics paths accept at most four exact anchor property filters` |
| مفتاح ليس في فهرس الخصائص | `product analytics path property keys must be supported privacy-safe keys` |
| المفتاح نفسه مرتين | `product analytics path property keys must be unique` |
| قيمة فارغة، أو قيمة أطول من 256 حرفًا، أو حرف تحكم | `product analytics path property values must be non-empty, control-free, and at most 256 characters` |
مثلًا، `depth: 0` يعيد:
```json theme={null}
{
"error": "product analytics path depth must be between 1 and 8",
"code": "validation_failed",
"next": "use depth from 1 through 8 adjacent named events",
"next_action": { "code": "fix_request", "target": "request" }
}
```
## فهرس خصائص التحليلات
يسرد `GET /api/telemetry/analytics/properties` مفاتيح الخصائص في أحداث المنتج المصنَّفة في مشروع واحد. استخدم المفاتيح في [مقارنات الشرائح](#analytics-segment-comparison) وفي عوامل تصفية الحدث المرجعي للمسارات. يعيد الفهرس المفاتيح والأعداد. ولا يعيد قيم الخصائص أو الهويات أبدًا.
### اقرأ مفاتيح الخصائص المتاحة
أرسل `project_id` و`since`. يمكنك أيضًا إرسال `until` و`service_name` و`release` و`environment` و`limit` و`response_version`. يقبل `limit` من `1` إلى `50` مفتاحًا. القيمة الافتراضية `20`. أرسل `response_version=2` لتحصل على قيمة `estimation.method` العامة.
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "project_id=" \
--data-urlencode "since=2026-06-01T00:00:00Z" \
--data-urlencode "until=2026-06-02T00:00:00Z" \
--data-urlencode "limit=20" \
--data-urlencode "response_version=2"
```
### نجاح فهرس الخصائص
في هذه النتيجة المصطنعة، يوجد 100 حدث مصنَّف. التُقطت خمسة منها قبل فهرس الخصائص الحالي.
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T00:00:00Z",
"until": "2026-06-02T00:00:00Z",
"limit": 20
},
"purpose": "Discovers bounded privacy-safe runtime, framework, operating-system, device, application, and custom-tag keys captured on classified product events. It reports migration, capture, privacy-filtering, and per-key coverage without returning property values or identities, so humans and agents can build exact segment comparisons without guessing which dimensions exist.",
"summary": {
"classified_events": 100,
"available_property_keys": 3,
"returned_properties": 3
},
"coverage": {
"indexed_events": 95,
"unindexed_events": 5,
"complete_index_events": 95,
"incomplete_index_events": 0,
"privacy_filtered_events": 4,
"events_with_properties": 90,
"index_coverage_rate": 0.95,
"property_capture_rate": 0.9,
"properties_truncated": false,
"values_returned": false,
"limitations": [
"Property discovery returns keys and aggregate counts only; property values and identity columns are never returned.",
"Property filters use exact case-sensitive bounded string equality and combine with logical AND inside each segment.",
"Historical events written before the current property index are excluded from property descriptors and exact property filters.",
"Direct-identity, credential-like, and network-address custom tag keys were intentionally excluded from the analytics property index."
]
},
"estimation": {
"count_accuracy": "approximate",
"method": "approximate_distinct",
"description": "Available property-key and per-key distinct-value counts are approximate distinct counts. Classified-event, index-coverage, privacy-filtering, and per-key event counts are exact within the selected fully evaluated window."
},
"properties": [
{
"key": "resource.runtime.name",
"source": "standard_context",
"value_type": "string",
"events": 90,
"coverage_rate": 0.9,
"distinct_values": 2
},
{
"key": "resource.application.version",
"source": "standard_context",
"value_type": "string",
"events": 70,
"coverage_rate": 0.7,
"distinct_values": 4
},
{
"key": "tag.plan",
"source": "custom_tag",
"value_type": "string",
"events": 60,
"coverage_rate": 0.6,
"distinct_values": 3
}
],
"next_action": {
"code": "compare_property_segments",
"target": "/api/telemetry/analytics/segments/compare",
"reason": "Use exact returned keys with locally known values to compare behavior while preserving identity and property-value privacy."
}
}
```
### فسّر الفهرس
قيمة `source` هي `standard_context` لمفتاح سياق قياسي، مثل `resource.runtime.name`، أو `custom_tag` لمفتاح يبدأ بـ `tag.`. وقيمة `value_type` هي دائمًا `string`. و`properties` مرتبة حسب `events`، من الأعلى إلى الأدنى.
يوجد `tag.plan` في 60 حدثًا من أصل 100 حدث مصنَّف. وله نحو 3 قيم مختلفة. لا يعرض الوصف هذه القيم. استخدم قيمًا تعرفها من تطبيقك. لا تخمّن قيمة من عدد. قد يحمل الحدث الواحد عدة مفاتيح، لذلك لا تجمع أعداد `events` الخاصة بكل مفتاح.
| الحقل | المعنى |
| - | - |
| `summary.classified_events` | الأحداث المصنَّفة في النطاق. وهذا هو المقام لكل `coverage_rate`. |
| `summary.available_property_keys` | العدد التقديري للمفاتيح المختلفة، لا عدد الصفوف المُعادة. |
| `coverage.unindexed_events` | الأحداث الملتقَطة قبل فهرس الخصائص الحالي. لا يمكنها أن تضيف مفاتيح. |
| `coverage.incomplete_index_events` | الأحداث التي فيها بعض السياق المشوَّه أو المقتطَع. وتبقى مفاتيحها الصالحة محسوبة. |
| `coverage.privacy_filtered_events` | الأحداث التي أزال LogBrew منها مفاتيح وسوم مخصصة حساسة. وهذا ليس عددًا للمفاتيح. |
| `coverage.properties_truncated` | `true` عندما توجد مفاتيح أكثر من `limit`. ضيّق النطاق، أو زِد `limit` حتى 50. |
| `coverage.values_returned` | دائمًا `false`. |
مصفوفة `properties` الفارغة لا تثبت أن المشروع ليس فيه أحداث منتج. اقرأ `summary` و`coverage` و`next_action`.
### أخطاء فهرس الخصائص
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، يعيد `limit=0` أو `limit=51` الاستجابة `422`:
```json theme={null}
{
"error": "product analytics property limit must be between 1 and 50",
"code": "validation_failed",
"next": "use limit=1 through limit=50",
"next_action": { "code": "fix_request", "target": "request" }
}
```
قيمة `response_version` غير `1` أو `2` تعيد `product analytics response_version must be 1 or 2`. يتحقق LogBrew من `response_version` قبل القيم الأخرى.
الطلب `POST` يعيد `405`:
```json theme={null}
{
"error": "Method not allowed",
"code": "method_not_allowed",
"next": "send GET /api/telemetry/analytics/properties with required project_id and since plus optional until, service_name, release, environment, limit, or response_version query parameters",
"next_action": { "code": "use_supported_method", "target": "api_method" }
}
```
## مقارنة شرائح التحليلات
يقارن `POST /api/telemetry/analytics/segments/compare` عدد المرات التي تصل فيها الجلسات أو المستخدمون إلى حدث محدد واحد عبر 2 إلى 4 شرائح في مشروع واحد. تختار الشريحة الأحداث حسب الخدمة والإصدار والبيئة وقيم الخصائص. الشريحة الأولى هي الشريحة الأساسية.
### حدّد المقارنة
أرسل نص JSON هذا مع مصادقة الحساب و`Content-Type: application/json`. هنا `basic` و`premium` قيمتا خطة في تطبيق المثال، لا خطط LogBrew:
```json theme={null}
{
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "1h",
"analysis_unit": "session",
"response_version": 2,
"target": { "kind": "interaction", "event_name": "checkout_completed" },
"segments": [
{
"key": "basic",
"label": "Basic plan",
"service_name": "checkout-api",
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "basic" }]
},
{
"key": "premium",
"label": "Premium plan",
"service_name": "checkout-api",
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "premium" }]
}
]
}
```
`target` و`segments` مطلوبان. قيمة `analysis_unit` هي `session` أو `identified_user`. القيمة الافتراضية `session`، وهي تعدّ الجلسات، لا الأشخاص. يقبل `interval` القيم نفسها التي تقبلها النظرة العامة. القيمة الافتراضية `auto`.
تحتاج كل شريحة إلى `key` فريد و`label` ومجموعة عوامل تصفية مختلفة:
* `key`: من 1 إلى 32 بايت. ابدأ بحرف ASCII صغير أو رقم. استخدم فقط أحرف ASCII الصغيرة والأرقام و`_` و`-`.
* `label`: من 1 إلى 80 حرفًا، دون أحرف تحكم.
* `service_name`، `release`، `environment`: اختيارية. كل قيمة من 1 إلى 256 حرفًا، دون أحرف تحكم.
* `property_filters`: من 0 إلى 4 عوامل تصفية. يمكن أن يظهر كل مفتاح مرة واحدة في الشريحة. يجب أن يطابق الحدث كل عوامل تصفية الشريحة. القيم حساسة لحالة الأحرف، ومن 1 إلى 256 حرفًا، ويزيل LogBrew المسافات من بدايتها ونهايتها.
الشريحة التي ليس فيها عوامل تصفية تختار كل النشاط المصنَّف في المشروع والنطاق الزمني. يمكن أن تتداخل الشرائح. اختلاف الاسم أو المفتاح لا يجعل مجموعتي عوامل تصفية متطابقتين صالحتين.
### نجاح مقارنة الشرائح
في هذه النتيجة المصطنعة، تصل الشريحة الأساسية إلى إتمام الشراء في 10 جلسات من أصل 50. وتصل إليه شريحة premium في 18 جلسة من أصل 60.
```json theme={null}
{
"schema_version": 2,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"since": "2026-06-01T11:00:00Z",
"until": "2026-06-01T12:00:00Z",
"interval": "1h",
"interval_seconds": 3600,
"analysis_unit": "session",
"target": { "kind": "interaction", "event_name": "checkout_completed" },
"segments": [
{
"key": "basic",
"label": "Basic plan",
"service_name": "checkout-api",
"release": null,
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "basic" }]
},
{
"key": "premium",
"label": "Premium plan",
"service_name": "checkout-api",
"release": null,
"environment": "production",
"property_filters": [{ "key": "tag.plan", "value": "premium" }]
}
]
},
"purpose": "Compares how often explicit sessions or typed opaque user subjects reach one exact versioned page-view, screen-view, or interaction outcome across two through four named service, release, environment, and exact safe-property segments. It distinguishes missing property capture from nonmatching values, returns time trends and descriptive differences from the first segment, and never returns identities or claims causality or statistical significance.",
"summary": {
"segment_count": 2,
"baseline_segment_key": "basic",
"segments_with_eligible_units": 2,
"segments_with_target_events": 2,
"segments_with_reached_units": 2
},
"confidence": {
"interpretation": "descriptive_only",
"unique_count_accuracy": "approximate",
"estimation_method": "approximate_distinct",
"causal_inference": "not_established",
"statistical_significance": "not_tested",
"segment_overlap": "possible",
"limitations": [
"Unique session or typed user-subject counts use bounded cardinality estimates; event and capture-coverage totals are exact within the fully evaluated window.",
"Segments are evaluated independently and may overlap, so their totals must not be added or interpreted as a population partition.",
"Differences and relative lift are descriptive only. They do not control for exposure, assignment, seasonality, selection bias, or other confounders.",
"Bucket-level unique counts are recalculated inside each bucket and are not additive across the series.",
"Session analysis compares visits or app sessions, not unique people.",
"At least one segment has classified events without the selected unit ID; compare unit_coverage_rate before interpreting reach differences.",
"Property predicates are exact case-sensitive string matches. Events without the current property index or every requested key are excluded from segment results and reported separately as missing_property_events.",
"Direct-identity, credential-like, and network-address custom tag keys are excluded from the analytics property index and cannot be used for segmentation."
]
},
"segments": [
{
"key": "basic",
"label": "Basic plan",
"eligible_units": 50,
"reached_units": 10,
"reach_rate": 0.2,
"usable_target_events_per_reached_unit": 1.8,
"coverage": {
"classified_events": 200,
"unit_identified_events": 190,
"excluded_events": 10,
"unit_coverage_rate": 0.95,
"target_events": 20,
"usable_target_events": 18,
"excluded_target_events": 2,
"target_unit_coverage_rate": 0.9,
"traced_target_events": 10,
"target_trace_link_rate": 0.5,
"property_filters": {
"context_events": 500,
"property_ready_events": 480,
"missing_property_events": 20,
"property_ready_rate": 0.96,
"matching_events": 200,
"nonmatching_value_events": 280,
"match_rate": 0.4166666666666667
}
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T12:00:00Z",
"classified_events": 200,
"eligible_units": 50,
"target_events": 20,
"usable_target_events": 18,
"reached_units": 10,
"reach_rate": 0.2
}
]
},
{
"key": "premium",
"label": "Premium plan",
"eligible_units": 60,
"reached_units": 18,
"reach_rate": 0.3,
"usable_target_events_per_reached_unit": 1.8888888888888888,
"coverage": {
"classified_events": 240,
"unit_identified_events": 228,
"excluded_events": 12,
"unit_coverage_rate": 0.95,
"target_events": 36,
"usable_target_events": 34,
"excluded_target_events": 2,
"target_unit_coverage_rate": 0.9444444444444444,
"traced_target_events": 18,
"target_trace_link_rate": 0.5,
"property_filters": {
"context_events": 500,
"property_ready_events": 480,
"missing_property_events": 20,
"property_ready_rate": 0.96,
"matching_events": 240,
"nonmatching_value_events": 240,
"match_rate": 0.5
}
},
"series": [
{
"bucket_start": "2026-06-01T11:00:00Z",
"bucket_end": "2026-06-01T12:00:00Z",
"classified_events": 240,
"eligible_units": 60,
"target_events": 36,
"usable_target_events": 34,
"reached_units": 18,
"reach_rate": 0.3
}
],
"comparison_to_baseline": {
"eligible_units_difference": 10,
"reached_units_difference": 8,
"target_events_difference": 16,
"reach_rate_difference": 0.09999999999999998,
"relative_reach_rate_lift": 0.4999999999999998
}
}
],
"next_action": {
"code": "investigate_segment_paths",
"target": "/api/telemetry/analytics/paths",
"reason": "Inspect paths around the target in the weakest segment, then use correlated traces to explain a material behavioral difference."
}
}
```
### اقرأ المعدّلات والفروق
يقدّر `eligible_units` عدد الجلسات أو المستخدمين الذين لهم نشاط مصنَّف في الشريحة. ويقدّر `reached_units` عدد من وصل منهم إلى الهدف. و`reach_rate` يساوي `reached_units` مقسومًا على `eligible_units`. لا تُحسب الأحداث التي ليس لها معرّف الوحدة المختارة ضمن هذه الوحدات.
معدّل الشريحة الأساسية 20%. ومعدّل شريحة premium هو 30%. الفرق 10 نقاط مئوية. والزيادة النسبية 50%، لا 10%. تأتي أخطاء الكسور العشرية الصغيرة من حساب الفاصلة العائمة. قرّب المعدّلات للعرض، لكن احسب بالقيم المُعادة. ليس للشريحة الأساسية `comparison_to_baseline`. وتُحذف الزيادة النسبية عندما يكون معدّل وصول الشريحة الأساسية صفرًا.
في `query`، يكون عامل تصفية الشريحة الذي لم ترسله بالقيمة `null`. وتُحذف قائمة `property_filters` الفارغة.
لـ `coverage.property_filters` الحقول نفسها التي لـ [تغطية عوامل تصفية الحدث المرجعي للمسارات](#filter-the-anchor-by-property). هنا يساوي `matching_events` قيمة `classified_events`. أبقِ المفاتيح المفقودة والقيم المختلفة منفصلة. يمكن أن تتداخل الشرائح، وقد تظهر الجلسة الواحدة في عدة فواصل زمنية. لا تجمع أعداد الوحدات عبر الشرائح أو الفواصل الزمنية.
المقارنة وصفية. قيمة `confidence.causal_inference` هي `not_established`، وقيمة `confidence.statistical_significance` هي `not_tested`. معدّل 30% مقابل 20% لا يبيّن أن خطةً تسببت في زيادة عمليات إتمام الشراء.
### أخطاء مقارنة الشرائح
بالإضافة إلى [أخطاء النطاق المشتركة](#shared-scope-errors)، تعيد هذه الطلبات `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| أقل من شريحتين أو أكثر من 4 شرائح | `product analytics segment comparison requires two through four segments` |
| شريحتان لهما المفتاح نفسه | `product analytics segment keys must be unique` |
| شريحتان لهما عوامل التصفية نفسها | `product analytics segment filters must be unique` |
| مفتاح ليس من 1 إلى 32 بايت مسموحًا | `product analytics segment keys must be 1 through 32 machine-safe bytes` |
| اسم فارغ أو طويل جدًا أو فيه حرف تحكم | `product analytics segment labels must be non-empty, control-free, and at most 80 characters` |
| قيمة عامل تصفية فيها حرف تحكم | `product analytics segment filters must be control-free` |
| أكثر من أربعة عوامل تصفية للخصائص في الشريحة | `product analytics segments accept at most four exact property filters` |
| مفتاح ليس في فهرس الخصائص | `product analytics segment property keys must be supported privacy-safe keys` |
| مفتاح الخاصية نفسه مرتين في الشريحة | `product analytics segment property keys must be unique within each segment` |
| قيمة خاصية فارغة أو طويلة جدًا أو فيها حرف تحكم | `product analytics segment property values must be non-empty, control-free, and at most 256 characters` |
| `response_version` بقيمة غير `1` أو `2` | `product analytics response_version must be 1 or 2` |
أخطاء `interval` هي نفسها [أخطاء النظرة العامة](#overview-errors).
مثلًا، شريحتان لهما مفتاحان مختلفان وعوامل تصفية متطابقة تعيدان:
```json theme={null}
{
"error": "product analytics segment filters must be unique",
"code": "validation_failed",
"next": "change at least one exact service_name, release, environment, or property filter",
"next_action": { "code": "fix_request", "target": "request" }
}
```
اختلاف الاسم أو ترتيب عوامل تصفية الخصائص لا يغيّر الأحداث المختارة. فشل التحقق ليس دليلًا على أنه لا توجد أحداث مطابقة.
الطلب `GET` يعيد `405`:
```json theme={null}
{
"error": "Method not allowed",
"code": "method_not_allowed",
"next": "send POST /api/telemetry/analytics/segments/compare with project_id, since, one exact target, two through four named segments, and optional until, interval, analysis_unit, property_filters, or response_version JSON fields",
"next_action": { "code": "use_supported_method", "target": "api_method" }
}
```
## استجابة حجم الإشارات
يعدّ `GET /api/telemetry/summary/volume` الإشارات المحتفَظ بها لمشروع واحد ونطاق زمني واحد. ويتطلب `project_id` و`since`. ولا يقبل `project_ids`.
لا يمكن أن يكون `until` في المستقبل. إذا حذفته، فالنهاية هي وقت الطلب. وقيمة `since` المختصرة مثل `24h` تُحسب رجوعًا من `until`. قيمة `interval` هي `auto` أو `1m` أو `5m` أو `15m` أو `1h` أو `6h` أو `1d`. القيمة الافتراضية `auto` تختار أصغر فاصل زمني يحتاج إلى 120 فاصلًا على الأكثر. ولا يمكن أن يحتاج الطلب إلى أكثر من 500 فاصل. قيمة `response_version` الوحيدة هي `1`.
### أعداد الإشارات
تغطي هذه الاستجابة المصطنعة فاصلين زمنيين مدة كل منهما دقيقة واحدة. نُفّذ الطلب الساعة 12:02 بتوقيت UTC دون `until`. لدى الحساب سياسة احتفاظ بالبيانات مدتها 30 يومًا. اقرأ السياسة وتاريخ القطع المُعادين. لا تفترض أن هذه القيم تنطبق على حسابك.
```json theme={null}
{
"schema_version": 1,
"query": {
"project_id": "11111111-1111-4111-8111-111111111111",
"requested_since": "2026-09-08T12:00:00Z",
"since": "2026-09-08T12:00:00Z",
"until": "2026-09-08T12:02:00Z",
"interval": "1m",
"interval_seconds": 60,
"bucket_alignment": "query_relative_utc_half_open",
"bucket_count": 2,
"service_name": "checkout-api",
"release": "api@1.2.3",
"environment": "production"
},
"purpose": "Compares retained issue occurrences, log events, unique traces, action events, and metric points over one exact project and time scope. Every lane is independently scalable, uses explicit zero-filled half-open buckets, returns no source telemetry rows, and qualifies retention and sampling so different signal volumes are not mistaken for equivalent impact.",
"series": [
{
"signal": "issues",
"count_unit": "issue_occurrences",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "logs",
"count_unit": "log_events",
"total": 3,
"peak": 2,
"non_empty_buckets": 2,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 2 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 1 }
]
},
{
"signal": "traces",
"count_unit": "unique_traces_by_first_observed_span",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "actions",
"count_unit": "action_events",
"total": 1,
"peak": 1,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
]
},
{
"signal": "metrics",
"count_unit": "metric_points",
"total": 2,
"peak": 2,
"non_empty_buckets": 1,
"points": [
{ "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 0 },
{ "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 2 }
]
}
],
"coverage": {
"storage_evaluation": "complete",
"output_truncation": "not_truncated",
"payload_shape": "aggregate_only",
"count_precision": "exact",
"integer_safety": "javascript_safe",
"javascript_safe_integer_max": 9007199254740991,
"returned_series": 5,
"returned_points": 10,
"max_buckets_per_series": 500,
"retention": {
"policy_days": 30,
"cutoff": "2026-08-09T12:02:00Z",
"window_clipped": false
},
"sampling": {
"server": "not_applied",
"upstream": "unknown"
},
"limitations": ["upstream_sampling_unknown", "release_volume_not_included"]
}
}
```
### اقرأ كل عدد بوحدته
| الإشارة | ما يعدّه `total` | لا تقرأه على أنه |
| - | - | - |
| `issues` | مرات حدوث المشكلات المحتفَظ بها | مشكلات مجمّعة أو مستخدمون متأثرون |
| `logs` | أحداث السجلات المحتفَظ بها | طلبات |
| `traces` | معرّفات التتبّع الفريدة، محسوبة عند أول Span محتفَظ به لها في هذا النطاق | Spans أو بدايات تتبّعات طوال عمرها |
| `actions` | أحداث الإجراءات المحتفَظ بها | مستخدمون أو جلسات |
| `metrics` | نقاط المقاييس المحتفَظ بها | مجموع قيم المقاييس |
`total` هو مجموع أعداد الفواصل الزمنية في السلسلة. و`peak` هو أكبر عدد في فاصل زمني منها. ويعدّ `non_empty_buckets` الفواصل الزمنية التي عددها أكبر من صفر. تظهر السلاسل الخمس دائمًا بهذا الترتيب. لا تدمج أعداد الإشارات المختلفة في درجة تأثير واحدة.
تبدأ الفواصل الزمنية عند `query.since`. يشمل الفاصل الزمني بدايته ولا يشمل نهايته. وقد يكون الفاصل الأخير أقصر من الفاصل المحدد. ليس في الاستجابة سلسلة لأعداد الإصدارات. لا تقرأ `release_volume_not_included` على أنه صفر إصدارات.
### النطاقات الفارغة والمقصَّرة
إذا لم تطابق أي إشارة، تبقى السلاسل الخمس كلها، ولنقاطها أعداد صفرية صريحة. أما الطلب الفاشل فمختلف. لا تستبدل الخطأ بمخطط مملوء بالأصفار.
قارن `query.requested_since` بـ `query.since`. إذا قصّر الاحتفاظ بالبيانات النطاق، تكون قيمة `coverage.retention.window_clipped` هي `true`، ويحتوي `limitations` على `retention_window_clipped`. إذا لم يبقَ أي جزء من النطاق المطلوب، تكون قيمة `query.bucket_count` هي `0`، ولكل سلسلة مصفوفة `points` فارغة. وهذا لا يثبت أنه لم تقع أحداث في تلك الفترة.
تكون قيمة `policy_days` هي `null` ويُحذف `cutoff` عندما لا ينطبق حد للاحتفاظ بالبيانات. وقيمة `sampling.upstream` هي دائمًا `unknown`، حتى عندما تكون قيمة `storage_evaluation` هي `complete`. لا تدّعِ أن الاستجابة تعدّ كل حدث أنتجه التطبيق.
### طلبات حجم الإشارات المرفوضة
تعيد هذه الطلبات `422` و`validation_failed`:
| السبب | `error` |
| - | - |
| لا يوجد `project_id` | `signal volume project_id is required` |
| لا يوجد `since` | `signal volume since is required` |
| `until` بعد وقت الطلب | `signal volume until must not be in the future` |
| النطاق أطول من 31 يومًا | `signal volume range must not exceed 31 days` |
| فاصل صريح يحتاج إلى أكثر من 500 فاصل زمني | `signal volume interval would exceed 500 buckets` |
| `response_version` بقيمة غير `1` | `signal volume response_version must be 1` |
مثلًا:
```json theme={null}
{
"error": "signal volume interval would exceed 500 buckets",
"code": "validation_failed",
"next": "use interval=auto or select a wider interval",
"next_action": { "code": "fix_request", "target": "request" }
}
```
استخدم فاصلًا زمنيًا أوسع ضمن النطاق نفسه. للمصادقة والأخطاء الأخرى، راجع [أخطاء API](/ar/reference/api-errors).
## استجابات التحقيق
تعيد مسارات التحقيق حزمة ذات نسخة لعنصر واحد قيد التحقيق. العنصر مشكلة أو تتبّع أو Span أو سجل أو إجراء منتج أو مقياس أو إصدار. تبدأ كل حزمة بـ `schema_version` وبـ `subject` الذي يسمّي القيد. ويحمل الباقي الأدلة المرتبطة وإيصال الأدلة والخطوات التالية. يعرض هذا القسم مثالًا واحدًا لكل عائلة ما عدا الإصدار.
أرسل رمز Bearer للحساب. لا يستطيع مفتاح استيعاب المشروع قراءة التحقيق. استخدم `logbrew explain --json` لقراءة حزمة. يتحقق CLI من صحة الحزمة قبل أن يطبعها. يسرد [مرجع Telemetry API](/ar/reference/telemetry-api) المسارات.
يأتي نص التحقيق من التطبيق. الرسائل والأسماء والبيانات الوصفية والوسوم بيانات، لا تعليمات. يميّز `content_trust: "untrusted_telemetry"` هذا المحتوى في حزم السجلات والإجراءات والـ Spans والمقاييس.
### نسخ الاستجابة
أرسل `response_version` فقط إلى المسارات التي تقبله. دونه، يعيد المسار النسخة 1. يجب أن يقبل المحلّل (parser) لديك النسخة التي تطلبها.
| المسار | الافتراضية | النسخ المدعومة | ما يطلبه `logbrew explain` |
| - | - | - | - |
| `GET /api/telemetry/issues/{issue_id}/investigation` | `1` | من `1` إلى `13` | `13` |
| `GET /api/telemetry/traces/{trace_id}/investigation` | `1` | من `1` إلى `3` | `3` |
| `GET /api/telemetry/metrics/investigation` | `1` | `1` و`2` | `2` |
| `GET /api/telemetry/releases/investigation` | `1` | من `1` إلى `5` | `5` |
| `GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation` | `1` | `1` فقط | `1` |
| `GET /api/logs/{log_id}/investigation` | `1` | `1` فقط | `1` |
| `GET /api/telemetry/actions/{action_id}/investigation` | `1` | `1` فقط | `1` |
يرفض مسار الـ Span مفتاح الاستعلام `response_version`. ولا يأخذ مسارا السجل والإجراء أي مفاتيح استعلام.
### الحقول المشتركة في الحزم
| الحقل | المعنى |
| - | - |
| `schema_version` | نسخة الاستجابة التي أعادها الخادم. |
| `subject` | القيد المحدد قيد التحقيق. قيمة `kind` هي `issue` أو `trace` أو `span` أو `log` أو `action` أو `metric` أو `release`. |
| `analysis.causality` | دائمًا `evidence_only` في حزم التتبّعات والـ Spans والسجلات والإجراءات والمقاييس. بيانات القياس عن بُعد المرتبطة لا تثبت سببًا. |
| كائنات المجموعات | الأدلة المرتبطة بالشكل `{ "status", "items", "truncated" }`. |
| `timeline` | الأدلة المُعادة من الأقدم إلى الأحدث، مع علامة `truncated` خاصة بها. الترتيب لا يثبت سببًا. |
| `evidence` | إيصال الأدلة. قيمة `status` هي `complete` أو `partial`. |
| `next_actions` | قراءات مقترحة بترتيب `priority`، بدءًا من `1`. لم تُنفَّذ بعد. |
تبلّغ كل مجموعة مرتبطة عن `status` واحد للإتاحة:
| الحالة | المعنى | سلوك العميل |
| - | - | - |
| `available` | اكتملت القراءة وأعادت عناصر. | اعرض العناصر وعلامة `truncated`. |
| `not_linked` | ليس للعنصر قيد التحقيق معرّف لهذا الرابط، مثل معرّف التتبّع. | اشرح أن الرابط مفقود. لا تبنِ رابطًا من الطوابع الزمنية. |
| `not_found` | اكتملت القراءة ولم تجد أدلة محتفَظًا بها. | اعرض نتيجة فارغة. |
| `unavailable` | فشلت القراءة الاختيارية. يبقى العنصر قيد التحقيق صالحًا. | أبقِ العنصر ظاهرًا. أعد المحاولة لاحقًا. لا تعرض صفر عناصر على أنه نتيجة. |
لإيصال الأدلة أربع قوائم مرتبة من أسماء الحقول الثابتة: `captured_fields` و`missing_fields` و`redacted_fields` و`truncated_fields`. تكون قيمة `status` هي `complete` فقط عندما تكون القوائم الثلاث الأخيرة فارغة. البيانات المحجوبة ليست بيانات مفقودة. والبيانات المقتطَعة ليست بيانات كاملة. لا تملأ قيمة محجوبة أو مقتطَعة.
### حدود التحقيق
تحدّ هذه الحدود الاستجابة الواحدة. تبيّن علامة `truncated` أو عنصر في `truncated_fields` أن حدًا ما حذف بيانات.
| الأدلة | الحد |
| - | - |
| العناصر المرتبطة في مجموعة واحدة | 20 |
| الـ Spans المحتفَظ بها المقروءة لتتبّع واحد | 1,000 |
| عناصر `timeline` | 50 لحزم السجلات والإجراءات والـ Spans. و100 لحزم التتبّعات والمقاييس. |
| السمات المنظّمة والخصائص والبيانات الوصفية | 64 قيمة مفردة، و4 مستويات من الكائنات أو المصفوفات، و16 عنصرًا في كل مصفوفة، و512 حرفًا في كل سلسلة نصية |
| النطاق الزمني للارتباط | 5 دقائق قبل السجل أو الإجراء أو حدوث المشكلة المختار وبعده. وللتتبّع أو الـ Span، 5 دقائق قبل البداية وبعد النهاية، و24 ساعة على الأكثر. |
يسرد قسم كل عائلة حدوده الخاصة.
### استجابة التحقيق في المشكلة
استخدم `GET /api/telemetry/issues/{issue_id}/investigation` لقراءة الأدلة لحدوث واحد من مشكلة مجمّعة. تبيّن [إرشادات التحقيق في مشكلة](/ar/guides/investigate-an-issue) كيف تقرأ الأدلة بالترتيب. اطلب النسخة 13:
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/issues/$LOGBREW_ISSUE_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "response_version=13" \
--data-urlencode "selection=recommended"
```
مفاتيح الاستعلام هي `response_version` و`selection` و`occurrence_id`. قيمة `selection` هي `recommended` أو `first` أو `latest`. القيم حساسة لحالة الأحرف. في النسخ من 2 إلى 13، يستخدم المُحدِّد المحذوف `recommended`. وتعيد النسخة 1 أحدث حدوث محتفَظ به ولا تقبل أي مُحدِّد. لا تنطبق عوامل تصفية قائمة المشكلات على هذه القراءة.
لاستجابة `200 OK` المصطنعة هذه حدوث `TypeError` معالَج واحد مع تتبّع مرتبط. ليس فيها طلب ولا Breadcrumbs ولا سجلات مرتبطة ولا أدلة نشر، لذلك قيمة `evidence.status` هي `partial`.
```json theme={null}
{
"schema_version": 13,
"subject": {
"kind": "issue", "id": "11111111-1111-4111-8111-111111111111",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"fingerprint": "checkout-cart-total", "status": "unresolved", "severity": "error",
"title": "TypeError",
"message": "Cannot read properties of undefined (reading 'total')",
"occurrence_count": 1, "first_seen_at": "2026-08-03T11:05:00Z",
"last_seen_at": "2026-08-03T11:05:00Z"
},
"event": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": {
"schema_version": 1,
"resource": {
"service": null,
"deployment": null,
"runtime": {"name": "node", "version": "24.4.0"},
"framework": null,
"operating_system": {"name": "Linux", "version": "6.8", "build": null},
"device": {"family": null, "model": null, "architecture": "arm64"},
"application": null
},
"trace": {
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"parent_span_id": null, "sampled": true
},
"session": null,
"subject": null,
"tags": {}
},
"exception": {"type": "TypeError", "mechanism": {"type": "javascript.error", "handled": true}},
"exception_chain": {
"status": "captured",
"entries": [
{
"id": 0,
"parent_id": null,
"relationship": "reported",
"type": "TypeError",
"message": null,
"message_state": "redacted",
"module": null,
"mechanism": {"type": "javascript.error", "handled": true},
"stack_frames": [
{
"index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null, "source": "captured"
},
{
"index": 1, "module": null, "function": "handleCheckout",
"file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
"source": "captured"
}
],
"stack_frames_state": "captured"
}
],
"truncated": false
},
"stack_frames": [
{
"index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null, "source": "captured"
},
{
"index": 1, "module": null, "function": "handleCheckout",
"file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
"source": "captured"
}
],
"breadcrumbs": [],
"breadcrumbs_truncated": false
},
"occurrence_selection": {
"requested": "recommended",
"reason": "only_retained_occurrence",
"selected": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"first": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"latest": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"recommended": {
"id": "22222222-2222-4222-8222-222222222222",
"occurred_at": "2026-08-03T11:05:00Z",
"severity": "error",
"environment": "production",
"release": "checkout@1.2.3",
"service_name": "checkout-api",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"exception_type": "TypeError",
"trace_linked": true,
"stack": {"frame_count": 2, "truncated": false},
"breadcrumbs": {"count": 0, "truncated": false},
"context_captured": true
},
"recommendation": {
"algorithm_version": 1, "candidate_count": 1, "candidate_limit": 50,
"candidate_window_truncated": false
}
},
"lifecycle": {
"persisted_status": "unresolved",
"effective_status": "unresolved",
"activity": {"status": "available", "changes": [], "truncated": false},
"regression": {
"status": "not_detected", "reason": "no_resolution_recorded",
"resolution_changed_at": null, "first_reappeared_occurrence": null
}
},
"occurrence_analysis": {
"status": "complete",
"coverage": {
"retained_occurrences": 1, "trend_occurrences": 1, "available_distribution_count": 4,
"expected_distribution_count": 4, "max_buckets": 30, "max_values_per_dimension": 10
},
"trend": {
"scope_start": "2026-08-03T11:05:00Z",
"scope_end": "2026-08-03T11:05:00Z",
"interval_seconds": 60,
"buckets": [
{
"bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:06:00Z",
"occurrence_count": 1
}
]
},
"distributions": [
{
"dimension": "release",
"distinct_value_count": 1,
"values": [
{
"value": "checkout@1.2.3", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "environment",
"distinct_value_count": 1,
"values": [
{
"value": "production", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "service",
"distinct_value_count": 1,
"values": [
{
"value": "checkout-api", "version": null, "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
},
{
"dimension": "sdk",
"distinct_value_count": 1,
"values": [
{
"value": "@logbrew/node", "version": "0.1.11", "occurrence_count": 1,
"share_basis_points": 10000
}
],
"other_occurrence_count": 0
}
],
"limitations": []
},
"grouping": {"strategy": "sdk_fingerprint", "components": ["sdk_fingerprint"], "stack": null},
"cause": {
"status": "evidence_only",
"summary": null,
"provenance": null,
"signals": ["handled_exception", "error_trace_span"]
},
"fix": {
"status": "observed_frame",
"location": {
"component": null, "module": null, "function": "cartTotal", "file": "src/cart.ts",
"line": 42, "column": 17, "in_app": null
},
"provenance": "backend_observed"
},
"source_locator": {
"status": "not_found",
"repository_provider": null,
"repository_full_name": null,
"component_path": null,
"revision": null,
"revision_source": null,
"repository_relative_file": null,
"evidence": {
"status": "partial",
"captured_fields": ["source.service"],
"missing_fields": ["source.component"],
"redacted_fields": [],
"truncated_fields": []
}
},
"reproduction": {
"status": "insufficient_evidence",
"baseline_occurrence_id": "22222222-2222-4222-8222-222222222222",
"evidence": {
"status": "partial",
"captured_fields": [
"reproduction.baseline_occurrence", "reproduction.code_location",
"reproduction.expected_failure"
],
"missing_fields": ["reproduction.trigger"],
"redacted_fields": [],
"truncated_fields": []
}
},
"impact": {
"occurrence_count": 1,
"first_seen_at": "2026-08-03T11:05:00Z",
"last_seen_at": "2026-08-03T11:05:00Z",
"affected_users": null,
"user_impact": {
"status": "not_captured",
"known_affected_users": null,
"count_method": "unavailable",
"coverage": {
"retained_occurrences": 1, "indexed_occurrences": 1,
"historical_unindexed_occurrences": 0, "identified_user_occurrences": 0,
"anonymous_subject_occurrences": 0, "missing_subject_occurrences": 1,
"privacy_filtered_subject_occurrences": 0, "index_coverage_basis_points": 10000,
"identified_user_coverage_basis_points": 0
},
"limitations": ["missing_subject_context"]
},
"reported": null
},
"correlations": {
"trace": {
"status": "available",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"summary": {
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_count": 1,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:04:59.950Z",
"duration_ms": 180,
"root_span": {
"span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "error",
"started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
"service_name": "checkout-api"
},
"slowest_child_span": null,
"slowest_path": [],
"error_spans": [
{
"span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "error",
"started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api", "span_count": 1, "error_span_count": 1,
"max_duration_ms": 180
}
],
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"truncated": false
},
"logs": {"status": "not_found", "items": [], "truncated": false},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false},
"related_issues": {"status": "not_found", "items": [], "truncated": false},
"release": {
"release": "checkout@1.2.3", "environment": "production",
"service_name": "checkout-api", "deployment_status": "not_found"
}
},
"evidence": {
"status": "partial",
"captured_fields": [
"context", "deployment.lookup", "exception", "exception.mechanism", "exception_chain",
"exception_chain.stack_frames", "grouping", "grouping.components",
"grouping.strategy", "grouping.strategy_details", "lifecycle.regression",
"lifecycle.status_history", "likely_fix_area", "occurrence.boundaries",
"occurrence.distribution.environment", "occurrence.distribution.release",
"occurrence.distribution.sdk", "occurrence.distribution.service",
"occurrence.recommendation", "occurrence.selection", "occurrence.trend", "release",
"sdk", "source_locator", "stack_frames", "trace"
],
"missing_fields": [
"affected_users", "breadcrumbs", "deployment", "impact", "likely_root_cause",
"related_actions", "related_issues", "related_logs", "related_metrics", "request",
"source_locator.complete"
],
"redacted_fields": ["exception_chain.messages"],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_code_location", "target": "source_code",
"reason": "likely_fix_location_available"
},
{
"priority": 2, "code": "inspect_trace", "target": "trace_summary",
"reason": "linked_trace_available"
},
{
"priority": 3, "code": "compare_release", "target": "release_summary",
"reason": "release_identity_available"
},
{
"priority": 4, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete"
}
]
}
```
| الحقل | النسخة | المعنى |
| - | - | - |
| `subject` | 1 | المشكلة المجمّعة. تصف `first_seen_at` و`last_seen_at` و`occurrence_count` المجموعة. |
| `event` | 1 | الحدوث المختار: الـ SDK و`context` و`exception` و`stack_frames` و`breadcrumbs`. في النسخة 1، يكون `null` عندما لا يمكن قراءة أحدث حدوث. |
| `cause` | 1 | قيمة `status` هي `reported_hypothesis` أو `evidence_only` أو `unknown`. ويسرد `signals` الإشارات المرصودة. |
| `fix` | 1 | موضع في الشيفرة. قيمة `status` هي `reported_location` أو `observed_application_frame` أو `observed_frame` أو `observed_underlying_exception_frame` أو `unknown`. |
| `impact` | 1 | أعداد مرات الحدوث و`user_impact`. ويحمل `reported` التأثير الذي أبلغ عنه التطبيق، أو `null`. |
| `correlations` | 1 | `trace` و`logs` و`actions` و`metrics` و`release`. |
| `occurrence_selection` | 2 | المُحدِّد المطلوب، والسبب، وملخصات مرات الحدوث المختار والأول والأحدث والمقترح. |
| `lifecycle` | 3 | `persisted_status` و`effective_status` ونشاط الحالة و`regression`. قد تكون قيمة `effective_status` هي `regressed`. |
| `occurrence_analysis` | 4 | اتجاه مرات الحدوث، وتوزيعات الإصدار والبيئة والخدمة والـ SDK. |
| `event.exception_chain` | 5 | حتى 8 استثناءات مرتبطة. قيمة `relationship` هي `reported` أو `cause` أو `context` أو `aggregate_member` أو `suppressed`. |
| `event.request` | 6 | `method` و`route_template` و`response_status_code`. يغيب المفتاح عندما لم يُلتقط أي طلب. |
| `grouping` | 7 | `strategy` التجميع و`components` الخاصة بها، واستخدام إطارات المكدّس. |
| `correlations.release.deployment_status` | 8 | حالة البحث عن عملية النشر. تظهر `deployment` و`time_since_deployment_ms` و`deployment_causality` فقط عند العثور على عملية نشر. |
| `correlations.related_issues` | 9 | مشكلات أخرى في التتبّع نفسه. |
| `source_locator` | 10 | المستودع والمكوّن والمراجعة والملف بمساره النسبي في المستودع، عندما يستطيع LogBrew ربطها. |
| `reproduction` | 11 | قيمة `status` هي `ready` أو `partial` أو `insufficient_evidence`. |
| رمز `verify_correction` في `next_actions` | 12 | يظهر عندما تكون قيمة `reproduction.status` هي `ready`. |
| `impact.user_impact.count_method` | 13 | يبلّغ عن العدد التقريبي للقيم المختلفة بالقيمة `approximate_distinct`. تستخدم النسخ الأقدم اسم قيمة أقدم. و`unavailable` تعني أنه لا يوجد عدد. |
المفاتيح التي تضيفها نسخة لاحقة تغيب عن النسخة الأقدم. لا تقرأ المفتاح الغائب على أنه `null`.
يبلّغ `subject.status` وحالات `lifecycle` عن المشكلة المؤرشفة بالقيمة `ignored`. أما استجابات قائمة المشكلات وتفاصيلها فتستخدم `archived` في نسخة الاستجابة 2 وما بعدها.
حدود المشكلة: يقرأ الاقتراح 50 حدوثًا محتفَظًا به على الأكثر. وللاتجاه 30 فاصلًا زمنيًا على الأكثر. ويعيد كل توزيع 10 قيم على الأكثر. وللمكدّس 32 إطارًا على الأكثر.
#### أخطاء طلب التحقيق في المشكلة
استخدم `selection` أو `occurrence_id`. لا ترسلهما معًا، حتى عندما يختاران الحدوث نفسه:
```json theme={null}
{
"error": "selection and occurrence_id are mutually exclusive",
"code": "validation_failed",
"next": "use response_version=2 through 13 with at most one of selection=first|latest|recommended or an exact occurrence_id copied from GET /api/telemetry/issues/{issue_id}/events",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
| HTTP | `error` | السبب | طريقة التعافي |
| - | - | - | - |
| `422` | `selection and occurrence_id are mutually exclusive` | في الطلب المُحدِّدان كلاهما. | أبقِ مُحدِّدًا واحدًا. |
| `422` | `issue occurrence selection requires response_version=2 through 13` | في الطلب مُحدِّد مع النسخة 1، أو دون نسخة. | أرسل `response_version=13`. أبقِ المُحدِّد. |
| `422` | `issue investigation response_version must be 1 through 13` | النسخة خارج النطاق. | أرسل نسخة مدعومة. |
| `422` | `invalid query parameters` | مفتاح غير معروف، أو UUID غير صالح، أو نسخة ليست عددًا صحيحًا، أو قيمة `selection` غير معروفة. | صحّح [الاستعلام](/ar/reference/api-errors#invalid-query-parameters). |
| `404` | `issue occurrence not found` | الحدوث ليس في التاريخ المحتفَظ به لهذه المجموعة. | انسخ معرّف الحدوث من أحداث هذه المشكلة. لا تستخدم `latest` أو `recommended` بدلًا منه دون موافقة. |
| `404` | `issue not found` | لا يحتوي أي مشروع يمكن قراءته على هذه المشكلة. | تحقق من الحساب ومن UUID المشكلة. لا ترسل UUID الحدوث على أنه معرّف المشكلة. |
الحدوث المفقود لا يعني أن المشكلة مفقودة. والاستجابة `404` لا تبيّن هل يستطيع حساب آخر قراءة المشكلة.
### استجابة التحقيق في التتبّع
استخدم `GET /api/telemetry/traces/{trace_id}/investigation` لقراءة تتبّع واحد مع مسار الفشل وأبطأ مسار والإشارات المرتبطة. مفاتيح الاستعلام هي `response_version` و`project_id` و`release` و`environment`. وكلها اختيارية. اطلب النسخة 3:
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "response_version=3"
```
تضيف النسخة 2 الحقلين `cause` و`fix` إلى كل مشكلة مرتبطة. وتضيف النسخة 3 الحقل `span_id` إلى المشكلات والإجراءات والمقاييس المرتبطة عندما يكون قد التُقط.
في هذه الاستجابة المصطنعة Span خادم جذري وSpan عميل فاشل. والـ Span الفاشل هو أيضًا أبطأ Span فرعي. ليس للـ Spans سياق منظّم، لذلك `spans.context` مفقود.
```json theme={null}
{
"schema_version": 3,
"subject": {
"kind": "trace",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"analyzed_span_count": 2,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"analysis": {
"status": "errors_observed",
"causality": "evidence_only",
"root_span": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"first_error_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"first_error_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"bottleneck_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"bottleneck_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
]
},
"spans": {
"items": [
{
"id": "33333333-3333-4333-8333-333333333333",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"span_id": "b7ad6b7169203331",
"parent_span_id": null,
"name": "POST /checkout",
"operation": "http.server",
"status": "ok",
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"roles": ["root", "error_path", "bottleneck_path", "slow"]
},
{
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"span_id": "53995c3f42cd8ad8",
"parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-08-03T11:05:00.100Z",
"duration_ms": 900,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"roles": ["first_error", "error_path", "bottleneck", "bottleneck_path", "error", "slow"]
}
],
"truncated": false
},
"correlations": {
"window": {
"since": "2026-08-03T11:00:00Z",
"until": "2026-08-03T11:10:01.200Z",
"scopes": [
{
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"issues": {"status": "not_found", "items": [], "truncated": false},
"logs": {
"status": "available",
"items": [
{
"id": "55555555-5555-4555-8555-555555555555",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
"source": "payments", "message": "Charge request failed",
"occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false}
},
"timeline": {
"items": [
{
"id": "b7ad6b7169203331", "kind": "span", "occurred_at": "2026-08-03T11:05:00Z",
"name": "POST /checkout", "service_name": "checkout-api",
"span_id": "b7ad6b7169203331", "severity": null, "status": "ok",
"duration_ms": 1200
},
{
"id": "53995c3f42cd8ad8", "kind": "span", "occurred_at": "2026-08-03T11:05:00.100Z",
"name": "POST /v1/charges", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
"duration_ms": 900
},
{
"id": "55555555-5555-4555-8555-555555555555", "kind": "log",
"occurred_at": "2026-08-03T11:05:01Z", "name": "Charge request failed",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
"status": null, "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"correlations.window", "related_actions", "related_issues", "related_logs",
"related_metrics", "spans.sdk", "timeline", "trace.parentage", "trace.root",
"trace.spans"
],
"missing_fields": ["spans.context"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_first_error_span", "target": "trace_span",
"reason": "error_span_observed", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 2, "code": "review_related_logs", "target": "telemetry_logs",
"reason": "related_logs_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_summary",
"reason": "release_identity_available", "span_id": null, "issue_id": null
},
{
"priority": 4, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "span_id": null, "issue_id": null
}
]
}
```
| الحقل | المعنى |
| - | - |
| `subject` | مجاميع التتبّع من الـ Spans التي جرى تحليلها. |
| `analysis.status` | `errors_observed` أو `latency_focus` أو `no_error_observed`. |
| `analysis.first_error_path` | سلسلة الآباء المعروفة من الـ Span الجذري إلى أبكر Span خطأ. |
| `analysis.bottleneck_path` | سلسلة الآباء المعروفة إلى أبطأ Span فرعي. |
| `spans.items[].roles` | سبب وجود الـ Span في المعاينة: `root` أو `first_error` أو `error_path` أو `bottleneck` أو `bottleneck_path` أو `error` أو `slow`. |
| `correlations.window` | النطاق الزمني ونطاقات النشر المستخدمة للقراءات المرتبطة. |
| `correlations.issues`، `logs`، `actions`، `metrics` | الإشارات التي لها معرّف التتبّع نفسه في النطاق الزمني. |
يكون `trace.parentage` مفقودًا عندما يسمّي Span أبًا لم يحتفظ به LogBrew. في معاينة الـ Spans 64 Span على الأكثر. وفي كل مسار تحليل 64 Span على الأكثر. وتستخدم القراءات المرتبطة 8 نطاقات نشر على الأكثر.
الإجراء التالي الذي هدفه `trace_span` يسمّي `span_id` من هذه الحزمة. لقراءة هذا الـ Span، أرسل طلبًا إلى مسار الـ Span مع `project_id` و`environment` و`release` الخاصة بالـ Span.
### استجابة التحقيق في Span
استخدم `GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation` لقراءة عملية واحدة في تتبّع. أرسل `project_id` و`environment` و`release`. الثلاثة كلها مطلوبة. انسخها من الـ Span المختار. لا ترسل قيمة `id` لصف الـ Span على أنها `span_id`.
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/spans/$SPAN_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "project_id=$PROJECT_ID" \
--data-urlencode "environment=production" \
--data-urlencode "release=checkout@1.2.3"
```
تصف هذه الاستجابة المصطنعة Span العميل الفاشل من مثال التتبّع. لسجل خطأ معرّف الـ Span نفسه. استغرق الـ Span وقتًا أطول من المئين 95 التقريبي لنظرائه المحتفَظ بهم.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "span",
"id": "44444444-4444-4444-8444-444444444444",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"span_id": "53995c3f42cd8ad8",
"parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges",
"operation": "http.client",
"status": "error",
"started_at": "2026-08-03T11:05:00.100Z",
"duration_ms": 900,
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"content_trust": "untrusted_telemetry"
},
"context": null,
"payload": {
"metadata": {
"values": {"provider": "example-pay"},
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"events": [],
"links": [],
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "error_evidence",
"causality": "evidence_only",
"observations": ["subject_error", "exact_span_error_log", "subject_at_or_above_peer_p95"]
},
"topology": {
"status": "available",
"root": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"parent": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"ancestors": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
}
],
"children": [],
"descendant_count": 0,
"cross_service_edges": [],
"parent_chain_status": "complete",
"truncated": false
},
"baseline": {
"status": "available",
"since": "2026-08-02T11:05:00.100Z",
"until": "2026-08-03T11:05:00.100Z",
"dimensions": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
"release": "checkout@1.2.3", "service_name": "checkout-api",
"operation": "http.client", "name": "POST /v1/charges"
},
"retained_peer_count": 40,
"error_peer_count": 2,
"error_rate_basis_points": 500,
"p50_duration_ms": 310.0,
"p95_duration_ms": 620.0,
"p99_duration_ms": 940.0,
"subject_percentile_basis_points": 9500,
"method": "approximate_t_digest",
"limitations": [
"retained_telemetry_only", "sampling_may_apply", "approximate_percentiles",
"same_release_only"
]
},
"correlations": {
"trace": {
"status": "available",
"summary": {
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"span_count": 2,
"error_span_count": 1,
"service_count": 1,
"project_count": 1,
"started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200,
"root_span": {
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
"duration_ms": 1200, "service_name": "checkout-api"
},
"slowest_child_span": {
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
},
"slowest_path": [
{
"span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
"operation": "http.server", "status": "ok",
"started_at": "2026-08-03T11:05:00Z", "duration_ms": 1200,
"service_name": "checkout-api"
},
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"error_spans": [
{
"span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
"name": "POST /v1/charges", "operation": "http.client", "status": "error",
"started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
"service_name": "checkout-api"
}
],
"services": [
{
"service_name": "checkout-api", "span_count": 2, "error_span_count": 1,
"max_duration_ms": 1200
}
],
"releases": ["checkout@1.2.3"],
"environments": ["production"]
},
"truncated": false
},
"issues": {"status": "not_found", "items": [], "truncated": false},
"logs": {
"status": "available",
"items": [
{
"id": "55555555-5555-4555-8555-555555555555",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
"source": "payments", "message": "Charge request failed",
"occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "environment": "production",
"release": "checkout@1.2.3"
}
],
"truncated": false
},
"actions": {"status": "not_found", "items": [], "truncated": false},
"metrics": {"status": "not_found", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "53995c3f42cd8ad8:start", "kind": "span_start",
"occurred_at": "2026-08-03T11:05:00.100Z", "offset_ms": 0,
"name": "POST /v1/charges", "service_name": "checkout-api",
"span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
"duration_ms": 900
},
{
"id": "55555555-5555-4555-8555-555555555555", "kind": "log",
"occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "payments",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
"status": null, "duration_ms": null
},
{
"id": "53995c3f42cd8ad8:end", "kind": "span_end",
"occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "POST /v1/charges",
"service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": null,
"status": "error", "duration_ms": 900
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"attributes.metadata.provider", "baseline", "correlations.actions",
"correlations.issues", "correlations.logs", "correlations.metrics",
"correlations.trace", "subject.content_trust", "subject.deployment",
"subject.identity", "subject.sdk", "subject.timing", "topology"
],
"missing_fields": ["context"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_parent_span", "target": "span_investigation",
"reason": "parent_context_available", "span_id": "b7ad6b7169203331", "issue_id": null
},
{
"priority": 2, "code": "review_exact_span_logs", "target": "telemetry_logs",
"reason": "exact_span_logs_available", "span_id": "53995c3f42cd8ad8",
"issue_id": null
},
{
"priority": 3, "code": "inspect_trace", "target": "trace_investigation",
"reason": "trace_context_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 4, "code": "compare_peer_baseline", "target": "peer_baseline",
"reason": "subject_latency_elevated", "span_id": "53995c3f42cd8ad8", "issue_id": null
},
{
"priority": 5, "code": "compare_release", "target": "release_investigation",
"reason": "exact_release_available", "span_id": null, "issue_id": null
},
{
"priority": 6, "code": "improve_capture", "target": "sdk_capture",
"reason": "capture_incomplete", "span_id": "53995c3f42cd8ad8", "issue_id": null
}
]
}
```
| الحقل | المعنى |
| - | - |
| `payload` | `metadata` الخاصة بالـ Span، وحتى 8 عناصر في `events`، وحتى 8 عناصر في `links`. وتتشارك ميزانية واحدة من 64 قيمة. |
| `analysis.observations` | `subject_error` أو `child_error` أو `exact_span_error_log` أو `related_issue` أو `subject_at_or_above_peer_p95` أو `subject_at_or_above_peer_p99`. |
| `topology` | `root` و`parent` و`ancestors` و`children` المباشرة و`descendant_count` و`cross_service_edges`. |
| `topology.parent_chain_status` | `root` أو `complete` أو `missing` أو `cycle` أو `truncated` أو `unavailable`. |
| `baseline` | الـ Spans الأقدم التي لها المشروع والبيئة والإصدار والخدمة والعملية والاسم نفسها. |
| `correlations.logs` | السجلات التي لها معرّف التتبّع ومعرّف الـ Span نفسيهما. |
| `correlations.issues`، `actions`، `metrics` | الإشارات التي لها معرّف التتبّع نفسه في المشروع والبيئة والإصدار نفسها. |
| `timeline[].offset_ms` | الملّي ثواني من بداية الـ Span. القيمة السالبة أبكر من الـ Span. |
يقرأ خط الأساس الساعات الأربع والعشرين التي تسبق بداية الـ Span. يشمل النطاق `since` ولا يشمل `until`. و`error_rate_basis_points: 500` تعني 5%. و`subject_percentile_basis_points: 9500` تعني أن 95% من النظراء المحتفَظ بهم لم يستغرقوا وقتًا أطول من هذا الـ Span. المئينات تقريبية. أبقِ `baseline.limitations` مع القيم. خط الأساس `not_found` ليس له نظراء محتفَظ بهم. وخط الأساس `unavailable` قراءة فاشلة، لا عدد صفري.
`parent_chain_status: "complete"` تعني أن السلسلة المحتفَظ بها تصل إلى Span جذري. ولا تثبت أن LogBrew احتفظ بكل Span في الطلب. تعيد `topology` 64 سلفًا على الأكثر، و50 Span فرعيًا مباشرًا، و50 حافة بين الخدمات.
| HTTP | `error` | طريقة التعافي |
| - | - | - |
| `422` | `trace_id must be a non-zero 32-character hexadecimal value` | انسخ `trace_id` من استجابة تتبّع في LogBrew. |
| `422` | `span_id must be a non-zero 16-character hexadecimal value` | انسخ `span_id` من استجابة تتبّع في LogBrew. |
| `422` | `environment and release must be non-empty exact span scope values` | انسخ النطاق من الـ Span المختار. |
| `422` | `invalid query parameters` | أرسل `project_id` و`environment` و`release`، ولا مفتاح غيرها. |
| `404` | `span not found` | تحقق من المعرّفات والمشروع والبيئة والإصدار. |
### استجابة التحقيق في السجل
استخدم `GET /api/logs/{log_id}/investigation` لقراءة سجل واحد وأدلته المرتبطة. ليس لهذا المسار مفاتيح استعلام. انسخ معرّف السجل من قائمة سجلات.
```bash theme={null}
curl --fail-with-body -sS \
"https://api.logbrew.co/api/logs/$LOG_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN"
```
قد تعيد القراءة أدلة خارج عوامل تصفية قائمة السجلات. تستخدم القراءات المرتبطة مشروع السجل وبيئته وإصداره، و5 دقائق قبل السجل وبعده. وتستخدم السجلات القريبة أيضًا الخدمة نفسها. ولا تحتاج إلى معرّف تتبّع. أما قراءات التتبّع المطابق تمامًا فتحتاج إلى معرّف تتبّع السجل، وقد تتضمن خدمات أخرى. ويستخدم ملخص التتبّع معرّف التتبّع والنطاق نفسيهما، دون النطاق الزمني.
في هذه الاستجابة المصطنعة سجل تحذير دون سياق تتبّع، وسجل قريب واحد. لا تبني الاستجابة رابط تتبّع من الطوابع الزمنية.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "log",
"id": "66666666-6666-4666-8666-666666666666",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"severity": "warning",
"content_trust": "untrusted_telemetry",
"source": "inventory",
"message": "Inventory update delayed",
"occurred_at": "2026-08-03T12:00:00Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"}
},
"context": null,
"attributes": {
"values": {"retry_count": 2},
"included_leaf_count": 1,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "warning_evidence",
"causality": "evidence_only",
"observations": ["subject_warning"]
},
"correlations": {
"trace": {
"status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
"summary": null, "truncated": false
},
"issues": {"status": "not_linked", "items": [], "truncated": false},
"trace_logs": {"status": "not_linked", "items": [], "truncated": false},
"nearby_logs": {
"status": "available",
"items": [
{
"id": "77777777-7777-4777-8777-777777777777",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "info",
"source": "inventory", "message": "Inventory retry started",
"occurred_at": "2026-08-03T11:59:58Z", "service_name": "checkout-api",
"trace_id": null, "span_id": null, "environment": "production",
"release": "checkout@1.2.3", "relationship": "nearby_scope"
}
],
"truncated": false
},
"actions": {"status": "not_linked", "items": [], "truncated": false},
"metrics": {"status": "not_linked", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "77777777-7777-4777-8777-777777777777", "kind": "log",
"relationship": "nearby_scope", "occurred_at": "2026-08-03T11:59:58Z",
"name": "inventory", "message": "Inventory retry started",
"service_name": "checkout-api", "span_id": null, "severity": "info", "status": null,
"duration_ms": null
},
{
"id": "66666666-6666-4666-8666-666666666666", "kind": "log",
"relationship": "subject", "occurred_at": "2026-08-03T12:00:00Z",
"name": "inventory", "message": "Inventory update delayed",
"service_name": "checkout-api", "span_id": null, "severity": "warning",
"status": null, "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"attributes", "attributes.retry_count", "correlations.nearby_logs",
"correlations.release", "subject.content_trust", "subject.environment", "subject.id",
"subject.message", "subject.occurred_at", "subject.project_id", "subject.release",
"subject.sdk.name", "subject.sdk.version", "subject.service_name", "subject.severity",
"subject.source", "timeline"
],
"missing_fields": ["context", "correlations.trace.trace_id"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "review_nearby_logs", "target": "telemetry_logs",
"reason": "nearby_logs_available", "issue_id": null, "trace_id": null,
"span_id": null
},
{
"priority": 2, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_investigation",
"reason": "release_identity_available", "issue_id": null, "trace_id": null,
"span_id": null
}
]
}
```
| الحقل | المعنى |
| - | - |
| `attributes` | السمات المنظّمة المحدودة. تستبعد `values` الحقل `context`، الموجود في الحقل `context` في المستوى الأعلى. |
| `analysis.status` | `critical_evidence` أو `error_evidence` أو `warning_evidence` أو `no_failure_observed`. |
| `correlations.trace` | معرّف التتبّع ومعرّف الـ Span و`exact_span` و`summary` التتبّع. |
| `correlations.trace_logs` | السجلات التي لها معرّف التتبّع نفسه. قيمة `relationship` هي `exact_trace`. |
| `correlations.nearby_logs` | سجلات الخدمة نفسها في النطاق الزمني. قيمة `relationship` هي `nearby_scope`. تستبعد السجل قيد التحقيق وسجلات التتبّع المطابق تمامًا. |
| `correlations.issues`، `actions`، `metrics` | الإشارات التي لها معرّف التتبّع نفسه. |
| `correlations.release` | نطاق الإصدار للتحقيق في الإصدار. ولا يحمل مقارنة. |
| `timeline[].relationship` | `subject` أو `exact_span` أو `exact_trace` أو `nearby_scope`. |
قد يكون معرّف التتبّع موجودًا عندما تكون حالة التتبّع `not_found` أو `unavailable`. وملخص التتبّع المتاح لا يضمن وجود `exact_span`.
### استجابة التحقيق في الإجراء
استخدم `GET /api/telemetry/actions/{action_id}/investigation` لقراءة إجراء منتج واحد وحالته المبلَّغ عنها وأدلته المرتبطة. ليس لهذا المسار مفاتيح استعلام. تستخدم القراءات المرتبطة النطاق الزمني والنطاقات نفسها التي يستخدمها التحقيق في السجل.
```bash theme={null}
curl --fail-with-body -sS \
"https://api.logbrew.co/api/telemetry/actions/$ACTION_ID/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN"
```
تستخدم `correlations` و`timeline` و`next_actions` أشكال التحقيق في السجل. وتستبعد الإجراءات المرتبطة الإجراء قيد التحقيق.
تصف هذه الاستجابة المصطنعة إجراء إتمام شراء فاشلًا من مستخدم مسجَّل الدخول. ليس للإجراء معرّف تتبّع.
```json theme={null}
{
"schema_version": 1,
"subject": {
"kind": "action",
"id": "14141414-1414-4141-8141-141414141414",
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "checkout.submit",
"status": "failure",
"content_trust": "untrusted_telemetry",
"occurred_at": "2026-08-03T11:05:00Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"subject_classification": "user",
"session_captured": true
},
"context": null,
"properties": {
"values": {"plan": "team", "step": "payment"},
"included_leaf_count": 2,
"redacted": false,
"truncated": false
},
"analysis": {
"status": "subject_failure",
"causality": "evidence_only",
"observations": ["subject_failure"]
},
"correlations": {
"trace": {
"status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
"summary": null, "truncated": false
},
"issues": {"status": "not_linked", "items": [], "truncated": false},
"trace_logs": {"status": "not_linked", "items": [], "truncated": false},
"nearby_logs": {"status": "not_found", "items": [], "truncated": false},
"actions": {"status": "not_linked", "items": [], "truncated": false},
"metrics": {"status": "not_linked", "items": [], "truncated": false},
"release": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api"
}
},
"timeline": {
"items": [
{
"id": "14141414-1414-4141-8141-141414141414", "kind": "action",
"relationship": "subject", "occurred_at": "2026-08-03T11:05:00Z",
"name": "checkout.submit", "message": null, "service_name": "checkout-api",
"span_id": null, "severity": null, "status": "failure", "duration_ms": null
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"correlations.nearby_logs", "correlations.release", "properties.metadata",
"properties.metadata.plan", "properties.metadata.step", "subject.content_trust",
"subject.environment", "subject.id", "subject.name", "subject.occurred_at",
"subject.project_id", "subject.release", "subject.sdk.name", "subject.sdk.version",
"subject.service_name", "subject.session_captured", "subject.status",
"subject.subject_classification", "timeline"
],
"missing_fields": ["context", "correlations.trace.trace_id"],
"redacted_fields": ["subject.distinct_id", "subject.session_id"],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1, "code": "inspect_analytics_paths", "target": "analytics_paths",
"reason": "session_captured", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 2, "code": "improve_capture", "target": "sdk_configuration",
"reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
},
{
"priority": 3, "code": "compare_release", "target": "release_investigation",
"reason": "release_identity_available", "issue_id": null, "trace_id": null,
"span_id": null
}
]
}
```
| الحقل | المعنى |
| - | - |
| `subject.status` | `queued` أو `running` أو `success` أو `failure`، أو `null` عندما لم تُلتقط حالة مدعومة. |
| `subject.subject_classification` | `user` أو `anonymous` أو `legacy_unknown` أو `missing` أو `historical_unindexed` أو `unsupported`. |
| `subject.session_captured` | هل كانت للإجراء جلسة. لا تعيد الاستجابة معرّف الجلسة أبدًا. |
| `properties` | الكائن `metadata` المحدود للإجراء. |
| `analysis.status` | `subject_failure` أو `correlated_failure_evidence` أو `in_progress` أو `success_observed` أو `status_not_captured`. |
لا تعيد الاستجابة معرّفات الكيانات أو الجلسات أبدًا. يسرد إيصال الأدلة دائمًا `subject.distinct_id` على أنه محجوب، و`subject.session_id` عندما تكون الجلسة قد التُقطت. لهذا السبب، كل حزمة إجراء `partial` وتتضمن `improve_capture`. لا تُزِل ضوابط الخصوصية لتلبية ذلك.
### استجابة التحقيق في المقياس
استخدم `GET /api/telemetry/metrics/investigation` لقراءة اسم مقياس واحد في مشروع واحد ونطاق زمني واحد. تحتوي الاستجابة على السلسلة الحالية، ومقارنة مع النطاق السابق المساوي له في الطول، وأحدث عيّنة، والعيّنات النموذجية للتتبّع، وعمليات النشر المكتملة. تضيف النسخة 2 وصف المقياس من أحدث عيّنة محتفَظ بها. وتبلّغ النسخة 1 دائمًا عن `description_status: "not_captured"`.
```bash theme={null}
curl --fail-with-body -sS -G \
"https://api.logbrew.co/api/telemetry/metrics/investigation" \
-H "Authorization: Bearer $LOGBREW_TOKEN" \
--data-urlencode "project_id=$PROJECT_ID" \
--data-urlencode "name=http.server.duration" \
--data-urlencode "since=2026-08-02T12:00:00Z" \
--data-urlencode "until=2026-08-03T12:00:00Z" \
--data-urlencode "interval=5m" \
--data-urlencode "group_by=service_name" \
--data-urlencode "environment=production" \
--data-urlencode "series_limit=12" \
--data-urlencode "response_version=2"
```
`project_id` و`name` و`since` مطلوبة. يشمل النطاق `since` ولا يشمل `until`. والقيمة الافتراضية لـ `until` هي الآن. وتقرأ المقارنة أيضًا النطاق السابق المساوي في الطول.
في هذا المدرّج التكراري المصطنع 5 عيّنات في فاصلين زمنيين مدة كل منهما 5 دقائق. قيمة p95 في الفاصل الأحدث 48 ms. وقيمة p95 في أحدث فاصل من النطاق السابق 24 ms.
```json theme={null}
{
"schema_version": 2,
"subject": {
"kind": "metric", "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "http.server.duration", "description_status": "captured",
"description": "Duration of one completed server request."
},
"query": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "name": "http.server.duration",
"since": "2026-08-02T12:00:00Z", "until": "2026-08-03T12:00:00Z", "interval": "5m",
"interval_seconds": 300, "group_by": "service_name", "environment": "production",
"series_limit": 12
},
"purpose": "Explains one metric's latest application-supplied description and bounded change, compares the immediately preceding equal window, exposes one privacy-bounded latest-sample capture context, exact trace/span exemplars, and nearby completed deployments, and keeps every correlation evidence-only rather than claiming an anomaly or root cause.",
"content_trust": "untrusted_telemetry",
"analysis": {
"status": "change_observed",
"causality": "evidence_only",
"focus": {
"comparison_index": 0, "selection": "largest_absolute_relative_change",
"direction": "increased", "absolute_change": 24.0, "relative_change_percent": 100.0
}
},
"coverage": {
"samples": 5, "series": 1, "returned_series": 1, "points": 2,
"expected_buckets_per_series": 288, "first_seen_at": "2026-08-03T11:00:10Z",
"last_seen_at": "2026-08-03T11:09:50Z", "truncated": false
},
"series": [
{
"identity": {
"kind": "histogram", "unit": "ms", "temporality": "delta",
"group_by": "service_name", "group_value": "checkout-api"
},
"status": "ready",
"aggregation": {
"code": "distribution_p95",
"description": "Primary value is the approximate p95 of raw observations in each bucket; p50, p99, range, average, count, and sum preserve distribution context."
},
"sample_count": 5,
"points": [
{
"bucket_start": "2026-08-03T11:00:00Z", "bucket_end": "2026-08-03T11:05:00Z",
"sample_count": 2, "value": 42.0, "min": 42.0, "max": 42.0, "average": 42.0,
"sum": 84.0, "p50": 42.0, "p95": 42.0, "p99": 42.0, "trace_exemplars": []
},
{
"bucket_start": "2026-08-03T11:05:00Z",
"bucket_end": "2026-08-03T11:10:00Z",
"sample_count": 3,
"value": 48.0,
"min": 48.0,
"max": 48.0,
"average": 48.0,
"sum": 144.0,
"p50": 48.0,
"p95": 48.0,
"p99": 48.0,
"trace_exemplars": ["4bf92f3577b34da6a3ce929d0e0e4736"]
}
]
}
],
"comparison": {
"status": "available",
"method": "adjacent_equal_window_latest_bucket",
"previous_since": "2026-08-01T12:00:00Z",
"previous_until": "2026-08-02T12:00:00Z",
"items": [
{
"identity": {
"kind": "histogram", "unit": "ms", "temporality": "delta",
"group_by": "service_name", "group_value": "checkout-api"
},
"aggregation": "distribution_p95",
"current": {
"bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:10:00Z",
"sample_count": 3, "value": 48.0
},
"previous": {
"bucket_start": "2026-08-02T11:55:00Z", "bucket_end": "2026-08-02T12:00:00Z",
"sample_count": 2, "value": 24.0
},
"direction": "increased",
"absolute_change": 24.0,
"relative_change_percent": 100.0
}
],
"truncated": false,
"limitation": "Each item compares the latest non-empty semantic bucket in adjacent equal-length windows. It is an observed value change, not seasonality-aware anomaly detection or evidence that a deployment caused the change."
},
"latest_sample": {
"status": "available",
"sample": {
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"kind": "histogram",
"value": 48.0,
"unit": "ms",
"temporality": "delta",
"occurred_at": "2026-08-03T11:09:50Z",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"},
"context": null,
"metadata": {"values": {}, "included_leaf_count": 0, "redacted": false, "truncated": false}
}
},
"exemplars": {
"status": "available",
"coverage": {
"matching_samples": 5, "trace_linked_samples": 1, "span_linked_samples": 1,
"returned_exemplars": 1
},
"items": [
{
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"value": 48.0,
"occurred_at": "2026-08-03T11:09:50Z",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"service_name": "checkout-api",
"environment": "production",
"release": "checkout@1.2.3",
"sdk": {"name": "@logbrew/node", "version": "0.1.11"}
}
],
"truncated": false
},
"deployments": {
"status": "available",
"items": [
{
"deployment_id": "deploy-123", "release": "checkout@1.2.3",
"environment": "production", "service_name": "checkout-api", "status": "succeeded",
"started_at": "2026-08-03T11:02:00Z", "finished_at": "2026-08-03T11:03:00Z",
"commit_sha": "0123456789abcdef"
}
],
"truncated": false
},
"timeline": {
"items": [
{
"id": "deploy-123", "kind": "deployment_finished",
"occurred_at": "2026-08-03T11:03:00Z", "value": null, "trace_id": null,
"span_id": null, "release": "checkout@1.2.3", "service_name": "checkout-api"
},
{
"id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "kind": "metric_exemplar",
"occurred_at": "2026-08-03T11:09:50Z", "value": 48.0,
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"release": "checkout@1.2.3", "service_name": "checkout-api"
}
],
"truncated": false
},
"evidence": {
"status": "partial",
"captured_fields": [
"metric.current_window_coverage", "metric.deployment_overlays", "metric.description",
"metric.identity", "metric.latest_sample", "metric.latest_sample.kind",
"metric.latest_sample.occurred_at", "metric.latest_sample.scope",
"metric.latest_sample.sdk.name", "metric.latest_sample.sdk.version",
"metric.latest_sample.span_id", "metric.latest_sample.trace_id",
"metric.latest_sample.value", "metric.prior_window_comparison", "metric.query_scope",
"metric.series_semantics", "metric.span_exemplars", "metric.trace_exemplars"
],
"missing_fields": ["metric.latest_sample.context", "metric.latest_sample.metadata"],
"redacted_fields": [],
"truncated_fields": []
},
"next_actions": [
{
"priority": 1,
"code": "inspect_exact_span",
"target": "span_investigation",
"reason": "Inspect the exact span that emitted a retained metric exemplar, then review its failure, latency, log, issue, action, and trace evidence.",
"context": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
"environment": "production", "release": "checkout@1.2.3",
"service_name": "checkout-api"
}
},
{
"priority": 2,
"code": "review_deployment",
"target": "release_investigation",
"reason": "Review release-scoped telemetry for a completed deployment inside the compared evidence window without treating temporal proximity as causality.",
"context": {
"project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "trace_id": null,
"span_id": null, "environment": "production", "release": "checkout@1.2.3",
"service_name": "checkout-api"
}
}
]
}
```
| الحقل | المعنى |
| - | - |
| `subject.description_status` | `captured` أو `not_captured` أو `unavailable`. |
| `query` | الاستعلام بعد التطبيع. تظهر `service_name` و`release` و`environment` فقط عند إرسالها. |
| `analysis.status` | `no_samples` أو `change_observed` أو `no_change_observed` أو `baseline_not_found` أو `comparison_unavailable`. |
| `analysis.focus` | عنصر المقارنة صاحب أكبر تغير نسبي، أو أكبر تغير مطلق عندما لا يوجد تغير نسبي. ويكون `null` عندما لا يوجد عنصر قابل للمقارنة. |
| `series[].aggregation.code` | `gauge_last` أو `delta_sum` أو `distribution_p95` أو `raw_cumulative_last` أو `raw_last`. |
| `comparison.status` | `available` أو `partial` أو `not_found` أو `unavailable` أو `no_current_samples`. |
| `comparison.items[]` | أحدث فاصل زمني غير فارغ في كل نطاق لهوية السلسلة نفسها. |
| `latest_sample` | أحدث عيّنة خام، مع الـ SDK و`context` و`metadata` ورابط التتبّع. |
| `exemplars` | العيّنات الخام التي لها معرّف تتبّع. ويعدّ `coverage` العيّنات المرتبطة. |
| `deployments` | عمليات النشر المكتملة من بداية النطاق السابق حتى `until`. |
| `next_actions[]` | `code` و`target` و`reason` بنص عادي، ونطاق `context` للقراءة التالية. |
`relative_change_percent` يساوي `(current - previous) / abs(previous) * 100`. ويكون `null` عندما تكون القيمة السابقة صفرًا أو مفقودة. يعدّ `expected_buckets_per_series` الفواصل الزمنية الممكنة، لا الفواصل التي فيها بيانات. لا ترسم الفواصل الفارغة أصفارًا. عملية النشر القريبة من تغير لا تثبت أنها سببت التغير.
المشروع الذي لا يستطيع الحساب قراءته يعيد `200 OK` مع `analysis.status: "no_samples"`، لا `404`. النتيجة الفارغة لا تصف أنواع الإشارات الأخرى.
حدود المقياس: النطاق 31 يومًا على الأكثر. ولكل سلسلة 500 فاصل زمني على الأكثر. وقيمة `series_limit` من 1 إلى 20، والافتراضية 10. تعيد الاستجابة 20 عيّنة نموذجية و20 عملية نشر على الأكثر.
| HTTP | `error` | طريقة التعافي |
| - | - | - |
| `422` | `metric investigation response_version must be 1 or 2` | احذف `response_version` أو أرسل `2`. |
| `422` | `metric series project_id is required` | أرسل معرّف مشروع واحد يمكن قراءته. |
| `422` | `metric series name is required` | انسخ الاسم من قائمة المقاييس. |
| `422` | `metric series since is required` | أرسل قيمة مثل `24h` أو طابعًا زمنيًا بتنسيق RFC 3339. |
| `422` | `metric series range must not exceed 31 days` | استخدم نطاقًا أقصر. |
| `422` | `metric series interval would exceed 500 buckets` | استخدم `interval=auto` أو فاصلًا زمنيًا أوسع. |
| `422` | `metric series_limit must be between 1 and 20` | أرسل قيمة من 1 إلى 20. |
قيمة `interval` هي `auto` أو `1m` أو `5m` أو `15m` أو `1h` أو `6h` أو `1d`. وقيمة `group_by` هي `none` أو `service_name` أو `release` أو `environment`. والقيم الأخرى تعيد `422`.
### أخطاء التحقيق
| HTTP | المسار | `error` |
| - | - | - |
| `404` | السجل | `log not found` |
| `404` | الإجراء | `action not found` |
| `404` | التتبّع | `trace not found` |
| `422` | التتبّع | `trace investigation response_version must be 1, 2, or 3` |
| `400` | السجل، الإجراء، المشكلة | `invalid URL path parameters` عندما لا يكون معرّف المسار UUID |
| `422` | المشكلة، التتبّع، الـ Span، المقياس | `invalid query parameters` لمفتاح غير معروف أو قيمة من نوع خاطئ |
الاستجابة `404` تعني أنه لا يوجد مشروع يمكن قراءته يحتوي على القيد. ويعيد كل مسار أيضًا `401` دون مصادقة صالحة، و`405` لطريقة غير `GET`. راجع [أخطاء API](/ar/reference/api-errors) لاستجابات [عدم العثور](/ar/reference/api-errors#resource-not-found) و[المسار](/ar/reference/api-errors#invalid-path-value) و[المصادقة](/ar/reference/api-errors#authentication-failure) و[الطريقة](/ar/reference/api-errors#unsupported-method).
قد تفشل قراءة أدلة اختيارية داخل استجابة `200 OK`. عندها تبلّغ المجموعة عن `unavailable`. لا تعرضها على أنها `not_found` أو صفر قيود.
## قيم الخطورة
قيم الخطورة التي يراها المستخدم هي `info` و`warning` و`error` و`critical`. يمكن لحزم SDK وبيئات التشغيل أن ترسل أسماء بديلة شائعة مثل `trace` أو `debug` أو `warn` أو `fatal`. تعيد استجابات REST والاستجابات المباشرة دائمًا القيمة المعيارية. مثلًا، يقبل LogBrew القيمة `warn` مُدخلًا ويعيد `warning`. ويرفض الاستيعاب قيم الخطورة غير المعروفة.
| الاسم البديل | القيمة المعيارية |
| - | - |
| `trace`، `debug` | `info` |
| `warn` | `warning` |
| `fatal` | `critical` |
## استجابات قواعد الخطورة
تغيّر قاعدة الخطورة طريقة عرض LogBrew لسجل أو مشكلة. ولا تغيّر الخطورة التي التقطها التطبيق. تعيد السجلات والمشكلات كائن `triage`:
| الحقل | المعنى |
| - | - |
| `effective_severity` | الخطورة التي تُعرض. دون قاعدة، تساوي `severity`. |
| `ignored` | `true` عندما تتجاهل قاعدة سجل هذا السجل، أو عندما تكون المشكلة مؤرشفة. |
| `rule_applied` | `true` عندما تنطبق قاعدة خطورة أو حالة التجاهل. و`false` هي القيمة الافتراضية، لا بيانات مفقودة. |
استخدم `triage.effective_severity` للعرض. أبقِ `severity` على أنها القيمة الملتقَطة. تحذف قائمة السجلات افتراضيًا السجلات المتجاهَلة. أرسل `status=ignored` أو `status=all` في `GET /api/logs` لتضمينها.
يجب أن يملك الحساب صلاحية إدارة المشكلات في المشروع. صلاحية القراءة لا تكفي. دون هذه الصلاحية، يعيد تغيير القاعدة `403` مع `code: forbidden`.
### غيّر قاعدة سجل
يضبط `PUT /api/logs/{log_id}/triage-rule` القاعدة للسجل وللسجلات اللاحقة التي لها البصمة نفسها. يحتاج النص إلى `severity` و`ignored` كليهما:
```bash theme={null}
curl --request PUT "https://api.logbrew.co/api/logs/$LOG_ID/triage-rule" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--header "Content-Type: application/json" \
--data '{ "severity": "info", "ignored": true }'
```
تحتوي الاستجابة `200 OK` على [السجل](#log-response) كاملًا. تبقى قيمة `severity` فيه `warning`. ويعرض `triage` القاعدة:
```json theme={null}
{
"severity": "warning",
"triage": {
"effective_severity": "info",
"ignored": true,
"rule_applied": true
}
}
```
يعرض هذا المقتطف الحقول التي تغيّرت فقط. قيمة `severity` في الطلب هي `source` أو `info` أو `warning` أو `error` أو `critical`. تعيد `source` الخطورة الملتقَطة. ولا تجعل السجل المتجاهَل نشطًا. لعرض السجل مرة أخرى، أرسل `"ignored": false`.
### غيّر قاعدة مشكلة
يضبط `PUT /api/telemetry/issues/{issue_id}/triage-rule` الخطورة المعروضة لمشكلة مجمّعة ولمرات حدوثها اللاحقة. يقبل النص `severity` فقط:
```bash theme={null}
curl --request PUT "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/triage-rule" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--header "Content-Type: application/json" \
--data '{ "severity": "warning" }'
```
تحتوي الاستجابة `200 OK` على [المشكلة](#issue-response) كاملة بالنسخة 1. ولا تتغير `severity` و`status` الملتقَطتان:
```json theme={null}
{
"severity": "error",
"status": "unresolved",
"triage": {
"effective_severity": "warning",
"ignored": false,
"rule_applied": true
}
}
```
يعرض هذا المقتطف بعض الحقول فقط. لا تحلّ القاعدة المشكلة ولا تؤرشفها ولا تعيد فتحها. استخدم [تغيير الحالة](#issue-status-response-examples) لذلك. تتبع الأولوية المشتقة الخطورة الفعلية الجديدة. اقرأ المشكلة مع `response_version=2` أو `3` لتراها.
الخطورة غير المدعومة تعيد `422`:
```json theme={null}
{
"error": "triage severity must be source, info, warning, error, or critical",
"code": "validation_failed",
"next": "use source to restore captured severity, or choose info, warning, error, or critical",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
حقل النص غير المعروف، مثل `status` في قاعدة مشكلة، يعيد `422` مع `code: invalid_json`. والسجل أو المشكلة المفقودة أو غير المقروءة تعيد `404` مع `code: not_found`. إذا ضاعت الاستجابة، فاقرأ السجل أو المشكلة مرة أخرى قبل أن ترسل القاعدة مرة أخرى.
## تنسيق استجابة الخطأ
تعيد أخطاء LogBrew API غلاف JSON. يعرض هذا المثال طلبًا مرفوضًا؛ ويعتمد نص `error` و`next` على المشكلة:
```json theme={null}
{
"error": "",
"code": "validation_failed",
"next": "",
"next_action": {
"code": "fix_request",
"target": "request"
}
}
```
استخدم `code` لفروع البرنامج، و`next_action` للأتمتة. اعرض `error` و`next` على الأشخاص نصًا عاديًا. لا تحلّل صياغتهما. تضيف بعض الأخطاء حقولًا، مثل `limit` أو `reset_at` أو `retry_after_seconds`. الاستجابة التي ليس لها نص JSON ليس لها `code` من LogBrew. راجع [أخطاء API](/ar/reference/api-errors) لكل الرموز.
## اقرأ البيانات باستخدام CLI
يقرأ CLI المسارات نفسها ويعيد JSON نفسه مع `--json`. ابدأ بنطاق واسع، ثم ضيّقه:
```bash theme={null}
logbrew read releases --environment production --json
logbrew read issues --release api@1.2.3 --status unresolved --json
logbrew read logs --release api@1.2.3 --since 24h --json
logbrew read actions --name checkout_failed --since 24h --json
logbrew read traces --status error --since 24h --json
logbrew read trace --json
```
أضف `--pagination cursor` لتحصل على غلاف المؤشر. يطلب CLI نسخة استجابة المشكلة 4. راجع [اقرأ الصفحة التالية](/ar/reference/cli#read-the-next-page) و[المتابعة المباشرة](/ar/reference/cli#live-watch).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.