ある国のユーザーから問題が報告されている一方で、チーム側ではサービスが通常どおり稼働しているように見えるときは、ユーザーの地域における観測結果を確認するのが有効です。UptimeScout APIでは、地域コードを指定して選択したサービスの履歴を取得でき、時間帯ごとのデータと測定数が返されます。出力されるのは、問い合わせの調査に使える検証可能な表です。各時間帯の時刻、解像度、シグナルの内訳、サンプル数を確認できます。

ここで扱う実践的なシナリオは、地域的な障害の疑いを調査することです。入力するのは、UptimeScoutのカタログにあるサービスID、USやGBなどの地域コード、そして履歴の対象期間です。結果を使うと、ユーザーから報告された時刻とサービスの観測結果を照合できます。APIが示すのは観測された可用性のシグナルです。サービスのチェックは問題の切り分けに役立ちますが、アプリケーション自体のチェックに代わるものではありません。
まずサービスと地域を確認する
カタログから始めましょう。名前または検索語で目的のサービスを探し、正確なIDを記録します。UptimeScout OpenAPI仕様には、GET /v1/servicesによる検索と、q、service、region、limit、offsetの各パラメーターが記載されています。調査レポートでは、表示名だけでなくIDを保存するのがおすすめです。そうすれば、後から同じカタログ項目に対して再度リクエストできます。
地域は独立した2文字のコードで指定します。結果と一緒に地域コードを保存することが重要です。USを指定した応答と、地域フィルターを指定しない応答では、答えられる問いが異なります。説明文をロシア語で表示する必要がある場合、lang=ruは説明文のローカライズを制御し、regionは観測対象を選択します。ドキュメントでは、この2つの用途が明確に区別されています。
単一のステータスではなく履歴を取得する
インシデントの調査には、必須パラメーターserviceと選択したregionを指定して、/v1/historyを使います。hoursパラメーターで履歴の対象期間を指定でき、仕様上は1〜2160時間の値を設定できます。リクエストにはlangも指定できます。OpenAPI仕様によると、認証にはBearer方式でライセンスを渡します。実際の運用では、キーを環境変数に保存し、リクエストログに記録しないようにしてください。
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)
これは最小限のリクエスト例であり、実際の調査結果を公開したものではありません。githubというIDとGBという地域は例として示したパラメーターです。実際に使う際は、調査対象に応じてサービスと地域を選んでください。応答全体をJSONで保存し、取得時刻とリクエストの説明をシステム内の別フィールドに記録しておくと便利です。そうすれば調査を再現し、どのデータスナップショットを使ったか確認できます。
解像度と欠損も結果の一部
history配列では、observed_at、resolution_seconds、aggregated、samples、countsの各フィールドが重要です。解像度は時間間隔の長さを示し、samplesは集計に含まれた観測数、countsはシグナルの内訳を示します。これらをまとめて確認してください。samplesが少ない1行と、より多くの観測を含む集計行では、分析上の重みが異なります。

UptimeScoutの説明によると、履歴は選択した期間に応じて異なる間隔の時間枠で構成されます。短期間では1分または5分間隔、1日では1時間間隔、長期間では1日間隔です。保存済みの古い集計データでは、解像度がより粗い場合があります。そのため、行が1時間または1日の集計を表しているのに、「障害はこの分に始まった」と結論づけないでください。実際のresolution_secondsの値と、応答内のeffective_startおよびhistory_resolutionフィールドを使い、判断できる範囲を明示しましょう。
欠損している時間帯は不明として扱います。仕様では、欠損を不明な時間帯として確認するよう明記されています。履歴の空白部分は、それだけでは正常稼働も障害も意味しません。レポートでこのルールを守れば、欠損を「正常」ステータスやゼロ値で誤って埋めることを防げます。
履歴と現在のシグナルを照合する
問い合わせがあった時点の状態を確認するには、同じserviceとregionを指定して/v1/statusをリクエストします。サービスオブジェクトでは、status、observed_at、staleを合わせて確認してください。ドキュメントでは、これらのフィールドを状態とシグナルの鮮度を把握する方法として示しています。最上位のstatusはAPIリクエストの結果を表し、service.statusは特定サービスの可用性シグナルを表します。この違いは自動レポートで特に重要です。HTTPリクエストの成功と外部サービスの状態は、別のものです。
複数の依存先を確認する場合は/v1/statusesを使い、その後、異常が見られたサービスと地域に絞って履歴を取得できます。仕様には/v1/summaryと/v1/incidentsも用意されています。後者を使って調査する際は、その役割を正確に理解してください。このエンドポイントが返すのは、最近の異常シグナルであり、サービス提供者が確認したインシデントではありません。そのため、結果は照合のきっかけとして扱い、原因が確定した結論とみなさないでください。
推測を交えずに結論をまとめる
レポートの各行には、service ID、region、リクエスト期間、observed_at、resolution_seconds、samples、counts、欠損の有無を保存します。問い合わせや社内インシデントへのリンクは、APIのフィールドとは分けて追加してください。そのうえで、時間範囲をアプリケーションログ、地域別トレース、ユーザーの報告と照合します。集計の時間幅がインシデントより広い場合は、それに応じた表現にします。たとえば、指定した時間枠と地域の観測には、指定の解像度とサンプル数で、特定のシグナルが含まれていたと記します。
この調査により、当番担当者は次の方針を判断しやすくなります。外部サービスの地域側を確認するか、ユーザー自身のアプリケーションやネットワークの診断を続けるかです。調査を再現できるかどうかは、リクエストのパラメーターと元のJSONを保存しているかに左右されます。また、時間に関する結論の精度は、解像度、samples、不明な時間帯を明示的に考慮しているかで決まります。可用性の調査における実践的な成果は、単なる現在のステータス表示ではありません。地域と時間の範囲が明確で、同僚が再検証できる記録です。