Wenn Nutzer in einem Land Probleme melden, während das Team einen normalen Betrieb des Dienstes sieht, ist es am hilfreichsten, die Beobachtungen für genau ihre Region zu prüfen. Mit der UptimeScout API lässt sich der Verlauf eines ausgewählten Dienstes anhand eines Regionscodes abrufen – einschließlich Zeitintervallen und Anzahl der Messungen. Das Ergebnis ist eine überprüfbare Tabelle für die Bearbeitung der Meldung: Intervallzeit, Auflösung, Signalverteilung und Anzahl der Samples.

Das praktische Szenario ist die Diagnose eines vermuteten regionalen Ausfalls. Als Eingaben dienen die Dienst-ID aus dem UptimeScout-Katalog, ein Regionscode wie US oder GB und ein Verlaufszeitraum. Das Ergebnis hilft dabei, den Zeitpunkt der Nutzermeldung mit den Beobachtungen zum Dienst abzugleichen. Die API beschreibt die Daten als Signale zur beobachteten Verfügbarkeit; eine Prüfung des Dienstes hilft bei der Eingrenzung, ersetzt aber nicht die eigenen Anwendungstests.
Dienst und Region zunächst bestätigen
Beginnen Sie im Katalog: Suchen Sie den gewünschten Dienst über seinen Namen oder das Suchfeld und notieren Sie anschließend seine genaue ID. Die Spezifikation UptimeScout OpenAPI beschreibt die Suche über GET /v1/services und die Parameter q, service, region, limit und offset. Für einen Diagnosebericht sollte die ID gespeichert werden, nicht nur der angezeigte Name: So richtet sich eine spätere Abfrage an denselben Katalogeintrag.
Die Region wird separat über einen zweibuchstabigen Code angegeben. Speichern Sie diesen zusammen mit dem Ergebnis: Eine Antwort für US und eine Antwort ohne Regionsfilter beantworten unterschiedliche Fragen. Wenn die Beschreibung auf Russisch angezeigt werden soll, steuert der Parameter lang=ru die Lokalisierung der Beschreibung, während region die Beobachtungen auswählt. Die Dokumentation unterscheidet diese beiden Zwecke ausdrücklich.
Den Verlauf statt nur eines Status abrufen
Verwenden Sie zur Untersuchung eines Vorfalls /v1/history mit den Pflichtparametern service und der ausgewählten region. Der Parameter hours legt den Verlaufszeitraum fest; laut Spezifikation sind Werte von 1 bis 2160 Stunden zulässig. Auch lang ist als Parameter vorgesehen. Die Lizenz wird gemäß OpenAPI im Bearer-Schema zur Autorisierung übermittelt. Speichern Sie den Schlüssel bei der praktischen Ausführung in einer Umgebungsvariable und schreiben Sie ihn nicht in das Anforderungsprotokoll.
import os
import requests
response = requests.get(
"https://api.uptimescout.com/v1/history",
headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)
Dies ist ein minimales Beispiel für eine Anfrage, kein veröffentlichtes Ergebnis einer tatsächlichen Untersuchung. Die Dienst-ID github und die Region GB sind Beispielparameter: Wählen Sie vor der Verwendung den für Ihre Aufgabe passenden Dienst und die passende Region. Speichern Sie am besten die vollständige Antwort als JSON und ergänzen Sie in separaten Feldern Ihres Auditsystems den Abrufzeitpunkt und die Beschreibung der Anfrage. So lässt sich die Untersuchung wiederholen und nachvollziehen, welcher konkrete Datenauszug verwendet wurde.
Auflösung und Lücken gehören zum Ergebnis
Im Array history sind die Felder observed_at, resolution_seconds, aggregated, samples und counts wichtig. Die Auflösung gibt die Dauer des Zeitintervalls an; samples zeigt, wie viele Beobachtungen in die Aggregation eingegangen sind, und counts enthält die Signalverteilung. Betrachten Sie die Werte gemeinsam: Eine Zeile mit wenigen samples hat für die Analyse ein anderes Gewicht als eine Aggregation mit vielen Beobachtungen.

