API 모니터링이란? 가용성, 응답 시간, 응답 검증
API 모니터링에서 무엇을 측정하는지, 인증이 필요한 HTTP 응답을 어떻게 검증하는지, 메트릭과 로그 및 트레이스로 장애를 어떻게 조사하는지 설명합니다.
재고 API가 200 OK를 반환해도 응답의 stock 값이 null이면 숫자를 기대한 주문 서비스는 결제를 진행할 수 없습니다. 재고가 0인 경우는 다릅니다. 주문 서비스는 정상 응답을 받아 사용자에게 품절을 안내할 수 있습니다.
API 모니터링은 엔드포인트가 호출 측의 기대대로 응답하는지 살피는 일입니다. 정기 테스트는 실제 요청이 뜸한 시간에도 같은 조건으로 API를 호출합니다. 운영 메트릭, 로그, 트레이스는 서비스에 들어온 실제 요청을 보여 줍니다. 테스트 상품의 재고 조회가 성공하더라도 특정 창고를 조회하는 운영 요청에서만 타임아웃이 발생할 수 있습니다.
어떤 응답을 성공으로 볼지 정한다
인증이 필요한 GET /v1/inventory/SKU-42로 테스트 상품의 재고를 조회한다고 가정해 보겠습니다. HTTP 200을 받고 stock이 0 이상의 정수인지 확인합니다. 응답 시간 기준은 호출 서비스가 실제로 기다릴 수 있는 시간에 맞춥니다.
| 테스트 결과 | 알 수 있는 것 |
|---|---|
목표 시간 안에 HTTP 200과 {"stock":0} 수신 |
정상 응답을 받았으며 해당 상품은 품절이다 |
HTTP 200과 {"stock":null} 수신 |
서버는 응답했지만 호출 서비스가 기대하는 응답 형식을 지키지 않았다 |
| 인증을 포함한 테스트 요청에 HTTP 401 반환 | 테스트 자격 증명과 인증 경로를 점검해야 한다 |
| 제한 시간 안에 응답을 받지 못함 | 테스트가 타임아웃됐다. 네트워크 경로와 서버 측 데이터를 비교해 원인을 좁힌다 |
주문 서비스가 재고 API에 2초만 할애한다면 3초 뒤에 도착한 응답은 내용이 맞아도 쓸 수 없습니다. 느린 응답, 타임아웃, 상태 코드 오류, 응답 내용 불일치를 나눠 기록하면 어떤 문제가 늘었는지 보기 쉽습니다. 운영에서는 엔드포인트나 작업별로 요청 수, 오류율, P95와 P99 같은 상위 백분위 응답 시간을 확인합니다. 정기 테스트에서 얻은 응답 시간은 해당 노드와 입력값을 기준으로 한 결과입니다. Google SRE의 네 가지 핵심 신호(영어)
실제 호출 경로와 가까운 곳에서 확인한다
HTTP 테스트는 실행 노드에서 엔드포인트의 동작을 보는 블랙박스 모니터링입니다. 거래처가 사용하는 공개 API는 거래처와 비슷한 경로에서 점검합니다. 사내 재고 서비스라면 내부 DNS를 조회하고 대상에 접속할 수 있는 네트워크에 노드를 둡니다. 게이트웨이를 통과하는 외부 테스트와 서비스에 직접 접속하는 내부 테스트를 따로 보면 문제가 생긴 구간을 좁히기 쉽습니다. 합성 모니터링과 실행 위치
결제나 문자 발송처럼 외부 API를 확인하려면 제공업체가 테스트를 허용하는지 확인하고 승인된 엔드포인트나 계정을 사용합니다. 샌드박스 결과는 샌드박스에서 관찰한 동작입니다. 운영 장애를 조사할 때는 애플리케이션에서 외부 API를 호출한 기록도 함께 봅니다. 그래야 인증 실패, 호출량 제한, 네트워크 타임아웃, 제공업체가 반환한 오류를 구분할 수 있습니다. 한 노드에서 실패했다면 우선 그 노드에서 확인한 현상으로 해석합니다.
인증이 필요한 읽기부터 시작한다
테스트에 필요한 최소 권한만 가진 전용 자격 증명을 사용합니다. Guance HTTP 테스트에서는 API 요구 사항에 맞춰 헤더, HTTP 인증 정보 또는 클라이언트 인증서를 설정할 수 있습니다. stock처럼 JSON을 파싱한 뒤 필드 값을 검사해야 한다면 Pipeline 스크립트 모드를 사용합니다. 응답에 민감한 데이터가 포함될 수 있다면 개인정보 보호 설정에서 본문을 저장하지 않도록 할 수 있습니다. 알림에는 자격 증명과 응답 원문을 넣지 않습니다.
인증 정보를 뺀 요청으로 401 Unauthorized를, 허용되지 않은 메서드로 405 Method Not Allowed를 확인할 수도 있습니다. 두 테스트는 요청을 거부하는 경로를 확인하므로 인증에 성공했을 때의 동작을 검증하는 테스트와 분리합니다. 수명이 짧은 토큰이 필요하면 승인된 방식으로 갱신합니다. 한 HTTP 응답에서 얻은 값을 다음 요청에 전달하는 방식이라면 Guance 다단계 API 테스트로 해당 흐름을 구성할 수 있습니다.
쓰기 동작을 확인해야 한다면 격리된 환경에서 전용 데이터를 사용합니다. 테스트에서는 타임아웃이 발생해도 서버에서는 레코드 생성이나 후속 처리가 끝날 수 있습니다. 이런 경우에도 테스트 데이터를 찾아서 정리할 수 있도록 설계하고, API가 멱등성이나 중복 방지를 보장하는 범위에서만 쓰기를 재시도합니다. HTTP 메서드 및 상태 코드 명세(영어)
테스트 실패를 운영 요청과 함께 본다
Guance 설정 화면의 연결 테스트는 선택한 노드와 별개로 실행됩니다. 스케줄을 설정한 뒤에는 실제 선택한 노드에서 실행된 결과를 확인한 다음 이상 감지와 복구 조건을 설정합니다. 알림에는 엔드포인트, 실행 노드, 발생 시각, 실패한 조건을 담습니다. 여러 번 실패해야 알리도록 하면 일시적인 변동을 걸러 낼 수 있지만 감지까지 더 오래 걸립니다.
배포 직후 재고 테스트에서 stock: null이 반환되기 시작했다면 같은 시간대의 재고 API 오류와 응답 시간을 확인합니다. Guance APM에서는 계측을 적용한 서비스의 트레이스와 연관 로그를 확인할 수 있습니다. 테스트 요청에 식별자를 넣고 서비스에서도 기록한다면 해당 요청을 찾아볼 수 있습니다. 식별자가 없다면 엔드포인트, 시간대, 환경으로 범위를 좁힙니다. 게이트웨이 등에서 요청이 끊겨 계측 대상 서비스에 도달하지 않으면 그 서비스의 트레이스에는 나타나지 않습니다.
정기 테스트의 성공률은 집계 대상 중 설정한 조건을 충족한 비율입니다. 사용자 대상 SLO에는 운영 요청 가운데 집계 요건을 충족하는 요청의 성공 비율을 쓸 수 있습니다. 두 비율을 따로 봐야 테스트 상품의 조회는 정상인데 일부 운영 요청에서만 문제가 발생하는 상황을 놓치지 않습니다. 업타임 모니터링과 가용성
