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