تنسيق استجابات API وأمثلة استجابات JSON

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

اقرأ الاستجابة

اقرأ كل استجابة بهذا الترتيب:

اقرأ حالة HTTP.
تأكد أن للنص الشكل الذي يحدده المسار.
تأكد أن كل project_id يقع داخل نطاق المشروع المطلوب.
أبقِ قيم التعداد (enum) المعيارية والمعرّفات دون تغيير.
اتبع next_action فقط عندما يدعم العميل قيمتي code وtarget الخاصتين به.
تعامل مع null والحقل المحذوف والقائمة الفارغة على أنها حالات مختلفة.

قد تحتوي الاستجابة 200 OK على قائمة فارغة. قائمة السجلات الفارغة تعني أنه لم يطابق أي سجل الطلب. ولا تعني أن المشكلات أو التتبّعات أو الإجراءات فارغة أيضًا. لا تربط الإشارات لأن طوابعها الزمنية متقاربة. اتبع تتبّعًا فقط عندما تحتوي الاستجابة على trace_id الخاص به تمامًا. الاستجابة 404 والقائمة الفارغة نتيجتان مختلفتان. يعيد مسار القائمة [] عندما لا يطابق أي قيد. ويعيد مسار التفاصيل 404 مع code: not_found عندما لا يجد قيدًا يمكن قراءته. لا تثبت أي من النتيجتين أن الاستيعاب فشل.

ما يجب إرساله

فائدة الاستجابات بقدر فائدة بيانات القياس عن بُعد التي ترسلها. أرسل هذه القيم في كل غلاف أو إعداد SDK:

release وenvironment.
أسماء ثابتة للخدمات والإجراءات والمقاييس.
سياق التتبّع عندما تنتمي السجلات والـ Spans والإجراءات والمشكلات إلى الطلب نفسه.
قيم الخطورة المعيارية: info وwarning وerror وcritical.
سمات تساعد في تصحيح الأخطاء، دون أسرار أو بيانات شخصية غير ضرورية.

راجع دمج SDK والتحكم في البيانات الملتقطة.

استجابة الاستيعاب

تقرأ حزم SDK العامة استجابة POST /v1/events نيابةً عنك. لا تحتاج شيفرة التطبيق إلى معالجتها.

استجابة دفعة SDK

تعيد دفعة SDK الناجحة 200 OK مع الأعداد المقبولة لكل تدفق:

{
  "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 مع أعداد العناصر المقبولة لكل تدفق:

{
  "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 الخاصة بها سابقًا لهذا المشروع. راجع الغلاف الأصلي المباشر.

أخطاء الاستيعاب

الاستجابة 401 مع code: ingest_key_invalid تعني أن رمز Bearer للاستيعاب مُبطَل أو منتهي الصلاحية أو غير صالح للمشروع. في POST /v1/events، يعيد الطلب 401 مع code: unauthorized عندما يغيب رمز Bearer أو لا يكون مفتاح استيعاب. استخدم رمز Bearer الحالي للاستيعاب الخاص بالمشروع. لا تُعد المحاولة باستخدام رمز Bearer للحساب. تعيد دفعة SDK المرفوضة 422 مع code: validation_failed:

{
  "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 في الصفحة الأخيرة. الصفوف مرتبة من الأحدث إلى الأقدم. راجع ترقيم الصفحات بالمؤشر.

استجابة السجل

صفحة مؤشر للسجلات مع limit=1:

{
  "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 نتيجة قاعدة الخطورة. راجع استجابات قواعد الخطورة. يكون 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:

{
  "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 والقراءات التي تليها، راجع التحقيق في مشكلة. first_seen_at وlast_seen_at هما وقتا أول حدوث وأحدث حدوث. لا يتغيران عندما تتغير الحالة. تظهر بعض الحقول فقط عندما تتوفر البيانات لدى LogBrew:

الحقل	متى يظهر
`span_id`	للمشكلة رابط Span. وإلا يُحذف الحقل.
`diagnostics`	لأحدث حدوث نوع استثناء أو Breadcrumbs (أحداث قصيرة مسجَّلة قبل وقوع المشكلة). راجع تاريخ مرات حدوث المشكلة.
`symbolication`	في `GET /api/telemetry/issues/{issue_id}` فقط، عندما تكون للمشكلة هوية ملف بناء خاصة بالإصدار. راجع خرائط المصدر لـ JavaScript.

قيمة 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` عندما تتبع الأولوية الخطورة الفعلية.

{
  "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 عندما لا يكون للمشكلة مسؤول:

{
  "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:

{
  "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=<project_id> كل حساب يمكن إسناد المشكلات إليه في المشروع:

{
  "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.

استجابة الإجراء

{
  "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 عندما يكون مفقودًا. ليس للإجراء خطورة. راجع التقاط أحداث المنتج.

استجابة المقياس

{
  "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 ليست صفرًا.

استجابة الإصدار

{
  "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`

راجع الإصدارات.

استجابة اكتشاف التتبّعات

يعيد GET /api/telemetry/traces?pagination=cursor صفًا واحدًا لكل تتبّع، بالإضافة إلى إيصال naming_quality للصفحة المُعادة:

{
  "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 التتبّع وملخصه.

القوائم الفارغة والقيود المفقودة

قد لا تكون لقراءة القائمة نتائج مطابقة. أما قراءة التفاصيل فلها عقد مختلف:

الطلب	النجاح	لا يوجد قيد يمكن قراءته
`GET /api/logs/{log_id}`	`200` مع سجل واحد	`404` مع `code: not_found`
`GET /api/telemetry/issues/{issue_id}`	`200` مع مشكلة واحدة	`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:

{
  "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:

{
  "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. ولا يعيد المشاريع الأخرى نتيجةً جزئية:

{
  "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 لمشروع خارج نطاق اتصالها. راجع نطاق المشروع.

أخطاء المؤشر

تستخدم السجلات والمشكلات والإجراءات والمقاييس ومرات حدوث المشكلات 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`

مثلًا:

{
  "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:

{
  "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 الأخطاء نفسها التي تعيدها المؤشرات الأخرى.

أخطاء اكتشاف التتبّعات

تنطبق هذه الأخطاء على 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 لصفحة تتبّعات. راجع عوامل تصفية التتبّعات.

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

يقرأ GET /api/telemetry/issues/{issue_id}/events مرات حدوث مشكلة مجمّعة واحدة. استخدم رمز Bearer للحساب ومعرّف المشكلة المجمّعة. يقبل المسار فقط pagination وcursor_time وcursor_id وlimit. ولا يقبل عوامل التصفية حسب المشروع أو الوقت أو الإصدار أو البيئة أو الخطورة.

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"

صفحة أولى فيها حدوث واحد ومؤشر متابعة:

{
  "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`	معرّف حدوث واحد. استخدمه لاختيار ذلك الحدوث.
`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 عندما لا تكون للمشكلة مرات حدوث يمكن قراءتها. وقد تكون صفحة لاحقة صفحة أخيرة فارغة:

{
  "issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
  "events": [],
  "next_cursor": null
}

لا تُعد استخدام مؤشر لمشكلة أخرى. تنطبق أخطاء المؤشر على هذا المسار.

استجابات Spans التتبّع وملخصه

يعيد GET /api/telemetry/traces/{trace_id} الـ Spans لتتبّع واحد. أضف /summary لتحصل على ملخص للـ Spans نفسها. يقبل المساران كلاهما فقط project_id وrelease وenvironment. ولا يستخدمان مؤشر اكتشاف التتبّعات. ولا تنتقل عوامل التصفية من طلب قائمة سابق.

قائمة الـ Spans

الـ Spans مرتبة حسب وقت البدء:

[
  {
    "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:

{
  "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 للحساب. ليس للطلب نص.

curl --request POST "https://api.logbrew.co/api/feed/ticket" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

تحتوي الاستجابة 200 OK على التذكرة في الحقل ticket:

{
  "ticket": "<feed-ticket>",
  "expires_in_seconds": 60,
  "next": "connect with GET /api/feed/live?ticket=<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=<feed-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`	بيانات سجل، بشكل استجابة السجل.
`native_issue`	بيانات مشكلة مجمّعة، بشكل استجابة المشكلة في النسخة 1.
`native_trace_span`	Span واحد، بشكل عنصر قائمة الـ Spans.
`native_action`	بيانات إجراء منتج، بشكل استجابة الإجراء.
`project_created`، `project_updated`، `project_catalog_changed`	بيانات المشروع. اقرأ قائمة المشاريع مرة أخرى عندما تتغير.
`usage_updated`، `usage_limit_warning`، `usage_limit_blocked`	استخدام الحساب، بشكل استخدام الحساب.

{
  "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.

تعامل مع الاتصال المغلق

رمز الإغلاق	السبب	الخطوة التالية
`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 مع المشكلة المجمّعة المحدَّثة، بشكل استجابة المشكلة نفسه. يختار مفتاح الاستعلام response_version النسخة. ولا يعيد المسار علامة نجاح. يضبط النص حقلًا واحدًا أو أكثر من status وpriority وassignee. يقبل status القيم unresolved أو resolved أو archived. وignored اسم أقدم لـ archived. راجع حدّث مشكلة واحدة. تحقق من id وstatus وpriority في الاستجابة قبل أن تعرض النجاح. لا تبنِ النتيجة من القيم المرسلة. تغيير الحالة لا يحذف مرات الحدوث، ولا يغيّر first_seen_at وlast_seen_at. ولا يغيّر severity أو قاعدة الخطورة. يعيد التغيير المرفوض 422 مع code: validation_failed:

{
  "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:<team_id>`	قيمة المسؤول غير مدعومة.
`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`	لا يستطيع الحساب قراءة المشكلة، أو المشكلة غير موجودة.

الحقل الذي له القيمة المطلوبة بالفعل لا يتغير. بعد انتهاء المهلة أو ضياع الاستجابة، أرسل الطلب نفسه مرة أخرى، أو اقرأ المشكلة أولًا. لا ترسل تغييرًا مختلفًا قبل أن تقرأ الحالة الحالية. راجع عمليات الكتابة. يعيد POST /api/telemetry/issues/bulk الاستجابة 200 OK مع نتيجة واحدة لكل معرّف مشكلة مطلوب، بترتيب الطلب. تستخدم كل مشكلة موجودة شكل النسخة 3. ولنتيجة not_found القيمة issue: 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 ولا يغيّر شيئًا. راجع حدّث المشكلات دفعة واحدة. يفشل الطلب الجماعي كله في هذه الحالات:

النتيجة	السبب
`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 يعيد:

{
  "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 مع استجابة معاملات الاستعلام غير الصالحة. ويعيد حقل JSON غير المعروف، أو حقل JSON المطلوب المفقود، أو قيمة التعداد غير المدعومة invalid_json. راجع JSON غير صالح. والطلب بطريقة HTTP خاطئة يعيد 405 وmethod_not_allowed. ويسمّي نص next فيه الطريقة والحقول المدعومة. راجع طريقة غير مدعومة.

استجابة النظرة العامة لتحليلات المنتج

يعرض GET /api/telemetry/analytics/overview النشاط في مشروع واحد: حجم الإجراءات، والمستخدمين، والجلسات، وسلسلة زمنية، وأبرز الإجراءات، ومشاهدات الصفحات ومشاهدات الشاشات والتفاعلات المصنَّفة. استخدمه لتجد أسماء الأحداث الدقيقة لمسارات التحليلات الأخرى. أرسل response_version=3. تعيد النسختان 1 و2 الأعداد نفسها، لكن قيمة estimation.method فيهما رمز أقدم. لا تتحقق النسخة 1 من نوع الكيان عندما تعدّ المستخدمين معروفي الهوية. وتعدّ النسختان 2 و3 فقط الكيانات من النوع user، وتضيفان أعداد الكيانات مجهولة الهوية وsubject_coverage. يقرأ هذا الطلب ساعة واحدة في فواصل زمنية مدة كل منها خمس دقائق، ويعيد صفين في كل قائمة من القوائم الأبرز:

curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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 إجراءً في فاصلين زمنيين من الفواصل الاثني عشر. يأتي عشرون إجراءً من كيانات مجهولة الهوية. لكل إجراء معرّف جلسة. ولنصف الإجراءات معرّف تتبّع.

{
  "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. راجع تحليلات المنتج.

أخطاء النظرة العامة

بالإضافة إلى أخطاء النطاق المشتركة، تعيد النظرة العامة 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 ثم تكمل التسجيل خلال ساعة واحدة:

{
  "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:

{
  "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 استخدامها. لا تعيد الاستجابة الهويات الخام. راجع تحليلات المنتج.

اقرأ التحويل والتغطية

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`	أكملت وحدة واحدة على الأقل قمع التحويل.

طلبات قمع التحويل المرفوضة

بالإضافة إلى أخطاء النطاق المشتركة، تعيد هذه الطلبات 422 وvalidation_failed. أقل من خطوتين أو أكثر من 8 خطوات:

{
  "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، أو قيمة أكبر من طول النطاق:

{
  "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. وهو يسأل هل يكمل المستخدمون عملية إتمام شراء أخرى بعد أول عملية إتمام شراء لهم في النطاق:

{
  "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 يونيو، يشاهد المستخدم الثاني صفحة لكنه لا يُتم عملية شراء أخرى.

{
  "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.

{
  "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 نفسها التي لاستجابة الأحداث المحددة. يعرض هذا المقتطف الحقول التي تتغير. في هذا المثال، للمستخدمَين نفسيهما ثلاثة أحداث وليس لهما مشاهدة صفحة:

{
  "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. هذه الأعداد أحداث، لا مستخدمون.

الاحتفاظ بالمستخدمين دون مستخدمين مؤهلين

قد لا يكون في النتيجة الناجحة مستخدمون ضمن المجموعات النموذجية. يعرض هذا المقتطف فترة واحدة مطلوبة دون مجموعات نموذجية:

{
  "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). المعدّل المفقود ليس صفرًا مقيسًا.

أخطاء الاحتفاظ بالمستخدمين

بالإضافة إلى أخطاء النطاق المشتركة، تعيد هذه الطلبات 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:

{
  "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. وهو يصنّف المستخدمين حسب حدث واحد، لا حسب كل نشاط في المشروع:

{
  "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 يونيو. هذا الحدث لا يطابق مُحدِّد إتمام الشراء.

{
  "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. كل مشاهدة صفحة أو مشاهدة شاشة أو تفاعل مدعوم يُحسب نشاطًا:

{
  "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 نفسها التي لاستجابة الأحداث المحددة. يعرض هذا المقتطف الحقول التي تتغير:

{
  "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:

{
  "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": []
}

المستخدمون الذين يظهرون في التاريخ المرصود فقط قد ينتجون مع ذلك فواصل زمنية فيها مستخدمون خاملون عندما لا يكون في نطاق التحليل نشاط.

أخطاء دورة الحياة

بالإضافة إلى أخطاء النطاق المشتركة، تعيد هذه الطلبات 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 يومًا:

{
  "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) حسب الخدمة:

curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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 في الفاصل الزمني الأخير. لا تقع أي عيّنة في الفاصل الزمني الأوسط، لذلك ليس للاستجابة نقطة له.

{
  "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 هو آخر تغير مُدوَّن، لا المجموع. راجع معاني تجميع المقاييس. يحدد نوع السلسلة وطبيعتها الزمنية (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:

{
  "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:

{
  "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.

{
  "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 مطلوبان.

نجاح المسارات

في هذه النتيجة المصطنعة، تحتوي أربع جلسات على الحدث المرجعي. يمثّل المساران المُعادان ثلاثًا من هذه الجلسات. ولا يُعاد مسار واحد أدنى ترتيبًا.

{
  "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 محددان تمامًا. انسخ المفتاح من فهرس الخصائص. تنطبق عوامل التصفية على الحدث المرجعي فقط، لا على الأحداث المحيطة به. القيم حساسة لحالة الأحرف. عندما توجد عوامل تصفية، يعيدها 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. بالإضافة إلى أخطاء النطاق المشتركة، تعيد هذه الطلبات 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 يعيد:

{
  "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 مفاتيح الخصائص في أحداث المنتج المصنَّفة في مشروع واحد. استخدم المفاتيح في مقارنات الشرائح وفي عوامل تصفية الحدث المرجعي للمسارات. يعيد الفهرس المفاتيح والأعداد. ولا يعيد قيم الخصائص أو الهويات أبدًا.

اقرأ مفاتيح الخصائص المتاحة

أرسل project_id وsince. يمكنك أيضًا إرسال until وservice_name وrelease وenvironment وlimit وresponse_version. يقبل limit من 1 إلى 50 مفتاحًا. القيمة الافتراضية 20. أرسل response_version=2 لتحصل على قيمة estimation.method العامة.

curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<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 حدث مصنَّف. التُقطت خمسة منها قبل فهرس الخصائص الحالي.

{
  "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.

أخطاء فهرس الخصائص

بالإضافة إلى أخطاء النطاق المشتركة، يعيد limit=0 أو limit=51 الاستجابة 422:

{
  "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:

{
  "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:

{
  "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.

{
  "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 الحقول نفسها التي لـ تغطية عوامل تصفية الحدث المرجعي للمسارات. هنا يساوي matching_events قيمة classified_events. أبقِ المفاتيح المفقودة والقيم المختلفة منفصلة. يمكن أن تتداخل الشرائح، وقد تظهر الجلسة الواحدة في عدة فواصل زمنية. لا تجمع أعداد الوحدات عبر الشرائح أو الفواصل الزمنية. المقارنة وصفية. قيمة confidence.causal_inference هي not_established، وقيمة confidence.statistical_significance هي not_tested. معدّل 30% مقابل 20% لا يبيّن أن خطةً تسببت في زيادة عمليات إتمام الشراء.

أخطاء مقارنة الشرائح

بالإضافة إلى أخطاء النطاق المشتركة، تعيد هذه الطلبات 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 هي نفسها أخطاء النظرة العامة. مثلًا، شريحتان لهما مفتاحان مختلفان وعوامل تصفية متطابقة تعيدان:

{
  "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:

{
  "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 يومًا. اقرأ السياسة وتاريخ القطع المُعادين. لا تفترض أن هذه القيم تنطبق على حسابك.

{
  "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`

مثلًا:

{
  "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.

استجابات التحقيق

تعيد مسارات التحقيق حزمة ذات نسخة لعنصر واحد قيد التحقيق. العنصر مشكلة أو تتبّع أو Span أو سجل أو إجراء منتج أو مقياس أو إصدار. تبدأ كل حزمة بـ schema_version وبـ subject الذي يسمّي القيد. ويحمل الباقي الأدلة المرتبطة وإيصال الأدلة والخطوات التالية. يعرض هذا القسم مثالًا واحدًا لكل عائلة ما عدا الإصدار. أرسل رمز Bearer للحساب. لا يستطيع مفتاح استيعاب المشروع قراءة التحقيق. استخدم logbrew explain <subject> --json لقراءة حزمة. يتحقق CLI من صحة الحزمة قبل أن يطبعها. يسرد مرجع 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 لقراءة الأدلة لحدوث واحد من مشكلة مجمّعة. تبيّن إرشادات التحقيق في مشكلة كيف تقرأ الأدلة بالترتيب. اطلب النسخة 13:

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 أحدث حدوث محتفَظ به ولا تقبل أي مُحدِّد. لا تنطبق عوامل تصفية قائمة المشكلات على هذه القراءة.

مثال على التحقيق في مشكلة بالنسخة 13

لاستجابة 200 OK المصطنعة هذه حدوث TypeError معالَج واحد مع تتبّع مرتبط. ليس فيها طلب ولا Breadcrumbs ولا سجلات مرتبطة ولا أدلة نشر، لذلك قيمة evidence.status هي partial.

{
  "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. لا ترسلهما معًا، حتى عندما يختاران الحدوث نفسه:

{
  "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` غير معروفة.	صحّح الاستعلام.
`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:

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 إلى المشكلات والإجراءات والمقاييس المرتبطة عندما يكون قد التُقط.

مثال على التحقيق في تتبّع بالنسخة 3

في هذه الاستجابة المصطنعة Span خادم جذري وSpan عميل فاشل. والـ Span الفاشل هو أيضًا أبطأ Span فرعي. ليس للـ Spans سياق منظّم، لذلك spans.context مفقود.

{
  "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.

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 نفسه. استغرق الـ Span وقتًا أطول من المئين 95 التقريبي لنظرائه المحتفَظ بهم.

{
  "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 لقراءة سجل واحد وأدلته المرتبطة. ليس لهذا المسار مفاتيح استعلام. انسخ معرّف السجل من قائمة سجلات.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/logs/$LOG_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

قد تعيد القراءة أدلة خارج عوامل تصفية قائمة السجلات. تستخدم القراءات المرتبطة مشروع السجل وبيئته وإصداره، و5 دقائق قبل السجل وبعده. وتستخدم السجلات القريبة أيضًا الخدمة نفسها. ولا تحتاج إلى معرّف تتبّع. أما قراءات التتبّع المطابق تمامًا فتحتاج إلى معرّف تتبّع السجل، وقد تتضمن خدمات أخرى. ويستخدم ملخص التتبّع معرّف التتبّع والنطاق نفسيهما، دون النطاق الزمني.

مثال على التحقيق في سجل

في هذه الاستجابة المصطنعة سجل تحذير دون سياق تتبّع، وسجل قريب واحد. لا تبني الاستجابة رابط تتبّع من الطوابع الزمنية.

{
  "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 لقراءة إجراء منتج واحد وحالته المبلَّغ عنها وأدلته المرتبطة. ليس لهذا المسار مفاتيح استعلام. تستخدم القراءات المرتبطة النطاق الزمني والنطاقات نفسها التي يستخدمها التحقيق في السجل.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/telemetry/actions/$ACTION_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

تستخدم correlations وtimeline وnext_actions أشكال التحقيق في السجل. وتستبعد الإجراءات المرتبطة الإجراء قيد التحقيق.

مثال على التحقيق في إجراء

تصف هذه الاستجابة المصطنعة إجراء إتمام شراء فاشلًا من مستخدم مسجَّل الدخول. ليس للإجراء معرّف تتبّع.

{
  "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".

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 هي الآن. وتقرأ المقارنة أيضًا النطاق السابق المساوي في الطول.

مثال على التحقيق في مقياس بالنسخة 2

في هذا المدرّج التكراري المصطنع 5 عيّنات في فاصلين زمنيين مدة كل منهما 5 دقائق. قيمة p95 في الفاصل الأحدث 48 ms. وقيمة p95 في أحدث فاصل من النطاق السابق 24 ms.

{
  "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 لاستجابات عدم العثور والمسار والمصادقة والطريقة. قد تفشل قراءة أدلة اختيارية داخل استجابة 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 كليهما:

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 على السجل كاملًا. تبقى قيمة severity فيه warning. ويعرض triage القاعدة:

{
  "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 فقط:

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 على المشكلة كاملة بالنسخة 1. ولا تتغير severity وstatus الملتقَطتان:

{
  "severity": "error",
  "status": "unresolved",
  "triage": {
    "effective_severity": "warning",
    "ignored": false,
    "rule_applied": true
  }
}

يعرض هذا المقتطف بعض الحقول فقط. لا تحلّ القاعدة المشكلة ولا تؤرشفها ولا تعيد فتحها. استخدم تغيير الحالة لذلك. تتبع الأولوية المشتقة الخطورة الفعلية الجديدة. اقرأ المشكلة مع response_version=2 أو 3 لتراها. الخطورة غير المدعومة تعيد 422:

{
  "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 على المشكلة:

{
  "error": "<what is wrong>",
  "code": "validation_failed",
  "next": "<how to fix it>",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

استخدم code لفروع البرنامج، وnext_action للأتمتة. اعرض error وnext على الأشخاص نصًا عاديًا. لا تحلّل صياغتهما. تضيف بعض الأخطاء حقولًا، مثل limit أو reset_at أو retry_after_seconds. الاستجابة التي ليس لها نص JSON ليس لها code من LogBrew. راجع أخطاء API لكل الرموز.

اقرأ البيانات باستخدام CLI

يقرأ CLI المسارات نفسها ويعيد JSON نفسه مع --json. ابدأ بنطاق واسع، ثم ضيّقه:

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 <trace_id> --json

أضف --pagination cursor لتحصل على غلاف المؤشر. يطلب CLI نسخة استجابة المشكلة 4. راجع اقرأ الصفحة التالية والمتابعة المباشرة.

​اقرأ الاستجابة

​ما يجب إرساله

​استجابة الاستيعاب

​استجابة دفعة SDK

​استجابة الغلاف الأصلي

​أخطاء الاستيعاب

​تنسيق استجابة قوائم بيانات القياس عن بُعد

​استجابة السجل

​استجابة المشكلة

​استجابة قائمة المسؤولين

​استجابة الإجراء

​استجابة المقياس

​استجابة الإصدار

​استجابة اكتشاف التتبّعات

​القوائم الفارغة والقيود المفقودة

​تحديدات المشاريع المرفوضة

​أخطاء المؤشر

​استجابات مؤشر الإصدارات

​أخطاء اكتشاف التتبّعات

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

​استجابات Spans التتبّع وملخصه

​قائمة الـ Spans

​ملخص التتبّع

​لا توجد Spans مطابقة

​تنسيق استجابة الأحداث المباشرة

​أنشئ تذكرة

​افتح الاتصال

​اقرأ الرسائل

​تعامل مع الاتصال المغلق

​أمثلة استجابات حالة المشكلة

​نطاق طلبات التحليلات

​أخطاء النطاق المشتركة

​استجابة النظرة العامة لتحليلات المنتج

​نجاح النظرة العامة

​اقرأ النظرة العامة

​أخطاء النظرة العامة

​استجابة قمع التحويل المرتب

​نجاح قمع التحويل

​اقرأ التحويل والتغطية

​نتائج قمع التحويل الفارغة

​طلبات قمع التحويل المرفوضة

​التحليل بأحداث محددة والتحليل التلقائي

​طلب الاحتفاظ بالمستخدمين لأحداث محددة

​نجاح الاحتفاظ بالمستخدمين لأحداث محددة

​اقرأ الاحتفاظ بالمستخدمين

​الاحتفاظ بالمستخدمين تلقائيًا

​الاحتفاظ بالمستخدمين دون مستخدمين مؤهلين

​أخطاء الاحتفاظ بالمستخدمين

​طلب دورة الحياة لحدث محدد

​نجاح دورة الحياة لحدث محدد

​اقرأ دورة الحياة

​دورة الحياة تلقائيًا

​دورة الحياة دون مستخدمين

​أخطاء دورة الحياة

​اقرأ نطاق التحليل المختار

​استجابة سلسلة المقياس

​نجاح سلسلة المقياس

​اقرأ سلسلة المقياس

​نطاق سلسلة المقياس وأخطاؤها

​استجابة تحليل المسارات

​نجاح المسارات

​اقرأ المسارات

​صفِّ الحدث المرجعي حسب خاصية

​المسارات الفارغة والطلبات المرفوضة

​فهرس خصائص التحليلات

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

​نجاح فهرس الخصائص

​فسّر الفهرس

​أخطاء فهرس الخصائص

​مقارنة شرائح التحليلات

​حدّد المقارنة

​نجاح مقارنة الشرائح

​اقرأ المعدّلات والفروق

​أخطاء مقارنة الشرائح

​استجابة حجم الإشارات

​أعداد الإشارات

​اقرأ كل عدد بوحدته

​النطاقات الفارغة والمقصَّرة

​طلبات حجم الإشارات المرفوضة

​استجابات التحقيق

اقرأ الاستجابة

ما يجب إرساله

استجابة الاستيعاب

استجابة دفعة SDK

استجابة الغلاف الأصلي

أخطاء الاستيعاب

تنسيق استجابة قوائم بيانات القياس عن بُعد

استجابة السجل

استجابة المشكلة

استجابة قائمة المسؤولين

استجابة الإجراء

استجابة المقياس

استجابة الإصدار

استجابة اكتشاف التتبّعات

القوائم الفارغة والقيود المفقودة

تحديدات المشاريع المرفوضة

أخطاء المؤشر

استجابات مؤشر الإصدارات

أخطاء اكتشاف التتبّعات

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

استجابات Spans التتبّع وملخصه

قائمة الـ Spans

ملخص التتبّع

لا توجد Spans مطابقة

تنسيق استجابة الأحداث المباشرة

أنشئ تذكرة

افتح الاتصال

اقرأ الرسائل

تعامل مع الاتصال المغلق

أمثلة استجابات حالة المشكلة

نطاق طلبات التحليلات

أخطاء النطاق المشتركة

استجابة النظرة العامة لتحليلات المنتج

نجاح النظرة العامة

اقرأ النظرة العامة

أخطاء النظرة العامة

استجابة قمع التحويل المرتب

نجاح قمع التحويل

اقرأ التحويل والتغطية

نتائج قمع التحويل الفارغة

طلبات قمع التحويل المرفوضة

التحليل بأحداث محددة والتحليل التلقائي

طلب الاحتفاظ بالمستخدمين لأحداث محددة

نجاح الاحتفاظ بالمستخدمين لأحداث محددة

اقرأ الاحتفاظ بالمستخدمين

الاحتفاظ بالمستخدمين تلقائيًا

الاحتفاظ بالمستخدمين دون مستخدمين مؤهلين

أخطاء الاحتفاظ بالمستخدمين

طلب دورة الحياة لحدث محدد

نجاح دورة الحياة لحدث محدد

اقرأ دورة الحياة

دورة الحياة تلقائيًا

دورة الحياة دون مستخدمين

أخطاء دورة الحياة

اقرأ نطاق التحليل المختار

استجابة سلسلة المقياس

نجاح سلسلة المقياس

اقرأ سلسلة المقياس

نطاق سلسلة المقياس وأخطاؤها

استجابة تحليل المسارات

نجاح المسارات

اقرأ المسارات

صفِّ الحدث المرجعي حسب خاصية

المسارات الفارغة والطلبات المرفوضة

فهرس خصائص التحليلات

اقرأ مفاتيح الخصائص المتاحة

نجاح فهرس الخصائص

فسّر الفهرس

أخطاء فهرس الخصائص

مقارنة شرائح التحليلات

حدّد المقارنة

نجاح مقارنة الشرائح

اقرأ المعدّلات والفروق

أخطاء مقارنة الشرائح

استجابة حجم الإشارات

أعداد الإشارات

اقرأ كل عدد بوحدته

النطاقات الفارغة والمقصَّرة

طلبات حجم الإشارات المرفوضة

استجابات التحقيق