# 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 목록 확인 ```bash pnpm --filter api perf:routes ``` 이 명령은 `*.controller.ts` 파일을 읽어 전체 route manifest를 출력한다. 리포트는 이 manifest를 기준으로 모든 API를 출력한다. 트래픽이 없었던 API는 `no-samples`로 표시된다. ### 2. New Relic Transaction 기반 전체 latency 리포트 ```bash 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 서버가 아래 환경변수로 실행된 뒤 트래픽이 쌓여야 한다. ```bash API_PERF_OBSERVABILITY_ENABLED=true API_PERF_NEW_RELIC_REQUEST_EVENTS_ENABLED=true ``` 중요: custom event는 소급 생성되지 않는다. 계측 코드가 배포되고 위 환경변수로 서버가 재시작된 이후의 요청부터 `ApiRequestPerformance`가 쌓인다. 기존 New Relic Transaction 데이터가 있어도 custom event 리포트는 0건일 수 있다. 리포트 생성: ```bash 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 서버를 계측 모드로 실행한다. ```bash 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`로 남는다. 리포트 생성: ```bash pnpm --filter api perf:report -- \ --source=local \ --input=/tmp/lolympus-api-performance.ndjson ``` JSON 출력: ```bash pnpm --filter api perf:report -- \ --source=local \ --input=/tmp/lolympus-api-performance.ndjson \ --format=json ``` 파일 저장: ```bash 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` 명령에서 덮어쓸 수 있다. ```bash 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 존재 여부를 먼저 확인한다. ```sql FROM ApiRequestPerformance SELECT count(*) SINCE 1 day ago ``` app name 필터까지 확인한다. ```sql 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`