UptimeScout beschreibt den Verlauf als Zeitfenster mit unterschiedlichen Intervallen, abhängig vom ausgewählten Zeitraum: Minuten- und Fünf-Minuten-Intervalle für kurze Zeiträume, Stundenintervalle für einen Tag und Tagesintervalle für längere Zeiträume. Gespeicherte ältere Aggregationen können eine gröbere Auflösung haben. Ziehen Sie deshalb nicht den Schluss, dass ein „Ausfall genau in dieser Minute“ begonnen hat, wenn eine Zeile eine Stunden- oder Tagesaggregation darstellt. Verwenden Sie den tatsächlichen Wert von resolution_seconds sowie die Felder effective_start und history_resolution in der Antwort, um die Grenzen der möglichen Aussage kenntlich zu machen.
Behandeln Sie ein fehlendes Intervall als unbekannt. Die Spezifikation fordert ausdrücklich, Lücken als unbekannte Intervalle zu prüfen: Eine leere Stelle im Verlauf bedeutet für sich genommen weder normalen Betrieb noch einen Ausfall. Diese einfache Regel verhindert im Bericht, dass Lücken fälschlich mit einem „grünen“ Status oder Nullen aufgefüllt werden.
Verlauf mit dem aktuellen Signal abgleichen
Wenn Sie den Zustand zum Zeitpunkt der Meldung prüfen möchten, rufen Sie /v1/status für dieselbe Kombination aus service und region ab. Prüfen Sie im Dienstobjekt status, observed_at und stale gemeinsam; die Dokumentation zeigt diese Felder als Möglichkeit, Zustand und Aktualität des Signals zu beurteilen. Der Status auf oberster Ebene bezieht sich auf das Ergebnis der API-Anfrage, während service.status das Verfügbarkeitssignal des jeweiligen Dienstes beschreibt. Diese Unterscheidung ist besonders in automatisierten Berichten hilfreich: Eine erfolgreiche HTTP-Antwort und der Zustand eines externen Dienstes sind zwei verschiedene Dinge.
Bei mehreren Abhängigkeiten können Sie /v1/statuses aufrufen und anschließend nur für die Dienste und Regionen mit Auffälligkeiten den Verlauf heranziehen. Die Spezifikation stellt außerdem /v1/summary und /v1/incidents bereit. Bei der Diagnose über die letzte Route sollten Sie ihre genaue Funktion berücksichtigen: Der Endpunkt gibt aktuelle erhöhte Störungssignale zurück, keine bestätigten Vorfälle des Anbieters selbst. Das Ergebnis ist daher ein Anlass zum Abgleich und keine fertige Schlussfolgerung über die Ursache.
Ergebnisse ohne Spekulation dokumentieren
Speichern Sie in der Berichtszeile die service ID, region, den Abfragezeitraum, observed_at, resolution_seconds, samples, counts und einen Hinweis auf Lücken. Fügen Sie einen Link zur Meldung oder zum internen Vorfall getrennt von den API-Feldern hinzu. Gleichen Sie anschließend den Zeitbereich mit Anwendungsprotokollen, regionalen Traces und der Nutzermeldung ab. Wenn das Aggregat einen größeren Zeitraum abdeckt als der Vorfall, formulieren Sie das Ergebnis entsprechend: Die Beobachtungen für die ausgewählte Region und den festgelegten Zeitraum enthalten bestimmte Signale, bei einer bestimmten Auflösung und Anzahl von Stichproben.
Eine solche Untersuchung hilft dem Bereitschaftsteam bei der Entscheidung, ob es die regionale Seite des externen Dienstes prüfen oder die Diagnose der eigenen Anwendung und des Netzwerks des Nutzers fortsetzen sollte. Die Reproduzierbarkeit hängt davon ab, dass Anfrageparameter und ursprüngliches JSON gespeichert werden; die Aussagekraft zeitlicher Schlussfolgerungen wiederum davon, dass Auflösung, samples und unbekannte Zeiträume ausdrücklich berücksichtigt werden. Das ist der praktische Nutzen im Verfügbarkeitsfall: nicht nur eine aktuelle Statusanzeige, sondern ein nach Region und Zeit abgegrenzter Datensatz, den Kollegen überprüfen können.