Time series

The viewer needs to see how a value changed over time and spot the moment it changed.

Updated September 9, 2026

Problem

Someone is looking at a number that moved. What they need is not the number. They need the shape that produced it, and the moment the shape changed, because that moment is usually the only thing they can act on.

Solution

Time on the horizontal, value on the vertical, points joined by a line. That part has been settled since Playfair and nobody needs to reconsider it.

What makes or breaks the panel is everything the line implies that the data never said. A time series on a screen is always sampled, always aggregated down to the pixels available, and the aggregation is a decision the viewer can’t see. Grafana makes one piece of this explicit, which is instructive: connect null values has three positions, Never, Always, and Threshold, and the same gap in the same data reads as an outage, as a straight line through nothing, or as a judgment call, depending on which one someone picked. Most products make that choice for you and don’t mention it.

The second thing is the y-axis. A line chart doesn’t need a zero baseline the way a bar chart does, because the line encodes change and the bar encodes magnitude. That freedom is also how a 2% drift gets drawn as a cliff.

Use when

The question has “when” in it. When did it start, when did it recover, is it still happening. Also when the viewer needs a rate rather than a total, which covers most of operations.

Don’t use when

The categories have no natural order, or there are more series than a person can follow. Twelve lines on one chart is a legend exercise. If the answer is a distribution rather than a trajectory, a histogram or a heatmap will say more.

Trade-offs

The line asserts continuity between points that were sampled discretely, so it always claims to know slightly more than it does. Downsampling to fit the panel width can erase the spike that mattered; a five-second outage doesn’t survive a query returning one point per minute, and nothing on the panel admits this. Averaging over the rollup window smooths in the same direction, always toward “fine”. Y-axis autoscaling makes every chart look eventful, which teaches the viewer to ignore all of them.

Checklist

What is the interval between points, and can the viewer tell?
What happens to a gap: drawn as a gap, connected, or filled with zero?
Is missing data visually distinct from a real zero?
Does the y-axis start at zero, and if not, is that defensible for this metric?
Does the axis rescale as data arrives, and does that make small movement look large?
What aggregation runs when the range is wide: average, max, or last? Would max change the answer?
Can the viewer see the time range and change it without leaving the panel?
Where several panels share a page, do they share a time range, and a y-scale where it matters?
Are units on the axis, and are they the units the viewer thinks in?
How many series before this stops being readable, and what happens at that count?

Compare

Grafana exposes the gap decision as a per-panel setting with three positions, which is the most honest treatment in the category and also the reason two panels on one dashboard can disagree about the same outage. Netdata samples per second and draws it, so the chart keeps detail most tools have averaged away before it reaches the panel, at the cost of a page that never sits still. Honeycomb answers the same question with a heatmap instead of a line, arguing that a line drawn through a percentile hides the distribution that would explain it. Sentry puts the series inline on every issue row as a sparkline, the same encoding at list density, doing a job a full panel would be too expensive for.

Sparkline is this pattern shrunk to sit beside a number. Anomaly band and threshold line are the two ways to put “what should this look like” on the same axes. Annotation answers the question the line provokes, which is what happened at that moment. Time-range picker is the control that makes the chart answerable at all, and zoom and pan is how the viewer narrows once they’ve found the moment.

Wireframe — the pattern's anatomy, not any one product's version of it

Implementation

Recharts, with the two decisions a line hides made explicit: the interval in the header, a closed set of gap treatments, and an axis that starts at zero unless the caller asks otherwise and the panel says so.

npm: recharts
Tokens: --card--muted--muted-foreground--border--chart-1

LightDarkCode

Checkout P95 · 1m intervalms

TimeSeries.tsxThe header names the interval, gaps are drawn as gaps, joined, or joined under a threshold, and the axis starts at zero unless told to fit.

import { CartesianGrid, Line, LineChart, ReferenceArea, Tooltip, XAxis, YAxis } from "recharts";

export type Sample = { t: number; value: number | null };

/**
 * Grafana's three positions for a gap, made a closed set. `never` draws the
 * gap; `always` draws a straight line through nothing; a threshold joins
 * only gaps shorter than it, which is the judgment call written down.
 */
export type Gaps = "never" | "always" | { joinUnderMs: number };

const hhmm = (t: number) => new Date(t).toISOString().slice(11, 16);
const MIN = 60_000;

/** The null runs, as [first, last] timestamps. */
const runs = (data: Sample[]) => {
  const out: [number, number][] = [];
  for (const s of data) {
    if (s.value !== null) continue;
    const last = out[out.length - 1];
    if (last && s.t - last[1] <= 1.5 * (data[1].t - data[0].t)) last[1] = s.t;
    else out.push([s.t, s.t]);
  }
  return out;
};

