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

259 lines
9.7 KiB
Markdown

# 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`