Single-tile throughput numbers (req/s, p99) miss what users actually experience. When you pan or zoom a MapLibre GL JS map, the browser fires a grid of tile requests in parallel to fill the viewport. The metric that matters is time-to-full-viewport — how long until the last tile of the grid paints.

Grid mode simulates exactly this.

Quick start

# Bring up the benchmark stack (tileserver-rs + tileserver-gl + martin + titiler)
docker compose -f benchmarks/docker-compose.yml --profile all up -d

# Run grid mode — default is 4×4 = 16 tiles per viewport
pnpm --filter @tileserver-rs/benchmarks run bench --mode grid

# Match a 1920×1080 browser viewport exactly
pnpm --filter @tileserver-rs/benchmarks run bench --mode grid --grid-size 5x4

# More iterations for tighter p99 confidence intervals
pnpm --filter @tileserver-rs/benchmarks run bench --mode grid --iterations 100

How the grid is built

For a 1920×1080 viewport at 512 px tiles you need ⌈1920/512⌉ + 1 = 5 tiles wide and ⌈1080/512⌉ + 1 = 4 tiles tall — 20 tiles total. A 4×4 default captures a typical retina laptop viewport. The benchmark centers the grid on a well-known test location (Florence for PMTiles, Zurich for MBTiles, the Alps for STAC raster) and fires every tile request concurrently via Promise.all — identical to MapLibre's browser fetch pattern.

z=12 centered on Florence (2177, 1494), 4×4 grid:

  (2175, 1492)  (2176, 1492)  (2177, 1492)  (2178, 1492)
  (2175, 1493)  (2176, 1493)  (2177, 1493)  (2178, 1493)
  (2175, 1494)  (2176, 1494)  (2177, 1494)  (2178, 1494)
  (2175, 1495)  (2176, 1495)  (2177, 1495)  (2178, 1495)

What gets measured

Each grid-load iteration records:

Every zoom level gets 3 warmup iterations (to prime caches, JIT, connection pools) before the measurement iterations kick in. This matters because cold-path STAC and COG tiles can take 30–60 s to hydrate, and warmup separates that from the steady-state number.

Results

Run captured 2026-10-16 on the same setup as the performance benchmarks (Apple Silicon, 12 cores, Docker, quiet host gate). 4×4 grid, 50 iterations per zoom after 3 warmup loads. Values are grids/s · average grid latency · P99.

On PMTiles tileserver-rs fills a city-zoom viewport fastest (5 ms, P99 8 ms), about 3× faster than tileserver-gl. On MBTiles it ties martin. On PostGIS martin is about 2× faster, on tables and on function sources. That gap is open work.

Why this matters more than req/s

Single-tile req/s numbers can mislead. A server that answers one tile in 10 ms but serializes the next 15 behind it still takes 160 ms to fill a viewport — the user experiences 160 ms, not 10 ms. Grid mode measures the parallel reality.

It also exposes tail latency. A server with 50 ms average and 600 ms p99 will feel janky because every viewport load is only as fast as its slowest tile. maxTileLatency in the per-iteration output surfaces this directly.

CLI reference

-m, --mode <mode>         single (default) | grid
-g, --grid-size <WxH>     grid dimensions, e.g. 4x4 (default), 5x4, 3x3
-i, --iterations <num>    per-zoom iterations (default: 50)

Raster formats automatically scale iteration count down by 3× (raster tiles are 10-50× slower than vector) so a full run completes in reasonable time without sacrificing statistical significance.

Grid mode supports the same --type, --server, and --markdown flags as single-tile mode — they all compose.

When to use each mode

Run both. Single-tile tells you whether your server can handle a load-test scenario (many clients, each fetching one tile). Grid tells you what a single user will experience sitting in front of the browser.