API 관측 가능성: 정의 및 구현 방법

API 관측 가능성(observability)은 API가 방출하는 원격 측정 데이터(telemetry)인 메트릭, 로그, 트레이스를 검토하여 API가 특정 방식으로 작동하는 이유를 이해하는 능력입니다. 이는 고정된 대시보드 세트를 모니터링하는 것을 넘어섭니다. 잘 계측된 API는 이미 생성된 데이터만을 사용하여 API의 내부 상태에 대해, 심지어 예상치 못했던 질문까지도 할 수 있게 해줍니다.

버튼

API 관측 가능성이 실제로 의미하는 바

이 용어는 제어 이론에서 유래했으며, 시스템의 외부 출력으로부터 내부 상태를 추론할 수 있다면 그 시스템은 관측 가능(observable)하다고 합니다. 소프트웨어에 적용하면, API의 출력(원격 측정 데이터)이 새로운 코드를 배포하여 로그 라인을 추가하지 않고도 모든 동작을 진단할 수 있을 만큼 충분한 정보를 제공할 때 API는 관측 가능하다고 할 수 있습니다.

마지막 부분이 중요합니다. 관측 가능성을 통해 고객이 특정 API 버전, 특정 지역의 사용자에게 새벽 2시에 결제 요청이 느리다고 보고할 때, 이미 수집된 데이터로부터 "왜 그런지"를 답할 수 있어야 합니다. 예측하지 못했던 장애 모드를 조사할 수 있을 만큼 풍부하게 계측해야 합니다. 이는 이미 질문할 줄 아는 것에만 답하는 업타임 확인과는 다른 목표입니다.

관측 가능성 대 모니터링

사람들은 이 두 단어를 상호 교환적으로 사용하지만, 실제로는 다른 것을 설명합니다.

모니터링은 알려진 신호를 감시하고 임계값을 넘으면 알림을 보냅니다. 무엇을 추적할지(오류율, CPU, p99 지연 시간) 그리고 무엇이 나쁜 상황으로 간주되는지를 미리 결정합니다. 모니터링은 "내가 고장 날 것으로 예상했던 것이 고장 났는가?"에 답합니다.

관측 가능성은 시스템의 속성입니다. 즉, 원격 측정 데이터가 내부 상태에 대한 임의의 질문을 얼마나 잘 할 수 있게 하는지를 나타냅니다. 이는 "이것이 왜 이런 식으로 작동하는가?"에 답하며, 심지어 "이것"이 대시보드를 구축한 적 없는 것일 때도 해당됩니다.

간단히 말해, 모니터링은 무언가 잘못되었다는 것을 알려줍니다. 관측 가능성은 그 원인을 찾는 데 도움을 줍니다. 둘 다 필요합니다. 모니터링은 알림을 제공하고, 관측 가능성은 알림에서 근본 원인까지의 경로를 제공합니다. 알림 측면에 대한 더 깊이 있는 내용은 API 모니터링 가이드에서 자세히 다룹니다.

다음 표는 이 둘의 차이점을 보여줍니다.

측면	모니터링 (Monitoring)	관측 가능성 (Observability)
답변하는 질문	알려진 신호가 범위를 벗어났는가?	시스템이 왜 이렇게 작동하는가?
정의 시점	사전 정의됨 (사전 정의된 확인)	조사 시점 (임시 쿼리)
가장 적합한 용도	알려진 장애 모드, SLO 위반	새롭고 예상치 못한 문제
출력	경고, 상태 대시보드	고차원적이고 쿼리 가능한 원격 측정 데이터

세 가지 기둥: 메트릭, 로그, 트레이스

관측 가능성은 세 가지 종류의 원격 측정 데이터, 즉 세 가지 기둥에 기반합니다. 벤더에 구애받지 않는 표준인 OpenTelemetry는 이를 원격 측정 "신호"로 공식화합니다. OpenTelemetry는 현재 트레이스, 메트릭, 로그, 배기지(baggage)를 지원하며, 이벤트와 프로파일은 개발 중입니다. 고전적인 세 가지는 첫 세 가지 신호에 해당합니다.

메트릭

메트릭은 시간에 따라 집계된 숫자 측정값입니다. API의 경우, 가장 중요한 것은 요청률(request rate), 오류율(error rate), 지연 시간 분포(latency distribution)입니다. 지연 시간은 평균뿐만 아니라 퍼센타일(p95 및 p99)로 보고해야 합니다. 평균은 실제 사용자가 느끼는 느린 꼬리 부분을 숨깁니다.

메트릭은 저장 비용이 저렴하고 쿼리가 빠르기 때문에 대시보드와 알림에 이상적입니다. 그들의 약점은 낮은 카디널리티(cardinality)에 있습니다. 즉, p99 지연 시간이 급증했다고 알려주지만, 어떤 요청이 그것을 유발했는지는 알려주지 않습니다.

