API 모니터링: 검사, 어설션 및 사용자 여정

접근성만이 아니라 API를 모니터링하세요. 예상 응답을 확인하고, 성능 저하를 찾아 계약이 깨지면 적절한 사람에게 알립니다.

적절한 모니터 선택

간단한 엔드포인트와 상태 코드 검사에는 HTTP를 사용하세요. 요청에 메서드, 본문, 헤더, 인증 또는 응답 어설션이 필요하면 API를 사용하세요. 로그인, 탐색, 결제처럼 여러 사용자 단계에 성공이 좌우되면 Browser를 사용하세요. 시스템의 호출 자체가 백그라운드 작업 완료의 가장 좋은 증거라면 Heartbeat를 사용하세요.

의미 있는 어설션 구성

안정적인 상태 또는 준비 엔드포인트 하나로 시작하세요. 특정 상태 코드와, 필요하다면 의존성이 준비되었음을 증명하는 작은 응답 본문 값을 기대하세요. 자격 증명은 모니터 구성에 시크릿으로 저장하고 공개 문서, 상태 페이지 또는 클라이언트 코드에 프로덕션 자격 증명을 넣지 마세요.

HTTP/API 어설션 예시

GET https://api.example.com/health
Expected status: 200
Expected body: {"ok":true}

응답 본문 어설션

상태 코드는 서버가 응답했다는 것만 알려 줍니다. 키워드 검사는 반환된 내용을 검증합니다. 줄마다 하나의 어설션을 입력하면 모든 줄이 일치해야 하므로 여러 줄은 OR가 아닌 AND로 동작합니다. 정규식 일치를 사용하면 각 줄을 RE2 패턴으로 처리해 변경되는 값을 검사할 수 있습니다. 키워드 부재 옵션은 전체 검사를 반전하여 텍스트나 패턴을 찾으면 실패하게 합니다. RE2는 lookahead, lookbehind, backreference를 지원하지 않으며 응답의 처음 1MB만 검색합니다.

리터럴 및 정규식 키워드 어설션

# Literal: every line must appear in the body
"status":"ok"

# Regular expression (RE2): every line must match
"status"\s*:\s*"(ok|healthy)"
"version":"4\.[0-9]+"

엔드포인트만으로 부족할 때

API가 200을 반환해도 고객이 보는 흐름은 실패할 수 있습니다. Browser 모니터링은 사람이 앱에서 거치는 여정을 검증합니다. 큐, cron 작업, 백업, 배포 파이프라인에는 완료를 확인하므로 단순 가용성보다 예약 heartbeat가 더 신뢰할 수 있는 신호인 경우가 많습니다.

실패에 의도적으로 대응

팀이 실제로 확인하는 알림 채널로 인시던트를 보내고, 자동화해도 안전한 작업에 트리거를 추가하세요. 시끄러운 검사와 고객 영향 검사를 분리해 각 실패에 명확한 담당자와 알림 경로를 두세요.