Auto-insight

Problem

Important changes can go unnoticed when a dashboard has more charts and categories than people can check.

Solution

Show a short summary of a change worth investigating, with a link to the supporting data. Favor findings that narrow the investigation over sentences that simply repeat a visible number.

State what was compared, the time period, and why the change was flagged. Separate a possible explanation from a confirmed cause.

Let people inspect the evidence and dismiss unhelpful findings. Review the detection rules when conditions change so expected activity does not fill the feed.

Use when

There are too many combinations to inspect manually, a useful baseline exists, and people can act on the findings.

Don’t use when

The page is small enough to read. An insight panel on a six-panel dashboard is telling people something they can see, and it trains them to skip the top of the page.

Trade-offs

False alarms can make people ignore the feed. Confident wording can overstate weak evidence, and recent changes can make historical baselines less useful. Automated summaries also need a clear dashboard underneath them.

Checklist

Is each insight a finding, or a restatement of something visible?
Does it say what was compared, over what window?
Is there one click to the underlying data?
What is the false-positive rate, and who reviews it?
Does the phrasing imply causation the analysis does not support?
What happens after a deliberate change that moves every baseline?
Can a viewer suppress an insight type, and does anyone?
How many insights per day, and does anyone read the last one?
Is there any measurement of whether these lead to action?
Would restructuring the page remove the need for this?

Compare

Datadog Watchdog is the most developed version in observability, surfacing detected anomalies across the estate as a feed rather than requiring a configured monitor per metric, which is the pattern’s real promise: catching what nobody thought to watch. Honeycomb BubbleUp takes the opposite path—the human points at the anomaly and the system explains it—which keeps a person in the loop for the judgement and gives the machine the dimensional comparison it is actually good at. Amplitude and BI tools generate narrative summaries of chart movements, which sit closer to the description end and are most useful to readers who would not otherwise read the chart at all. Grafana has no equivalent in core, so the machine-detection role falls to alerting rules and to ML features outside the dashboard.

Anomaly band shows an expected range visually. Alert rule delivers a notification to an owner. Cross-filter supports manual investigation.

Single-column narrative provides a place for a summary. Explain this metric defines the measures behind a finding.

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

Implementation

The product telling a reader what it noticed on a chart they did not open. Every claim has to link to the evidence, because an insight the reader cannot verify is a rumour with a nice border.

shadcn

npx shadcn@latest add card button

Tokens

--card--card-foreground--muted-foreground--border--chart-1

LightDarkCode

Insight

Errors increased 40%. 94% of them come from build 4a91c, in eu-west, all after 14:02.

compared 38 dimensions · 14:00-15:00

see the data

InsightCard.tsxThe finding, the provenance line computed from what was compared, and a link to the evidence that the type will not let you leave out.

import { Card } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

/** What was compared and over what window. Without it the sentence is a
 *  rumour with a nice border. */
export type Provenance = {
  /** How many dimensions were ranked against the baseline. */
  dimensions: number;
  /** The anomalous window, as the reader would type it into the chart. */
  window: string;
};

type Props = {
  /** The finding. It should name what separates the anomaly from the
   *  baseline, which is the work the reader could not do by scanning. */
  finding: string;
  provenance: Provenance;
  /** One click to the data that produced it. Required, because an insight
   *  that cannot be checked will not be trusted. */
  evidenceHref: string;
  heading?: string;
};

export function InsightCard({ finding, provenance, evidenceHref, heading = "Insight" }: Props) {
  return (
    <Card className="border-2 border-chart-1 p-4">
      <p className="border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">{heading}</p>
      <p className="mt-3 text-sm leading-relaxed text-card-foreground">{finding}</p>
      <p className="mt-2 text-[11px] tabular-nums text-muted-foreground">
        compared {provenance.dimensions} dimensions · {provenance.window}
      </p>
      <Button asChild variant="outline" size="sm" className="mt-2.5 h-6 px-2 text-[10px]">
        <a href={evidenceHref}>see the data</a>
      </Button>
    </Card>
  );
}

demo.tsxHow it is called: the finding from the drawing, 38 dimensions over one hour, one click to the query.

import { InsightCard } from "./InsightCard";

/**
 * A finding rather than a description: the 40% is what the chart showed, the
 * build, region and time are what comparing 38 dimensions found.
 */
export default function Demo() {
  return (
    <div className="w-[300px]">
      <InsightCard
        finding="Errors increased 40%. 94% of them come from build 4a91c, in eu-west, all after 14:02."
        provenance={{ dimensions: 38, window: "14:00-15:00" }}
        evidenceHref="/explore?metric=errors&from=14:00&to=15:00&group=build,region"
      />
    </div>
  );
}

What it renders. Identical markup in both panes, with only the token values changing.