로그

로그는 개별 이벤트의 타임스탬프가 찍힌 기록입니다. 일관된 필드를 가진 JSON으로 방출되는 구조화된 로그는 필터링 및 집계가 가능하므로 자유 텍스트 줄보다 훨씬 유용합니다.

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

trace_id 필드에 주목하세요. 이 ID는 로그 라인을 더 넓은 요청 흐름과 연결하며, 이는 세 번째 기둥으로 이어집니다.

트레이스

분산 트레이스는 하나의 요청이 여러 서비스를 거쳐 이동하는 과정을 추적합니다. 각 홉(hop)은 스팬(span)이 되며, 스팬들은 트레이스 ID를 공유하여 전체 경로를 재구성하고 어디에서 시간이 소요되었는지 확인할 수 있습니다. 요청이 게이트웨이, 인증 서비스 및 세 개의 마이크로 서비스를 통과할 때, 트레이스는 어떤 홉이 4초를 추가했는지 보여줍니다.

트레이스는 마이크로 서비스 디버깅을 다루기 쉽게 만듭니다. 트레이스가 없으면 체인에서 어떤 서비스가 느린지 추측해야 합니다.

세 가지 기둥은 함께 작동합니다. 메트릭 알림은 급증을 알립니다. 트레이스는 느린 서비스를 가리킵니다. 해당 서비스의 로그는 트레이스 ID로 필터링되어 정확히 무슨 일이 일어났는지 알려줍니다.

RED 방법과 골든 시그널

모든 것을 추적할 필요는 없습니다. RED 방법은 요청 기반 서비스에 대한 집중적인 시작점을 제공합니다. 톰 윌키(Tom Wilkie)는 2015년 위브웍스(Weaveworks) 재직 당시 구글의 네 가지 골든 시그널에서 파생된 이 방법을 소개했습니다.

RED는 다음을 의미합니다:

Rate (요청률): API가 처리하는 초당 요청 수.
Errors (오류): 5xx 응답 및 예상치 못한 4xx 응답과 같은 실패한 요청의 수 또는 비율.
Duration (지속 시간): p95 및 p99로 보고되는 요청 지연 시간의 분포.

Rate     = 초당 요청 수
Errors   = 5xx (및 예상치 못한 4xx) 응답의 %
Duration = 지연 시간 분포, p95 및 p99 (평균만 아님) 보고

RED는 요청 중심이며, API, 게이트웨이, 서비스 메시(service mesh)에 잘 맞습니다. 이와 대조적으로 USE(Utilization, Saturation, Errors)는 CPU 및 디스크와 같은 인프라 리소스를 대상으로 합니다. API의 경우 RED로 시작하고 그 아래 호스트에 대해 USE를 추가합니다.

SLI 및 SLO: 신호를 목표로 전환하기

관측 가능성 데이터는 목표를 부여할 때 실행 가능해집니다. 구글 SRE 책에서는 여기에서 두 가지 용어를 정의합니다.

서비스 수준 지표(SLI)는 서비스의 한 측면을 정량적으로 측정하는 것입니다. 일반적인 SLI는 요청 지연 시간, 오류율(실패한 모든 요청의 비율), 초당 요청 수 처리량입니다. 이들은 RED와 깔끔하게 일치합니다.

서비스 수준 목표(SLO)는 SLI에 대한 목표 값 또는 범위입니다. 예를 들어, "28일 동안 요청의 99.9%가 300ms 미만으로 완료되어야 한다"입니다. SLO는 API가 충분히 건강한지, 그리고 기능을 개발하는 대신 안정성에 엔지니어링 시간을 투자해야 할 시기를 알려줍니다.

SLI와 SLO는 메트릭에 의미를 부여합니다. 이들이 없으면 지연 시간 차트는 단순히 구불구불한 선에 불과하지만, 이들이 있으면 측정 가능한 계약이 됩니다.

도구: OpenTelemetry 및 백엔드

관측 가능성 도구는 원격 측정 데이터를 생성하는 방법과 어디로 보내는지 두 가지 계층으로 나눌 수 있습니다.

생성 측면에서는 OpenTelemetry가 배울 가치가 있는 표준입니다. OpenTracing과 OpenCensus를 병합하여 형성된 Cloud Native Computing Foundation(CNCF) 프로젝트입니다. 벤더 및 도구에 구애받지 않으므로 광범위한 백엔드에서 작동합니다. 핵심 원칙은 생성하는 데이터의 소유권을 가지며, 벤더 종속이 없다는 것입니다. API, 언어 SDK, 시맨틱 컨벤션, OTLP 와이어 프로토콜, 자동 계측 및 OpenTelemetry Collector를 제공합니다.

