Percentile summary

The mean is the number nobody experiences. Latency is reported at p50, p95 and p99 because the tail is what users feel, and an average hides exactly the part that pages someone.


Tokens this needs: --foreground, --muted-foreground, --border, --status-warn, --chart-1
The status, chart, scale, state and direction names are an extension,
not a rename. shadcn has --destructive and five --chart-* and nothing
else in this territory.

────────────────────────────────────────────────────────────────────────
// LatencyPercentiles.tsx
────────────────────────────────────────────────────────────────────────

/**
 * Percentiles from a histogram are estimates, and the panel should say so.
 *
 * This computes quantiles the way Prometheus's histogram_quantile does:
 * find the bucket the rank falls in, then interpolate linearly across it. The
 * error is bounded by that bucket's width and by nothing about the data, so
 * the component prints the bucket beside any estimate whose bucket is wide
 * relative to the value. A p95 of 443ms from a 300–450ms bucket has three
 * significant figures and one of them is real.
 */
export type Bucket = { le: number; count: number };

const ms = (v: number) => (v >= 1000 ? `${v / 1000}s` : `${Math.round(v)}ms`);

/** Which bucket holds the rank, and where in it the quantile interpolates to. */
export function quantile(buckets: Bucket[], q: number) {
  const total = buckets.reduce((n, b) => n + b.count, 0);
  const rank = q * total;
  let below = 0, lo = 0;
  for (const b of buckets) {
    if (below + b.count >= rank) {
      const frac = b.count ? (rank - below) / b.count : 0;
      return { value: lo + frac * (b.le - lo), lo, hi: b.le };
    }
    below += b.count;
    lo = b.le;
  }
  const last = buckets[buckets.length - 1];
  return { value: last.le, lo, hi: last.le };
}

/** An estimate whose bucket spans more than a quarter of its value is thin. */
const WIDE = 0.25;

export function LatencyPercentiles({ buckets, quantiles = [0.5, 0.95, 0.99], ticks, width = 400, height = 160 }: {
  buckets: Bucket[];
  quantiles?: number[];
  /** Axis labels, in ms. Defaults to every bucket boundary. */
  ticks?: number[];
  width?: number;
  height?: number;
}) {
  const max = buckets[buckets.length - 1].le;
  const peak = Math.max(...buckets.map((b) => b.count));
  const x = (v: number) => (v / max) * width;
  const plotH = height - 24;
  const estimates = quantiles.map((q) => {
    const e = quantile(buckets, q);
    return { q, ...e, wide: (e.hi - e.lo) / e.value > WIDE };
  });
  const flagged = estimates.find((e) => e.wide);

  return (
    <div>
      {/* The summary itself: three figures, the tail beside the middle. */}
      <dl className="flex gap-6">
        {estimates.map((e) => (
          <div key={e.q}>
            <dt className="text-xs text-muted-foreground">p{Math.round(e.q * 100)}</dt>
            <dd className={`text-2xl font-semibold tabular-nums ${e.wide ? "text-status-warn" : "text-foreground"}`}>
              {ms(e.value)}
              {e.wide && <span className="ml-1 text-xs font-normal">±</span>}
            </dd>
          </div>
        ))}
      </dl>

      <svg viewBox={`0 0 ${width} ${height}`} className="mt-4 w-full" aria-hidden="true">
        {buckets.map((b, i) => {
          const lo = i ? buckets[i - 1].le : 0;
          const h = (b.count / peak) * (plotH - 20);
          return <rect key={b.le} x={x(lo)} y={plotH - h} width={x(b.le) - x(lo)} height={h} className="fill-chart-1" />;
        })}
        {flagged && (
          <rect x={x(flagged.lo)} y={plotH - (buckets.find((b) => b.le === flagged.hi)!.count / peak) * (plotH - 20)}
            width={x(flagged.hi) - x(flagged.lo)} height={(buckets.find((b) => b.le === flagged.hi)!.count / peak) * (plotH - 20)}
            fill="none" className="stroke-status-warn" strokeWidth="2" />
        )}
        {estimates.map((e) => (
          <g key={e.q} className={e.wide ? "stroke-status-warn fill-status-warn" : "stroke-border fill-muted-foreground"}>
            <line x1={x(e.value)} y1={14} x2={x(e.value)} y2={plotH} strokeDasharray="4 4" strokeWidth={e.wide ? 2 : 1} />
            <text x={x(e.value)} y={10} textAnchor="middle" className="text-[9px]" stroke="none">p{Math.round(e.q * 100)} {ms(e.value)}</text>
          </g>
        ))}
        <line x1={0} y1={plotH} x2={width} y2={plotH} className="stroke-border" />
        {(ticks ?? buckets.map((b) => b.le)).map((t) => (
          <text key={t} x={x(t)} y={height - 4} textAnchor={t === max ? "end" : "middle"} className="fill-muted-foreground text-[9px]">{ms(t)}</text>
        ))}
      </svg>

      {flagged && (
        <p className="mt-2 text-xs text-muted-foreground">
          p{Math.round(flagged.q * 100)} is interpolated across the {ms(flagged.lo)}–{ms(flagged.hi)} bucket, which holds most of the observations. Anywhere in that bucket is consistent with the data.
        </p>
      )}
    </div>
  );
}

────────────────────────────────────────────────────────────────────────
// demo.tsx
────────────────────────────────────────────────────────────────────────

import { LatencyPercentiles } from "./LatencyPercentiles";

/**
 * Uneven buckets, roughly Prometheus's shape, with most observations in one
 * wide bucket from 300 to 450ms. p95 lands in it and gets the ± and the
 * outline; p50 lands in a narrow one and does not.
 */
export default function Demo() {
  return (
    <LatencyPercentiles
      buckets={[
        { le: 100, count: 30 },
        { le: 200, count: 50 },
        { le: 250, count: 60 },
        { le: 300, count: 40 },
        { le: 450, count: 130 },
        { le: 700, count: 7 },
        { le: 1000, count: 3 },
      ]}
      ticks={[100, 300, 450, 1000]}
    />
  );
}