81 lines
2.9 KiB
Markdown
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.
|