저장 및 분석을 위한 옵션은 다양합니다. Grafana와 함께 Prometheus는 메트릭 및 대시보드를 위한 일반적인 오픈 소스 스택입니다. Datadog 및 Honeycomb과 같은 상용 플랫폼은 트레이스, 메트릭, 로그를 수집하고 고차원적 쿼리를 제공합니다. Datadog를 사용하는 경우, Datadog API 상세 안내에서는 프로그래밍 방식으로 데이터를 푸시하고 풀하는 방법을 보여줍니다.

OpenTelemetry의 핵심은 한 번 계측하면 다시 계측할 필요 없이 백엔드를 전환할 수 있다는 것입니다. 이러한 이식성은 OpenTelemetry를 일찍 채택해야 하는 주요 이유입니다.

테스팅 및 합성 확인이 적합한 곳

관측 가능성은 단순히 프로덕션의 문제가 아닙니다. 가장 유용한 신호 중 일부는 배포 전후에 의도적으로 실행하는 테스트에서 나옵니다.

왼쪽으로 이동: 계약 테스트 및 CI 실행

코드가 배포되기 전에 계약 테스트(contract tests)는 API가 사양과 일치하는지 확인합니다. CI에서 이를 실행하면 사용자에게 도달하기 전에 파괴적인 변경 사항을 감지합니다. 모든 CI 테스트 실행은 신호입니다. 즉, 커밋, 환경 및 타임스탬프에 연결된 통과 또는 실패입니다. 이 기록은 릴리스 품질에 대한 관측 가능성 데이터입니다.

Apidog CLI는 파이프라인에서 테스트 시나리오를 실행합니다. Node.js를 기반으로 하며 Node v16 이상이 필요합니다.

npm install -g apidog-cli
# 설치 확인
node -v && apidog -v

환경에 대해 테스트 시나리오를 실행합니다. 환경 플래그는 필수이며, 토큰을 명시적으로 전달합니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

여기서 -t는 테스트 시나리오 ID, -e는 환경 ID, -r은 보고서 형식(cli, html, json, junit)을 설정합니다. 기본 리포터는 cli입니다. CSV 또는 JSON 파일에서 시나리오를 구동하려면 -d ./data.csv를 추가합니다(-d 또는 --iteration-data 플래그는 파일 경로를 받습니다). 보고서 개요를 Apidog 클라우드에 푸시할 수도 있습니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

복사하고 적용할 수 있는 전체 파이프라인은 CI/CD 가이드용 Apidog CLI 또는 모든 플래그에 대한 전체 CLI 참조를 참조하십시오.

프로덕션 환경에서의 합성 모니터링

합성 모니터링(synthetic monitoring)은 사용자처럼 외부에서 라이브 API에 대해 스크립트화된 요청을 주기적으로 실행합니다. 이는 실제 트래픽이 발생하기 전에 문제를 감지하고 지연 시간 및 가용성 데이터 포인트를 꾸준히 제공합니다. 기본적인 API 상태 확인은 가장 간단한 형태입니다. 전체 합성 모니터링은 로그인 후 결제와 같은 다단계 흐름으로 확장됩니다.

이러한 확인은 그 자체로 관측 가능성 신호입니다. 02:00에 4초 동안 실패한 합성 실행은 트레이스와 로그에 공급하고 싶은 바로 그런 이벤트입니다. 전용 도구에 대한 조사는 합성 테스트 도구 목록에서, 프로덕션 모니터링 플랫폼은 API 모니터링 도구 목록에서 확인할 수 있습니다.

Apidog 예약 작업을 통한 실제 신호 생성

Apidog는 예약 작업(Scheduled Tasks)을 통해 반복적인 합성 신호를 생성할 수 있습니다. 이 기능은 구성된 테스트 시나리오를 정해진 시간에 자동으로 실행하고, 결과를 캡처하며, 예약 회귀 테스트를 지원합니다. 테스트 모듈의 예약 작업에서 찾을 수 있습니다.

이에 의존하기 전에 알아야 할 몇 가지 사항이 있습니다. 예약 작업은 현재 베타 버전이므로, 오랫동안 안정된 기능이라기보다는 진화 중인 기능으로 취급해야 합니다. 또한 구성된 자체 호스팅 러너(Runner)가 필요합니다. "실행 대상(Runs On)" 옵션에는 현재 자체 호스팅 러너가 나열되어 있으며, Apidog Cloud는 곧 출시될 예정입니다. 따라서 완전히 클라우드에서 호스팅되는 예약 확인은 아직 없습니다.

설정할 때 다음을 선택합니다:

테스트 시나리오: 실행할 하나 이상의 시나리오.
실행 모드: 매주 일요일 오후 11시 또는 6시간마다와 같은 시간 주기.
알림: 모든 실행 후 또는 실패 시에만 알림.

