Files
lolympus-tournament-support/docs/specs/api-performance-observability.md
T

81 lines
2.9 KiB
Markdown

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