UptimeScout incidents 응답만으로 서비스에 장애가 발생했다고 즉시 선언할 수 있을까요? 아닙니다. 이 엔드포인트는 최근 이상 신호가 높아진 서비스를 나열하며, 사양에는 이것이 제공업체가 확인한 인시던트가 아니라고 명시되어 있습니다. 실무적으로 얻는 것은 확인이 필요한 짧은 신호 목록이지, 장애 원인에 대한 확정적 결론이 아닙니다.

이 구분은 당직 엔지니어와 분석가에게 유용합니다. 자동 알림은 “지역 Y의 서비스 X를 확인하세요”라고 알리면서도, 사실 확인과 원인 설명은 제공업체의 공식 상태 정보나 자체 진단에 맡길 수 있습니다. UptimeScout 사양에는 신호, 현재 상태, 관측 이력을 위한 별도 경로가 문서화되어 있습니다.
신호 목록이 실제로 반환하는 것
/v1/incidents는 이상 신호가 높아진 서비스 카탈로그를 조회하는 GET 엔드포인트입니다. 매개변수로 서비스, 지역, 카테고리, 검색어, 시간 범위를 필터링할 수 있습니다. 응답을 받으려면 라이선스가 필요하며, API는 Bearer 토큰 인증을 설명합니다. 지역 필드에는 두 글자 코드를 사용하고, hours는 1~2160시간의 범위를 지정합니다.
경로에 있는 “incident”라는 단어를 “확인된 장애”로 해석하기 쉽지만, 문서에서는 그 의미를 더 좁게 정의합니다. 즉, 최근 관측 신호입니다. 따라서 알림은 응답에 근거해 “가용성 저하 신호가 감지됨”처럼 작성하고, 서비스 제공업체가 인시던트를 인정했다고 단정하지 않아야 합니다.
알림 전에 수행할 최소 확인
먼저 원본 응답과 수신 시각, 요청 매개변수를 함께 저장합니다. 그런 다음 반환된 서비스와 지역을 확인하고, 서비스의 observed_at 및 stale 필드로 데이터의 최신성을 평가합니다. 관측이 오래된 것으로 표시되면 현재 신호처럼 보여 주지 말고 별도로 구분해야 합니다.
curl -sS 'https://api.uptimescout.com/v1/incidents?region=US&hours=24' \
-H "Authorization: Bearer $UPTIMESCOUT_LICENSE_KEY"
다음은 미국을 대상으로 24시간 범위를 요청하는 예시입니다. 키는 환경 변수에서 읽으므로 명령줄에 출력되지 않습니다. 응답을 받은 뒤 HTTP 오류와 JSON 구조를 확인하고, 반환된 서비스를 각각 처리합니다. 스키마에 포함된 상태 값은 operational, degraded, outage, unknown입니다. 필드나 값이 없으면 자체 해석을 대신 넣지 마세요.
조치가 필요한 신호라면 /v1/status를 통해 해당 서비스의 현재 상태를 조회하고, /v1/history로 이력을 확인하세요. 이력에서 resolution_seconds, samples, counts, effective_start를 시계열 데이터와 함께 저장하면 분석가는 데이터가 어느 시간 단위로 수집됐고 실제로 어떤 구간에 대해 제공되는지 확인할 수 있습니다. 사양은 누락된 구간의 상태를 알 수 없다고 경고합니다. 빈 구간을 자동으로 정상 상태나 장애로 간주해서는 안 됩니다.
응답을 검증 가능한 보고서로 만드는 방법
각 기록에 서비스 ID와 이름, 요청 지역, 상태, 관측 시각, 오래된 데이터 여부, 응답 수신 시각, 그리고 팀이 확인한 경우 공식 상태 정보의 링크를 기록하세요. 마지막 필드는 통합 시스템이나 담당자가 채웁니다. UptimeScout 사양은 신호에 확인된 원인이나 제공업체의 발표가 포함된다고 보장하지 않습니다.

업무 흐름을 세 단계로 나누세요. “신호 수신”은 /v1/incidents 결과에 기록이 포함되었다는 뜻입니다. “상태 확인 중”은 현재 상태와 이력을 조회하고 있다는 뜻입니다. “확인됨”은 외부의 공식 발표나 내부 검증으로 뒷받침되는 결론에만 사용하세요. 이렇게 간단히 구분하면 대시보드가 집계된 신호를 확정된 사실처럼 보여 주는 일을 막을 수 있습니다.
여러 지역에 대한 보고서를 작성한다면 필요한 지역 코드별로 별도 요청을 수행하고, 매개변수를 결과와 함께 저장하세요. lang 필드는 서비스 설명의 언어를 지정하며 관측 지역을 바꾸지 않습니다. 현지화된 카탈로그와 지역별 상태를 비교할 때 이 둘을 구분하는 것이 중요합니다.
결론의 범위
이 시나리오에서 검증 가능한 결과는 시각, 지역, 최신성 표시가 명확한 신호 기록에 상태 및 이력의 별도 확인 결과를 더한 것입니다. 이를 통해 무엇에 주의를 기울여야 하는지, 선택한 출처를 통해 무엇을 확인했는지 파악할 수 있습니다. /v1/incidents 응답 자체는 관측 신호가 높아졌다는 사실을 알릴 뿐입니다. 확인된 장애라고 선언하려면 이를 뒷받침하는 데이터가 필요합니다.