2.9 KiB
2.9 KiB
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-nodefor 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.tsgenerates full API reports.docs/specs/api-performance-observability.mddefines this behavior.
Code Style
Instrumentation must be opt-in and defensive:
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-samplesfor 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.