한 국가의 사용자들이 문제를 보고하지만 팀에서는 서비스가 정상적으로 작동하는 것으로 보일 때, 해당 지역의 관측 기록을 확인하는 것이 가장 유용합니다. UptimeScout API를 사용하면 선택한 서비스의 기록을 지역 코드로 요청하고 시간 구간과 측정 횟수를 확인할 수 있습니다. 그 결과 문의를 검토할 때 확인할 수 있는 표를 만들 수 있으며, 여기에는 시간 구간, 해상도, 신호 분포, 샘플 수가 포함됩니다.

여기서 다루는 실전 시나리오는 지역 장애로 의심되는 문제를 진단하는 것입니다. 입력값은 UptimeScout 카탈로그의 서비스 ID, US나 GB 같은 지역 코드, 그리고 기록 조회 기간입니다. 결과를 통해 사용자가 문제를 보고한 시각과 서비스 관측 기록을 비교할 수 있습니다. API는 데이터를 관측된 가용성 신호로 설명합니다. 서비스 상태 확인은 문제를 좁히는 데 유용하지만, 애플리케이션 자체의 점검을 대신하지는 않습니다.
먼저 서비스와 지역을 확인하세요
카탈로그에서 시작하세요. 이름이나 검색어로 필요한 서비스를 찾은 다음 정확한 ID를 기록합니다. UptimeScout OpenAPI 사양은 GET /v1/services 검색과 q, service, region, limit, offset 매개변수를 설명합니다. 진단 보고서에는 표시 이름만이 아니라 ID를 저장하는 편이 좋습니다. 그래야 후속 요청에서도 같은 카탈로그 항목을 지정할 수 있습니다.
지역은 별도의 두 글자 코드로 지정합니다. 결과와 함께 지역 코드도 저장해야 합니다. US로 필터링한 응답과 지역 필터가 없는 응답은 서로 다른 질문에 답하기 때문입니다. 설명을 러시아어로 표시하려면 lang=ru 매개변수를 사용하고, 관측 지역을 선택하려면 region 매개변수를 사용합니다. 문서는 이 두 매개변수의 용도를 명확히 구분합니다.
단일 상태 대신 기록을 요청하세요
장애를 분석할 때는 필수 매개변수 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가 적은 행 하나는 관측 수가 많은 집계와 분석상 의미가 다릅니다.

UptimeScout는 선택한 기간에 따라 시간 간격이 달라지는 시간 슬롯으로 기록을 설명합니다. 짧은 기간에는 1분 및 5분 간격, 하루에는 시간 단위, 더 긴 기간에는 일 단위로 표시됩니다. 저장된 과거 집계는 해상도가 더 거칠 수 있습니다. 따라서 한 행이 시간 단위나 일 단위 집계라면 “장애가 정확히 이 분에 시작됐다”고 결론 내리지 마세요. 응답의 실제 resolution_seconds 값과 effective_start, history_resolution 필드를 사용해 가능한 판단의 경계를 표시하세요.
누락된 구간은 알 수 없는 상태로 취급하세요. 사양은 누락 구간을 미확인 구간으로 확인하라고 명시합니다. 기록의 빈 부분 자체는 정상 작동도 장애도 나타내지 않습니다. 이 간단한 원칙을 보고서에 적용하면 누락을 임의로 ‘정상’ 상태나 0으로 채우는 오류를 막을 수 있습니다.
기록을 현재 신호와 대조하세요
문의가 접수된 시점의 상태를 확인해야 한다면 동일한 service와 region으로 /v1/status를 요청하세요. 서비스 객체의 status, observed_at, stale을 함께 살펴보세요. 문서는 이 필드들을 상태와 신호의 최신성을 파악하는 방법으로 제시합니다. 최상위 상태는 API 요청 결과를 나타내지만, service.status는 특정 서비스의 가용성 신호를 설명합니다. 이 구분은 자동 보고서에서 특히 유용합니다. 성공한 HTTP 응답과 외부 서비스의 상태는 서로 다른 개념입니다.
여러 종속 서비스를 확인하려면 /v1/statuses를 사용한 다음 이상 징후가 나타난 서비스와 지역에 대해서만 기록을 조회할 수 있습니다. 사양에는 /v1/summary와 /v1/incidents도 있습니다. 마지막 경로를 진단에 사용할 때는 그 정확한 역할을 고려하세요. 이 엔드포인트는 공급자가 확인한 장애가 아니라 최근의 이상 신호를 반환합니다. 그러므로 결과는 대조 확인의 계기로 삼아야 하며, 원인에 대한 확정적인 결론으로 보아서는 안 됩니다.
추측 없이 결론을 기록하는 방법
보고서의 각 행에 service ID, region, 요청 기간, observed_at, resolution_seconds, samples, counts, 누락 구간 여부를 저장하세요. API 필드와는 별도로 문의나 내부 장애 기록의 링크를 추가합니다. 그런 다음 시간 범위를 애플리케이션 로그, 지역별 추적 정보, 사용자 보고와 비교하세요. 집계의 시간 범위가 장애 시간보다 넓다면 그에 맞춰 결과를 표현해야 합니다. 예를 들어 지정한 기간과 지역의 관측 기록에는 특정 해상도와 샘플 수로 이런 신호가 포함되어 있다고 설명할 수 있습니다.
이런 분석은 당직 담당자가 외부 서비스의 지역별 문제를 점검할지, 아니면 사용자 측 네트워크와 자체 애플리케이션 진단을 이어갈지 결정하는 데 도움이 됩니다. 재현 가능성을 확보하려면 요청 매개변수와 원본 JSON을 보존해야 하며, 시간에 관한 결론의 품질을 높이려면 해상도, samples, 확인할 수 없는 구간을 명시적으로 고려해야 합니다. 가용성 사례에서 얻는 실질적인 결과는 단순한 현재 상태 표시가 아닙니다. 지역과 시간 범위를 한정해 동료가 다시 검증할 수 있는 기록입니다.