Find slow requests with performance diagnostics

This operations guide helps you identify slow HTTP route groups and determine how much database access contributes to their latency. After the measurement, you have a privacy-conscious ranking that can guide a separately tested optimization.

Prerequisites

You need a valid nucli alias for the System Tenant and the system_diagnostics:read scope. Verify the context first:

bash
nucli --tenant system whoami --scopes

Run measurements in production or staging only with explicit approval. The command reads metrics and does not change product data.

Measure routes

Choose a window with representative traffic:

bash
nucli --tenant system performance routes --window 30s --min-requests 5 --limit 20

Add --json for automation. The command reads one cumulative snapshot at the start and another at the end. It filters low-volume routes and ranks the remaining routes by P95 latency. A server restart or regressing counter aborts the analysis; rerun it with a complete window.

P95 is an approximate histogram bucket boundary. A value prefixed with >= means the observation reached the unbounded bucket. DB AVG shows cumulative database time per request, while DB Q/REQ shows the average query count. Parallel queries can accumulate more database time than the HTTP wall time.

High HTTP latency with low database time points toward application work, external services, or response size. High database time or query counts guide you toward query plans, indexes, N+1 access, or connection-pool waits. Treat these signals as evidence for a separate endpoint change, not as an automatic repair.

Prometheus is optional

Workspace produces the metrics itself, so nucli performance routes does not need a Prometheus server. Add an external Prometheus-compatible collector only when you need retained time series, dashboards, or alerts.

The protected raw endpoint is /api/v1/system/metrics. Its route labels do not contain concrete request paths, query strings, SQL, identities, or tenants.