للتحقق مما إذا كان الاشتباه في انقطاع الخدمة يتوافق مع عمليات الرصد في منطقة بعينها، اطلب حالة الخدمة وسجلها خلال فترة زمنية محددة. طابق المنطقة والطوابع الزمنية مع سجلات التطبيق. تجيب النتيجة عن سؤال محدد: هل سُجلت إشارة إقليمية في البيانات المحفوظة، وما مدى حداثة السجل ذي الصلة؟
تصف مواصفات UptimeScout طرائق منفصلة للحالة والسجل. في استجابة الحالة، يشير الحقل الأعلى مستوى `status` إلى نتيجة طلب واجهة API؛ أما إشارة الخدمة فتوجد في `service.status`. ويتضمن السجل فترات زمنية مجمّعة ودقة التجميع وعدد العينات. وهذه بيانات مفيدة للتشخيص الأولي ولإرفاقها بتقرير الحادث.
1. جهّز الخدمة والمنطقة والترخيص
يستخدم المثال أدناه معرّف الخدمة `github` والمنطقة `US`. في عملية التحقق الخاصة بك، استخدم معرّفًا صالحًا من دليل UptimeScout ورمز المنطقة التي رُصدت فيها المشكلة. قد تختلف المناطق المتاحة باختلاف الخدمات؛ لذا تحقّق من `available_regions` في الاستجابة قبل تفسيرها.

ثبّت Python 3.10 أو إصدارًا أحدث، وثبّت SDK وفقًا لتعليمات المشروع. ضع المفتاح في متغير البيئة `UPTIMESCOUT_LICENSE_KEY` ولا تُدرجه في الشيفرة أو السجلات. ينفّذ المثال طلبين عبر العميل الموثّق، ويحفظ استجابتي JSON الخام في الذاكرة ويطبعهما للتحقق. هذا مثال على التكامل، وليس تقريرًا عن اختبار نُفّذ هنا.
import json
import os
from uptimescout import Client, UptimeScoutError
client = Client(os.environ["UPTIMESCOUT_LICENSE_KEY"], timeout=30)
try:
status_data = client.status("github", region="US", lang="ru")
history_data = client.history("github", region="US", hours=24, lang="ru")
except UptimeScoutError as error:
raise SystemExit(f"API request failed: HTTP {error.status}")
print(json.dumps(
{"status": status_data, "history": history_data},
ensure_ascii=False,
indent=2,
))
يوثّق Python SDK من UptimeScout العميل وطرائق `status` و`history`، وكذلك المصادقة باستخدام Bearer ضمنيًا. اتبع تعليمات المستودع الحالية للتثبيت والإصدارات؛ فالمقتطف المعروض يفترض أن SDK مثبت.
2. تأكد من أنك تقرأ الإشارة لا حالة الطلب
تحقق من الحقول `service.status` و`service.observed_at` و`service.stale` والمنطقة الواردة في الاستجابة. يشير `status` في المستوى الأعلى إلى نجاح طلب واجهة API، لا إلى إتاحة الخدمة نفسها. احفظ أيضًا وقت الطلب ومعرّف الخدمة ومعلمات المنطقة، كي يتضح السجل الذي تستند إليه النتيجة.
إذا وُصفت الملاحظة بأنها حديثة وكان `service.status` يشير إلى تدهور أو انقطاع، فسجّل ذلك بوصفه إشارة إقليمية وقارنه بسجلاتك وأخطاء الاتصال وفحوص التطبيق. يبيّن الحقل `stale` ما إذا كانت الملاحظة المحفوظة قد تجاوزت فترة الحداثة المحددة. إذا كانت قيمته `true` أو كان الحقل المطلوب غائبًا، فصِف الإتاحة الحالية بأنها غير معروفة استنادًا إلى هذه الاستجابة؛ ولا تستنتج الحالة الراهنة من سجل قديم أو غير مكتمل.
تصف UptimeScout بياناتها بأنها إشارات إقليمية محفوظة: وهي مرجع للتشخيص، وليست قياسًا مباشرًا لزمن التشغيل ولا إثباتًا على انقطاع عالمي. لذا صغ النتيجة بدقة: «عُثر في المنطقة على إشارة من هذا النوع، سُجلت في الوقت المحدد». وتُظهر المقارنة مع فحوصك ما إذا كانت هذه الإشارة الخارجية تتفق مع تجربة مستخدمي تطبيقك.
3. طابق السجل ودقة الفترات
تعيد طريقة السجل بيانات مجمّعة زمنيًا. تحقّق في الاستجابة من `resolution_seconds` و`samples` و`counts` و`effective_start`، واحفظ أيضًا الحدود الزمنية الفعلية للفترات. توضح الوثائق أن المحاذاة تتم وفق التوقيت العالمي المنسق (UTC): فترات مدتها ثلاث دقائق للنوافذ التي لا تتجاوز ساعة، وخمس دقائق للنوافذ التي لا تتجاوز ثلاث ساعات، وساعة واحدة للنوافذ التي تصل إلى يوم، وفترات يومية للنوافذ الأطول. وقد تظل البيانات المجمّعة القديمة محفوظة بدقة معلنة أقل.

