Anomaly band

A metric is moving, and the person watching it can't tell whether the movement is normal for this hour on this weekday or the start of an incident.

Updated September 9, 2026

Problem

Raw time series lie by omission. Traffic drops every night. Latency rises every Monday at nine. A static threshold line fires all night or misses the daytime spike, and the on-call engineer learns to ignore it. What the viewer needs is the shape of normal, drawn on the chart, so the eye does the comparison.

Solution

Draw a translucent band around the series that represents the expected range for this moment, computed from the metric’s own history with seasonality. The line stays the line. The band is quiet, usually gray. When the line leaves the band, that segment changes color, and that color is the only alarm on the chart.

The band has to be honest about its own confidence. Datadog exposes three algorithms (basic, agile, robust) with different tolerance, and the width of the band is the visible expression of that choice. A band that’s too wide never fires. A band that’s too tight is a static threshold with extra steps.

Use when

The metric has a daily or weekly rhythm and a human is watching for departures from it: request rate, error rate, queue depth, sign-ups, spend. The band is most valuable on the overview chart people glance at, not on deep-dive charts where they’re already investigating.

Don’t use when

The metric is supposed to be flat, in which case a threshold line is clearer and cheaper. Or when history is short; a band trained on three days of data is a guess drawn with authority. And never on a chart whose viewer can’t see or change the algorithm, because they’ll trust it anyway.

Trade-offs

Bands add ink to every chart they’re on and hide the series behind them when the band is wide. They shift attention from absolute values to deviation, which is right for operations and wrong for capacity planning. They also produce a new class of false positive: a metric that’s abnormal and fine, like traffic after a product launch. Netdata’s approach of showing an anomaly rate as its own small ribbon above the chart, rather than a band on it, trades chart cleanliness for a second thing to read.

Checklist

Is the band visibly quieter than the series? Gray or very low alpha, no outline.
When the series leaves the band, does only that segment change, and does the color match the site’s semantic status scale?
Can the viewer find out how the band is computed and over what history?
Does the band exist on the time range the viewer is looking at, or only on the last few hours?
What happens at the right edge, where the newest points have the least history?
Does hover show the expected range as numbers, not just the actual value?
If an alert is attached to the band, does the chart say so?
Does the band survive the switch to dark theme without becoming invisible or glowing?

Compare

Datadog draws the band on the chart, gray, and recolors excursions; it’s the version most people picture. Netdata puts anomaly rate in a separate ribbon above every chart, computed per second, so the band never obscures the data but the eye has to travel. Grafana has no native band; teams fake one with a shaded series from a forecast query, which is a tell that the pattern is more product than chart type. Honeycomb skips the band entirely in favor of BubbleUp, which asks the user to draw the anomaly and then explains it, a cross-filter answer to the same problem.

Time series is the substrate. Threshold line is the simpler sibling for flat metrics. Alert rule is what the band usually feeds. Auto-insight is the band’s textual cousin, the “we noticed” feed. Semantic status color governs what the excursion looks like.

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

Implementation

A band saying what normal looked like, so a spike is read against an expectation rather than against a reader's memory. The band has to say how it was computed, because a model nobody can inspect is an opinion drawn as a fact.

npm: recharts
Tokens: --card--muted--muted-foreground--border--popover--status-critical--chart-1

LightDarkCode

Requests per second · 24h

Band: median ± 2 MAD for the same weekday and hour, from the last four weeks. 3 of 24 points outside it.

AnomalyBand.tsxA quiet range area under the series, colour only on the segment that leaves it, and a required method line saying how the band was computed.

import { Area, ComposedChart, Line, Tooltip, XAxis, YAxis } from "recharts";

export type Point = {
  /** The x label, "13:00". */
  t: string;
  value: number;
  /** What normal looks like at this moment: the band's floor and ceiling. */
  expected: [lo: number, hi: number];
};

/**
 * The band has to say how it was computed. A model nobody can inspect is an
 * opinion drawn as a fact, so the method and its history are required, and
 * they print under the chart rather than living in a tooltip.
 */
export type Method = { name: string; history: string };

const BAND = "hsl(var(--muted))";
const SERIES = "hsl(var(--chart-1))";
const ALARM = "hsl(var(--status-critical))";

