latency-break

CLI tool to analyze API latency and break it down into meaningful segments (network, DB, server logic, total time).

It helps you identify where your API is slow, not just how slow it is.

Usage

Run directly with npx:

npx latency-break <url>

To install:

npm install -g latency-break

To run installed package:

latency-break <url>

How it works

Every run measures the network phases client-side — no server changes needed:

DNS lookup
TCP connect
TLS handshake (https only)
TTFB (time to first byte)
Download

If the server is also instrumented, it additionally reads timing headers for a server-side breakdown:

X-Total-Time
X-DB-Time
X-Pre-DB-Time
X-Post-DB-Time

Whichever phases are available (network-only, or network + server), the CLI calls out the single slowest one as the bottleneck, with a one-line hint on what to check.

Output is colorized by magnitude (green/yellow/red per phase) when run in a terminal; colors are skipped automatically when piped to a file, when output isn't a TTY, or when NO_COLOR is set.

Options

Usage: latency-break <url> [options]

Options:
  --repeat <n>            Send <n> requests and report percentile stats (default: 1)
  --header "Name: value"  Add a request header (repeatable)
  --json                  Output machine-readable JSON instead of a formatted report
  --version               Print the CLI version
  --help                  Show this help

Single request

latency-break https://api.example.com/users

Prints the network breakdown, the server breakdown (if headers are present), and the bottleneck.

Repeated requests / percentile stats

latency-break https://api.example.com/users --repeat 20

Fires 20 requests and prints min / mean / p50 / p95 / p99 / max per phase, flagging phases with high variance (jitter: p95 ≥ 1.5× p50).

Custom headers

latency-break https://api.example.com/users --header "Authorization: Bearer <token>"

Repeat --header for multiple headers.

JSON output

latency-break https://api.example.com/users --json
latency-break https://api.example.com/users --repeat 20 --json

Single-request JSON includes the raw network/server timings. Repeated-request JSON includes computed stats per phase plus the raw per-request results.

Demo server

The demo/ folder has an instrumented Express + Postgres server that emits the X-*-Time headers, so you can see the full network + server breakdown end to end.

Start it:

node demo/index.js

Then, in another terminal:

latency-break http://localhost:3003/users