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,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