feat: add API performance observability reporting
This commit is contained in:
1 parent
871a5fe78a
commit
88de2148ae
14 files changed
+2082
-1
No files matched your search
@@ -0,0 +1,259 @@
|
||||
# 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`
|
||||
@@ -0,0 +1,80 @@
|
||||
# Spec: API Performance Observability And Full Route Report
|
||||
|
||||
## Objective
|
||||
|
||||
Add Phase 1 and Phase 2 support for API performance work:
|
||||
|
||||
- Phase 1 records request latency and Mongoose document-return metrics.
|
||||
- Phase 2 generates a report for every API route, not only the slowest routes.
|
||||
- New Relic Transaction or custom event data is the preferred production source.
|
||||
- Local NDJSON files provide a staging/local fallback with query-level detail.
|
||||
|
||||
Success means an engineer can run representative traffic against the API and produce
|
||||
a route-complete report that includes routes with no samples.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- NestJS API in `apps/api`
|
||||
- Mongoose models created through `ConnectionService`
|
||||
- New Relic Node agent, already configured by `apps/api/newrelic.cjs`
|
||||
- Jest for unit tests
|
||||
- `ts-node` for API maintenance scripts
|
||||
|
||||
## Commands
|
||||
|
||||
- Build: `pnpm --filter api build`
|
||||
- Test: `pnpm --filter api test`
|
||||
- Generate local/New Relic report: `pnpm --filter api perf:report`
|
||||
- Generate route manifest only: `pnpm --filter api perf:routes`
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `apps/api/src/modules/global/observability/` contains request/query instrumentation.
|
||||
- `apps/api/src/scripts/api-performance-report.ts` generates full API reports.
|
||||
- `docs/specs/api-performance-observability.md` defines this behavior.
|
||||
|
||||
## Code Style
|
||||
|
||||
Instrumentation must be opt-in and defensive:
|
||||
|
||||
```ts
|
||||
if (!isPerformanceObservabilityEnabled()) return;
|
||||
recordApiPerformanceEvent({
|
||||
type: 'api-request',
|
||||
method,
|
||||
route,
|
||||
durationMs,
|
||||
});
|
||||
```
|
||||
|
||||
Do not record raw request bodies, authorization headers, cookies, raw Mongo filters,
|
||||
or raw query results.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Unit test pure metric aggregation and route discovery logic.
|
||||
- Unit test request context aggregation without a database.
|
||||
- Build the API to catch Nest and TypeScript integration issues.
|
||||
- Production/staging validation uses New Relic Transaction data and optional local
|
||||
NDJSON from representative traffic.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- Always: keep instrumentation disabled unless explicitly enabled.
|
||||
- Always: include all discovered controller routes in the report.
|
||||
- Always: report `no-samples` for routes that did not receive traffic.
|
||||
- Ask first: adding external load-test dependencies or CI performance gates.
|
||||
- Never: log secrets, request bodies, auth headers, cookies, or raw Mongo filters.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- API request events include duration, status, route, query count, Mongoose duration,
|
||||
returned document count, and hydrated document count.
|
||||
- Mongoose query events include model, collection, operation, duration, returned
|
||||
documents, hydrated documents, and lean status.
|
||||
- New Relic receives route-level custom events when instrumentation is enabled.
|
||||
- New Relic Transaction traces can be grouped by route through custom transaction names
|
||||
and attributes.
|
||||
- The report generator can use local NDJSON, New Relic custom events, or New Relic
|
||||
Transaction duration data.
|
||||
- The report lists every API route from controller source files.
|
||||
Reference in new issue
Block a user