const outside = (p: Point) => p.value < p.expected[0] || p.value > p.expected[1];

export function AnomalyBand({ title, points, method, width = 400, height = 180 }: {
  title: string;
  points: Point[];
  method: Method;
  width?: number;
  height?: number;
}) {
  /**
   * Two lines over one series. The normal line is null wherever the value
   * leaves the band; the alarm line is null wherever it stays in. Each keeps
   * the boundary point on either side so the two meet instead of gapping.
   * Colour appears only where the line leaves the band, and nowhere else.
   */
  const data = points.map((p, i) => {
    const out = outside(p);
    const nearOut = out || outside(points[i - 1] ?? p) || outside(points[i + 1] ?? p);
    return { ...p, normal: out ? null : p.value, alarm: nearOut ? p.value : null };
  });
  const alarms = points.filter(outside).length;

  return (
    <div className="rounded-lg border bg-card p-4">
      <p className="border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">{title}</p>
      <div className="mt-3 overflow-x-auto">
        <ComposedChart width={width} height={height} data={data} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
          <XAxis interval={0} dataKey="t" ticks={["03:00", "12:00", "21:00"]} tickLine={false} axisLine={{ stroke: "hsl(var(--border))" }}
            tick={{ fontSize: 10, fill: "hsl(var(--muted-foreground))" }} />
          <YAxis hide domain={["dataMin - 100", "dataMax + 100"]} />
          {/* Quiet and grey. No outline: an edge would read as a limit. */}
          <Area dataKey="expected" fill={BAND} stroke="none" fillOpacity={1} isAnimationActive={false} />
          <Line dataKey="normal" stroke={SERIES} strokeWidth={2} dot={false} isAnimationActive={false} />
          <Line dataKey="alarm" stroke={ALARM} strokeWidth={2.5} dot={false} isAnimationActive={false} />
          {/* Hover gives the range as numbers, so "outside" can be checked. */}
          <Tooltip
            isAnimationActive={false}
            contentStyle={{ fontSize: 11, background: "hsl(var(--popover))", borderColor: "hsl(var(--border))" }}
            formatter={(v, name, item) => {
              const p = item.payload as Point;
              return name === "expected" ? [`${p.expected[0]}–${p.expected[1]}`, "expected"] : [String(v), "actual"];
            }}
          />
        </ComposedChart>
      </div>
      <p className="mt-2 text-[11px] text-muted-foreground">
        Band: {method.name}, from {method.history}.
        {alarms > 0 && ` ${alarms} of ${points.length} points outside it.`}
      </p>
    </div>
  );
}

demo.tsxHow it is called: 24 hourly points with a band that follows the daily rhythm, and three that leave it in the evening.

import { AnomalyBand, type Point } from "./AnomalyBand";

/**
 * Twenty-four hours of requests per second. The band is ±220 at 03:00 and
 * ±80 at midday because the metric's own rhythm is, and three evening points
 * leave it. Everything else is wobble the band already allows for.
 */
const HOURS: [center: number, half: number, actual: number][] = [
  [520, 190, 500], [470, 200, 450], [430, 210, 410], [410, 220, 430], [430, 210, 400], [500, 190, 520],
  [620, 170, 600], [800, 140, 830], [1000, 120, 980], [1180, 100, 1200], [1300, 90, 1290], [1380, 80, 1400],
  [1420, 80, 1410], [1400, 80, 1380], [1340, 90, 1360], [1240, 100, 1220], [1120, 110, 1140], [1000, 120, 990],
  [900, 130, 920], [820, 140, 870], [750, 150, 1260], [690, 160, 1320], [630, 170, 900], [570, 180, 640],
];

const POINTS: Point[] = HOURS.map(([center, half, actual], h) => ({
  t: `${String(h).padStart(2, "0")}:00`,
  value: actual,
  expected: [center - half, center + half],
}));

export default function Demo() {
  return (
    <AnomalyBand
      title="Requests per second · 24h"
      points={POINTS}
      method={{ name: "median ± 2 MAD for the same weekday and hour", history: "the last four weeks" }}
    />
  );
}