Files
lolympus-tournament-support/docs/operations/api-performance-runbook.md

9.7 KiB

API Performance Observability Runbook

이 문서는 API p95 latency, Mongoose query count, returned document count, hydrated document count를 기준으로 전체 API 성능 리포트를 생성하는 운영 절차를 정리한다.

목적

  • 특정 top 10 API만 보는 것이 아니라, controller에 정의된 모든 API를 대상으로 리포트를 만든다.
  • 운영 New Relic 실측 Transaction duration 데이터를 우선 활용한다.
  • ApiRequestPerformance custom event가 쌓인 환경에서는 Mongoose document 반환량까지 함께 분석한다.
  • 로컬/staging 리허설에서는 NDJSON 파일로 동일한 리포트를 만든다.

데이터 소스

Source 명령 옵션 용도 포함 지표
Local NDJSON --source=local staging/local 재현 테스트 latency, query count, Mongoose duration, docs returned, hydrated docs
New Relic custom event --source=newrelic-custom 운영/staging 상세 실측 분석 latency, query count, Mongoose duration, docs returned, hydrated docs
New Relic Transaction --source=newrelic-transaction 기존 New Relic latency 확인 latency, error rate

환경변수

API 서버 계측

환경변수 기본값 설명
API_PERF_OBSERVABILITY_ENABLED false API/Mongoose 성능 계측 전체 활성화
API_PERF_LOCAL_EVENTS_ENABLED API_PERF_OBSERVABILITY_ENABLED 값 로컬 NDJSON 파일 기록 여부
API_PERF_LOCAL_EVENT_FILE /tmp/lolympus-api-performance.ndjson 로컬 이벤트 파일 경로
API_PERF_NEW_RELIC_REQUEST_EVENTS_ENABLED API_PERF_OBSERVABILITY_ENABLED 값 ApiRequestPerformance custom event 기록 여부
API_PERF_NEW_RELIC_QUERY_EVENTS_ENABLED false query별 MongooseQueryPerformance custom event 기록 여부

API_PERF_NEW_RELIC_QUERY_EVENTS_ENABLED는 이벤트 수가 많을 수 있으므로 기본값을 false로 유지한다. request 단위 지표만으로도 route별 문서 반환량은 확인할 수 있다.

New Relic 리포트 조회

환경변수 설명
NEW_RELIC_ACCOUNT_ID New Relic account id
NEW_RELIC_USER_API_KEY 또는 NEW_RELIC_API_KEY NerdGraph 조회용 API key
NEW_RELIC_APP_NAME API app name. 기본값은 lolympus

기본 운영 흐름

1. 전체 API 목록 확인

pnpm --filter api perf:routes

이 명령은 *.controller.ts 파일을 읽어 전체 route manifest를 출력한다. 리포트는 이 manifest를 기준으로 모든 API를 출력한다. 트래픽이 없었던 API는 no-samples로 표시된다.

2. New Relic Transaction 기반 전체 latency 리포트

NEW_RELIC_ACCOUNT_ID=... \
NEW_RELIC_USER_API_KEY=... \
NEW_RELIC_APP_NAME=lolympus \
pnpm --filter api perf:report -- --source=newrelic-transaction --since="1 day ago"

이미 New Relic에 쌓인 Transaction duration을 사용한다. 가장 먼저 실행해 전체 API의 p95/p99 latency와 error rate를 확인한다.

제한사항:

  • Mongoose docs returned, hydrated docs returned는 나오지 않는다.
  • 이번 계측 배포 이후에는 transaction name이 METHOD /route-template 형태로 잡혀 route별 집계 정확도가 올라간다.

3. New Relic custom event 기반 상세 리포트

API 서버가 아래 환경변수로 실행된 뒤 트래픽이 쌓여야 한다.

API_PERF_OBSERVABILITY_ENABLED=true
API_PERF_NEW_RELIC_REQUEST_EVENTS_ENABLED=true

중요: custom event는 소급 생성되지 않는다. 계측 코드가 배포되고 위 환경변수로 서버가 재시작된 이후의 요청부터 ApiRequestPerformance가 쌓인다. 기존 New Relic Transaction 데이터가 있어도 custom event 리포트는 0건일 수 있다.

리포트 생성:

NEW_RELIC_ACCOUNT_ID=... \
NEW_RELIC_USER_API_KEY=... \
NEW_RELIC_APP_NAME=lolympus \
pnpm --filter api perf:report -- --source=newrelic-custom --since="1 day ago"

이 리포트는 route별로 다음 지표를 포함한다.

  • samples
  • avgMs, p50Ms, p95Ms, p99Ms, maxMs
  • errorRatePercentage
  • queryCountP95
  • mongooseDurationP95Ms
  • docsReturnedP95
  • hydratedDocsReturnedP95

4. Local NDJSON 기반 재현 테스트

staging/local API 서버를 계측 모드로 실행한다.

API_PERF_OBSERVABILITY_ENABLED=true \
API_PERF_LOCAL_EVENTS_ENABLED=true \
API_PERF_LOCAL_EVENT_FILE=/tmp/lolympus-api-performance.ndjson \
pnpm --filter api start:staging

브라우저, curl, Postman, k6 등으로 테스트 대상 API를 호출한다. 호출하지 않은 API는 리포트에서 no-samples로 남는다.

리포트 생성:

pnpm --filter api perf:report -- \
  --source=local \
  --input=/tmp/lolympus-api-performance.ndjson

JSON 출력:

pnpm --filter api perf:report -- \
  --source=local \
  --input=/tmp/lolympus-api-performance.ndjson \
  --format=json

파일 저장:

pnpm --filter api perf:report -- \
  --source=local \
  --input=/tmp/lolympus-api-performance.ndjson \
  --output=/tmp/api-performance-report.md

예산값 조정

기본 기준:

  • p95 latency budget: 300ms
  • docs returned p95 budget: 500
  • hydrated docs returned p95 budget: 0

명령에서 덮어쓸 수 있다.

pnpm --filter api perf:report -- \
  --source=newrelic-custom \
  --since="1 day ago" \
  --p95-budget-ms=500 \
  --docs-returned-p95-budget=300 \
  --hydrated-docs-returned-p95-budget=0

리포트 해석

Status 의미 다음 작업
ok 현재 budget 안에 있음 유지 관찰
slow p95 latency가 budget 초과 New Relic trace, Mongoose duration, 외부 호출 확인
document-heavy docs returned 또는 hydrated docs returned가 budget 초과 .lean(), .select(), pagination, aggregation/materialized view 검토
no-samples route manifest에는 있으나 측정 기간에 호출 샘플 없음 테스트 커버리지/운영 트래픽 여부 확인

document-heavy가 뜨는 API는 latency가 아직 괜찮아도 우선 조사 대상이다. 데이터가 늘어나면 p95 latency가 악화될 가능성이 높다.

권장 분석 순서

  1. newrelic-transaction으로 전체 route의 p95/p99 latency를 확인한다.
  2. newrelic-custom으로 slow 또는 document-heavy route를 확인한다.
  3. docsReturnedP95가 크면 projection, pagination, aggregate result 축소를 본다.
  4. hydratedDocsReturnedP95가 0보다 크면 읽기 전용 경로에 .lean() 적용을 검토한다.
  5. queryCountP95가 크면 N+1 query 또는 반복 조회를 찾는다.
  6. mongooseDurationP95Ms가 낮은데 p95Ms만 높으면 외부 API, CPU work, serialization, payload size를 본다.

전체 API 테스트 체크리스트

  • pnpm --filter api perf:routes로 route 목록을 확인했다.
  • 주요 화면/운영 기능을 실제로 한 번 이상 호출했다.
  • 리포트의 no-samples route를 확인했다.
  • intentionally unused/admin-only API와 테스트 누락 API를 구분했다.
  • slow route의 New Relic trace를 확인했다.
  • document-heavy route의 Mongoose 반환량과 hydration 여부를 확인했다.
  • 개선 전 리포트를 저장했다.
  • 개선 후 같은 window/traffic 조건으로 리포트를 다시 생성했다.

운영 주의사항

  • 계측은 기본 비활성화다. 운영에서 켤 때는 배포 환경변수로 명시한다.
  • request body, auth header, cookie, raw Mongo filter/result는 기록하지 않는다.
  • query별 custom event는 cardinality와 event volume이 커질 수 있어 필요할 때만 켠다.
  • local NDJSON 파일은 장시간 부하 테스트 시 커질 수 있다. 테스트 전 파일을 지우거나 새 경로를 사용한다.
  • New Relic custom event 기반 리포트는 계측 활성화 이후 쌓인 데이터만 포함한다.
  • Transaction 기반 리포트는 기존 실측 latency를 볼 수 있지만 Mongoose 문서 반환량은 포함하지 않는다.

문제 해결

리포트가 전부 no-samples로 나온다

  • local source라면 --input 경로가 API_PERF_LOCAL_EVENT_FILE과 같은지 확인한다.
  • API 서버가 API_PERF_OBSERVABILITY_ENABLED=true로 실행됐는지 확인한다.
  • API를 실제로 호출했는지 확인한다.
  • New Relic source라면 --since window 안에 데이터가 있는지 확인한다.
  • newrelic-custom source라면 계측 배포/환경변수 활성화 이후의 요청인지 확인한다.

New Relic에서 custom event 존재 여부를 먼저 확인한다.

FROM ApiRequestPerformance SELECT count(*) SINCE 1 day ago

app name 필터까지 확인한다.

FROM ApiRequestPerformance
SELECT count(*)
WHERE appName = 'lolympus'
SINCE 1 day ago

위 값이 0이면 pnpm --filter api perf:report -- --source=newrelic-custom도 전부 no-samples가 맞다. 이 경우 historical latency는 newrelic-transaction source로 보고, 상세 Mongoose 지표는 계측 활성화 후 다시 수집한다.

New Relic 조회가 실패한다

  • NEW_RELIC_ACCOUNT_ID가 숫자인지 확인한다.
  • NEW_RELIC_USER_API_KEY 또는 NEW_RELIC_API_KEY가 NerdGraph 조회 권한을 갖는지 확인한다.
  • NEW_RELIC_APP_NAME이 New Relic app name과 일치하는지 확인한다.

Mongoose 지표가 비어 있다

  • newrelic-transaction source는 Mongoose 지표를 제공하지 않는다.
  • newrelic-custom 또는 local source를 사용한다.
  • 계측 활성화 이후 발생한 request인지 확인한다.

관련 파일

  • apps/api/src/modules/global/observability/api-performance.interceptor.ts
  • apps/api/src/modules/global/observability/performance-observer.ts
  • apps/api/src/modules/global/observability/mongoose-performance.plugin.ts
  • apps/api/src/scripts/api-performance-report.ts
  • docs/specs/api-performance-observability.md