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 데이터를 우선 활용한다.
ApiRequestPerformancecustom 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별로 다음 지표를 포함한다.
samplesavgMs,p50Ms,p95Ms,p99Ms,maxMserrorRatePercentagequeryCountP95mongooseDurationP95MsdocsReturnedP95hydratedDocsReturnedP95
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가 악화될 가능성이 높다.
권장 분석 순서
newrelic-transaction으로 전체 route의 p95/p99 latency를 확인한다.newrelic-custom으로slow또는document-heavyroute를 확인한다.docsReturnedP95가 크면 projection, pagination, aggregate result 축소를 본다.hydratedDocsReturnedP95가 0보다 크면 읽기 전용 경로에.lean()적용을 검토한다.queryCountP95가 크면 N+1 query 또는 반복 조회를 찾는다.mongooseDurationP95Ms가 낮은데p95Ms만 높으면 외부 API, CPU work, serialization, payload size를 본다.
전체 API 테스트 체크리스트
pnpm --filter api perf:routes로 route 목록을 확인했다.- 주요 화면/운영 기능을 실제로 한 번 이상 호출했다.
- 리포트의
no-samplesroute를 확인했다. - intentionally unused/admin-only API와 테스트 누락 API를 구분했다.
slowroute의 New Relic trace를 확인했다.document-heavyroute의 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라면
--sincewindow 안에 데이터가 있는지 확인한다. newrelic-customsource라면 계측 배포/환경변수 활성화 이후의 요청인지 확인한다.
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-transactionsource는 Mongoose 지표를 제공하지 않는다.newrelic-custom또는localsource를 사용한다.- 계측 활성화 이후 발생한 request인지 확인한다.
관련 파일
apps/api/src/modules/global/observability/api-performance.interceptor.tsapps/api/src/modules/global/observability/performance-observer.tsapps/api/src/modules/global/observability/mongoose-performance.plugin.tsapps/api/src/scripts/api-performance-report.tsdocs/specs/api-performance-observability.md