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

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

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.