כדי לבדוק אם חשד לתקלה תואם לתצפיות באזור מסוים, בקשו את סטטוס השירות ואת ההיסטוריה עבור חלון הזמן הנבחר. השוו את האזור ואת חותמות הזמן ליומני היישום. התוצאה עונה על שאלה ממוקדת: האם הנתונים השמורים כוללים אות אזורי, ועד כמה הרשומה הרלוונטית עדכנית.
מפרט 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 ובדיקה של נקודת קצה מסוימת מתארות נקודות תצפית שונות, ולכן אי-ההתאמה כשלעצמה דורשת בדיקה — ולא בחירה בתשובה הנוחה יותר.
במקרה של שגיאת API, היעזרו בקוד HTTP: המפרט מפרט פרמטרים שגויים, רישיון חסר, רישיון לא תקף, חריגה מהמכסה ואי-זמינות זמנית. תקנו את הגורם המתאים. שגיאת בקשה אינה סטטוס של השירות הנבדק.
מה להעביר לאיש הכוננות
בסיכום קצר ציינו את השירות, האזור, שעת התצפית, עדכניות הרשומה ורזולוציית ההיסטוריה. סמנו בנפרד מרווחים ללא נתונים כלא ידועים וצרפו יומנים פנימיים מאותה תקופה. כך הצוות יקבל אות אזורי שניתן לבדוק, בלי לערבב בין מצב בקשת ה-API, תצפיות UptimeScout והמדידות העצמאיות של היישום.