실행 횟수는 구독 플랜에 따라 다릅니다. 실습을 위해서는 Apidog 예약 작업 상세 안내를 참조하십시오.

여기서의 가치는 루프를 닫는 것입니다. 한 곳에서 API를 설계하고 테스트한 다음, 동일한 시나리오를 주기적으로 실행하여 조치할 수 있는 통과/실패 및 지연 시간 신호를 계속 생성하도록 합니다. 신용 카드 없이 Apidog를 무료로 사용해보고 기존 테스트 시나리오를 반복되는 신호로 전환해 보세요.

관측 가능한 API를 위한 실용적인 경로

처음부터 시작하는 경우, 다음 순서로 진행하세요:

일관된 스키마와 모든 요청에 대한 트레이스 ID를 포함하는 구조화된 로그를 방출합니다.
트레이스, 메트릭, 로그가 컨텍스트를 공유하고 백엔드 간에 이식성을 유지하도록 OpenTelemetry로 계측합니다.
RED 메트릭(요청률, 오류, p95 및 p99를 포함한 지속 시간)을 추적하고 대시보드에 표시합니다.
메트릭이 단순히 추세가 아닌 목표를 가지도록 SLI 및 SLO를 정의합니다.
릴리스 전에 파괴적인 변경 사항을 감지하기 위해 CI에 계약 테스트를 추가합니다.
예를 들어 Apidog 예약 작업을 사용하여 프로덕션 환경에 대해 합성 확인을 주기적으로 실행합니다.

이 여섯 가지를 한 번에 다 할 필요는 없습니다. 첫 번째 단계인 트레이스 ID를 포함한 구조화된 로그만으로도 평면 텍스트 로그를 훨씬 뛰어넘는 발전을 이룰 수 있습니다.

자주 묻는 질문

API 관측 가능성이란 무엇인가요?

API 관측 가능성은 API가 방출하는 원격 측정 데이터, 즉 메트릭, 로그, 트레이스로부터 API의 내부 상태를 이해하는 능력입니다. 관측 가능한 API는 새로운 계측을 추가하지 않고도 예상치 못한 문제를 포함하여 특정 방식으로 작동하는 이유를 조사할 수 있게 해줍니다.

API 관측 가능성과 모니터링의 차이점은 무엇인가요?

모니터링은 미리 정의된 신호를 감시하고 임계값을 넘을 때 경고를 보내며, "내가 고장 날 것으로 예상했던 것이 고장 났는가?"에 답합니다. 관측 가능성은 시스템의 속성으로, 동작에 대한 새로운 임의의 질문을 할 수 있게 해주며, "왜 이런 일이 발생하는가?"에 답합니다. 모니터링은 무언가 잘못되었음을 알려주지만, 관측 가능성은 원인을 찾는 데 도움을 줍니다. 둘 다 필요합니다.

관측 가능성의 세 가지 기둥은 무엇인가요?

세 가지 기둥은 메트릭, 로그, 트레이스입니다. 메트릭은 요청률 및 지연 시간 퍼센타일과 같은 집계된 숫자입니다. 로그는 개별 이벤트의 타임스탬프가 찍힌 기록으로, 이상적으로는 JSON으로 구조화됩니다. 트레이스는 하나의 요청이 여러 서비스를 거쳐 이동하는 과정을 추적하여 시간이 어디에서 소요되었는지 확인할 수 있게 합니다. OpenTelemetry는 이를 원격 측정 신호로 공식화합니다.

API를 관측 가능하게 만드는 방법은 무엇인가요?

모든 요청에 트레이스 ID를 포함한 구조화된 로그를 방출하는 것으로 시작합니다. 메트릭, 로그, 트레이스가 컨텍스트를 공유하도록 OpenTelemetry로 코드를 계측합니다. RED 메트릭을 추적하고, SLI 및 SLO를 목표로 정의하며, CI에 계약 테스트를 추가하고, 프로덕션 환경에 대해 예약된 합성 확인을 실행합니다. 각 단계는 쿼리 가능한 신호를 추가합니다.

관측 가능성을 위해 OpenTelemetry가 필수인가요?

아닙니다. 관측 가능성은 어떤 원격 측정 도구로든 달성할 수 있는 속성이며, OpenTelemetry가 존재하기 훨씬 전부터 많은 팀이 독점 에이전트를 사용했습니다. 그렇지만 OpenTelemetry는 벤더에 구애받지 않는 CNCF 표준이므로, 이를 채택하면 한 번 계측하여 Prometheus, Datadog, Honeycomb과 같은 백엔드를 다시 계측할 필요 없이 전환할 수 있습니다. 이는 필수 사항이 아니라 강력한 기본값입니다.