/** Fill the gaps shorter than the threshold by straight line, leave the rest. */
const join = (data: Sample[], underMs: number): Sample[] => {
  const out = data.map((s) => ({ ...s }));
  for (const [a, b] of runs(data)) {
    if (b - a + MIN > underMs) continue;
    const i = out.findIndex((s) => s.t === a), j = out.findIndex((s) => s.t === b);
    const y0 = out[i - 1]?.value, y1 = out[j + 1]?.value;
    if (y0 == null || y1 == null) continue;
    for (let k = i; k <= j; k++) out[k].value = y0 + ((y1 - y0) * (k - i + 1)) / (j - i + 2);
  }
  return out;
};

/**
 * Time on the horizontal, value on the vertical, and the two decisions the
 * line would otherwise hide, stated: the interval is in the header, the gap
 * treatment is a prop with three positions, and the axis starts at zero
 * unless the caller says otherwise, in which case the panel says so too.
 */
export function TimeSeries({ title, interval, unit, data, gaps = "never", baseline = "zero", max, width = 400, height = 160 }: {
  title: string;
  /** The aggregation interval, as the viewer should read it: "1m", "5m", "1h". */
  interval: string;
  unit: string;
  data: Sample[];
  gaps?: Gaps;
  baseline?: "zero" | "fit";
  /** Pin the top of the axis, so panels on one page can share a scale. */
  max?: number;
  width?: number;
  height?: number;
}) {
  const series = typeof gaps === "object" ? join(data, gaps.joinUnderMs) : data;
  const gapRuns = runs(series);
  // Tick every 20 minutes on the clock, not from the first sample.
  const step = 20 * MIN;
  const ticks: number[] = [];
  for (let t = Math.ceil(data[0].t / step) * step; t <= data[data.length - 1].t; t += step) ticks.push(t);
  const stroke = "hsl(var(--chart-1))";
  const tick = { fontSize: 10, fill: "hsl(var(--muted-foreground))" };

  return (
    <div>
      <p className="flex justify-between border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">
        <span>{title} · {interval} interval</span>
        <span>{unit}</span>
      </p>
      <div className="mt-3 overflow-x-auto">
        <LineChart width={width} height={height} data={series} margin={{ top: 6, right: 8, bottom: 0, left: -16 }}>
          <CartesianGrid vertical={false} stroke="hsl(var(--border))" />
          <XAxis interval={0} dataKey="t" type="number" domain={["dataMin", "dataMax"]} ticks={ticks} tickFormatter={hhmm} tick={tick} stroke="hsl(var(--border))" />
          <YAxis domain={[baseline === "zero" ? 0 : "auto", max ?? "auto"]} tick={tick} stroke="hsl(var(--border))" />
          <Tooltip labelFormatter={(t) => `${hhmm(Number(t))} UTC`} formatter={(v) => [`${v} ${unit}`, title]} />
          {gapRuns.map(([a, b]) => (
            <ReferenceArea key={a} x1={a} x2={b} fill="hsl(var(--muted))" fillOpacity={1} stroke="none" />
          ))}
          <Line type="linear" dataKey="value" stroke={stroke} strokeWidth={2} dot={false} connectNulls={gaps === "always"} isAnimationActive={false} />
        </LineChart>
      </div>
      {baseline === "fit" && <p className="mt-2 text-[11px] text-muted-foreground">Axis does not start at zero.</p>}
    </div>
  );
}

demo.tsxHow it is called: a minute of samples at a time with ten missing, the gap left as a gap, the top of the axis pinned.

import { TimeSeries, type Sample } from "./TimeSeries";

/** Checkout p95 in ms, one sample a minute from 14:00, and ten minutes with no samples at all. */
const T0 = Date.UTC(2026, 8, 15, 14, 0);
const VALUES: (number | null)[] = [
  90, 104, 112, 98, 120, 116, 124, 110, 128, 134, 126, 140, 146, 138, 152, 150, 144, 158, 164, 156,
  null, null, null, null, null, null, null, null, null, null,
  196, 188, 204, 174, 212, 220, 208, 241, 230, 236, 219, 248, 256, 262, 272,
];
const DATA: Sample[] = VALUES.map((value, i) => ({ t: T0 + i * 60_000, value }));

export default function Demo() {
  return (
    <div className="rounded-lg border bg-card p-4">
      <TimeSeries title="Checkout P95" interval="1m" unit="ms" data={DATA} gaps="never" max={400} />
    </div>
  );
}