لذلك اختر نافذة زمنية تناسب السؤال. استخدم نطاقًا قصيرًا ملائمًا للحوادث القصيرة، واعرض دقة التجميع بجوار النتيجة. أما عند تناول فترة طويلة، فاذكر أن السجل قد يكون مجمّعًا حسب الأيام؛ إذ لا تتيح نقطة يومية استعادة التغيرات دقيقة بدقيقة.
الفترات المفقودة بيانات غير معروفة، وليست دليلًا على أن الخدمة عملت بصورة طبيعية. احتفظ بعدد العينات وحدود الفترات بجوار القيم المجمّعة. يساعد ذلك على فهم مدى تغطية السجل للفترة محل البحث والبيانات التي تستند إليها النتيجة.
4. أعدّ سجلًا قابلًا للتحقق عن الحادث
يكفي للتقرير حفظ الاستجابات الأصلية والحقول الموحّدة: الخدمة والمنطقة ووقت الطلب و`service.status` و`observed_at` و`stale` ونافذة السجل المختارة و`resolution_seconds` وعدد العينات و`effective_start`. اترك القيمة المفقودة كما هي؛ فالصفر وغياب البيانات لا يعنيان الشيء نفسه.
بعد ذلك، طابق هذه المعلومات مع الفحوص الداخلية للفترة نفسها: رموز الاستجابة وأخطاء الاتصال ومنطقة الاستضافة والطوابع الزمنية. إذا اختلفت البيانات، فاحتفظ بكلا الجانبين. يرصد UptimeScout منطقةً بعينها، بينما يفحص اختبار نقطة النهاية (endpoint) نقطة رصد مختلفة؛ لذا يتطلب الاختلاف بحد ذاته التحقق، لا اختيار النتيجة الأنسب.
عند حدوث خطأ في واجهة API، استرشد برمز HTTP: تسرد المواصفات معلمات غير صحيحة، وغياب الترخيص، وعدم صلاحية الترخيص، وتجاوز الحصة، وعدم التوفر المؤقت. عالج السبب المناسب. فخطأ الطلب ليس حالة الخدمة الجاري فحصها.
ما الذي تسلّمه إلى المناوب
اذكر في الخلاصة الموجزة الخدمة والمنطقة ووقت الملاحظة وحداثة السجل ودقة السجل الزمني. وعلّم الفترات التي تخلو من البيانات بأنها غير معروفة، وأرفق السجلات الداخلية للفترة المطابقة. وهكذا يحصل الفريق على إشارة إقليمية قابلة للتحقق من دون الخلط بين حالة طلب واجهة API وملاحظات UptimeScout وقياسات التطبيق الداخلية.