# Annotation > A change in the line has a cause, and the viewer shouldn't have to go find it elsewhere. - Canonical: https://patterns.konigi.com/dashboards/annotation - Group: Meta information - Level: implementation - Status: published - Updated: September 10, 2026 - Also called: event marker, deploy marker, note on chart --- ## Problem Latency doubled at 14:07 and stayed there. Somewhere there is a deploy log, a change ticket, or a person who knows why, and the viewer is looking at a chart that shows the effect and nothing about the cause. ## Solution Put the event on the same axis as the data. A vertical line at the moment, a marker with a label, and detail on hover. The correlation the viewer would otherwise construct by cross-referencing two systems becomes something they see. Grafana's model is a good one to think in, because it separates two sources of the same visual. Built-in annotations are added by ctrl or cmd-clicking a graph, stored in Grafana itself against the `-- Grafana --` data source, and fetched by a query that exists on every dashboard. Query-driven annotations come from a data source: any query returning events becomes markers. The first is a person saying "this mattered". The second is a system saying "this happened". Both are necessary and they age differently. Automatic annotations from deploys, config changes and incidents are complete and never stop arriving, which is also their failure mode: a chart with forty deploy markers a day has a picket fence where a signal should be. Manual annotations are sparse, high-value, and depend on someone remembering. Tags are what make the automatic kind survivable, because they let a panel choose which events it cares about. Grafana filters annotation queries by tag for exactly this reason. The other useful distinction is point versus region. A deploy is a moment. A maintenance window, a traffic experiment or a degraded period is a span, and drawing a span as a line loses the duration that was the whole point. Grafana handles this with a **Time regions** query type defining **From** and **To**. ## Use when Charts are read to explain rather than only to monitor, and the causes live in systems the viewer would otherwise have to go and check. ## Don't use when The event stream is high-volume and unfiltered. Forty markers is worse than none, because it converts the chart into a chart with a fence in front of it. ## Trade-offs Annotations occupy the same visual channel as thresholds and anomaly bands, so a chart can quickly have three kinds of vertical furniture competing with the series. They imply causation by adjacency: a marker near a spike reads as the explanation whether or not it is, which is a real analytical hazard on a page people trust. Manual ones are only as good as the discipline behind them, and that discipline decays. And annotations stored in the dashboard rather than in the data are lost when the dashboard is rebuilt. ## Checklist - Where do these events come from, and does anything guarantee they keep arriving? - Are annotations tagged, and does each panel show only the tags it needs? - At the busiest time range, how many markers appear, and is the chart still readable? - Is a span drawn as a span, or flattened into a line? - Does the marker say what happened, or only that something did? - Can the viewer get from a marker to the underlying deploy, ticket or incident? - Do annotations survive the dashboard being rebuilt or duplicated? - Do they compete visually with thresholds and bands on the same chart? - Does a marker near a spike risk implying a cause nobody has verified? - Who can add one, and is that the right set of people? ## Compare **Grafana** splits the pattern cleanly into stored annotations added by hand and query-driven ones from any data source, then filters both by tag, which is the most complete treatment and also the one that most needs someone to curate the tags. **Datadog** treats events as a first-class stream that overlays any graph, so deploys and alerts appear on charts without per-dashboard configuration, at the cost of needing suppression when the stream is noisy. **Honeycomb** leans on markers tied to deploys as the main annotation, on the reasoning that in practice the question is almost always whether a release caused it. **Sentry** goes further and makes the release an object rather than a marker, attaching regressions to it directly, which answers the causal question rather than only placing it on an axis. ## Related Time series is the chart this decorates. Comment and annotate is the collaborative version, where the note is addressed to a person rather than to the record. Threshold line competes for the same visual channel. Status history is the aggregated form of the same events. Zoom and pan is how a viewer gets from a marker to the detail around it. ## Examples ### Grafana (Grafana Labs) The reference implementation for panel grids, template variables, and stat panels; most other tools are defined by how they differ from it. **Demo / Annotations** — captured September 10, 2026, Grafana Play (signed out; no version string exposed). operational, medium density, dark theme, desktop-web. The header on this dashboard says annotations "appear as vertical lines and icons on all graph panels—events visible at a glance", and the panel directly beneath it is the counter-example. Roughly fifty red dashed lines across twenty-four hours, evenly spaced, and the request-rate series behind them is genuinely hard to follow: the fence is denser than the data. Every one of those lines is a real event correctly recorded, and the tag filter in the top left is switched on, so this is the filtered view. That is the whole problem with automatic annotations—they are complete and they never stop arriving, and completeness at this cadence is indistinguishable from noise. The list panel at the bottom is what makes them usable again: the same events, four of them, timestamped and tagged, in a form you can read. Hotspots in this capture: - [Annotation](https://patterns.konigi.com/dashboards/annotation) *(this pattern)* — Fifty deploy markers on a 24-hour chart. Each one is correct and together they are a picket fence. - [Annotation](https://patterns.konigi.com/dashboards/annotation) *(this pattern)* — The same events as a list, tagged release and timestamped. Readable in a way the chart is not. - [Filter bar](https://patterns.konigi.com/dashboards/filter-bar) — The tag filter that makes this survivable, already on. The chart above is the filtered version. - [Time-range picker](https://patterns.konigi.com/dashboards/time-range-picker) — Twenty-four hours, which is what sets the marker density. An hour here would be three lines. ### Kibana (Elastic) Query-first rather than panel-first: the search bar is the primary control and the charts are downstream of it, which inverts Grafana's arrangement. **Dashboards / [Flights] Global Flight Dashboard** — captured September 10, 2026, Elastic demo environment, sample flight data (guest session). analytical, dense density, light theme, desktop-web. Two things on this page are worth arguing with. The first is the table on the right, sorted by delay rate: Chicago/Rockford 100%, Syracuse 100%, Birmingham 75%. A hundred percent of flights delayed is either a catastrophe or one flight, and nothing in the table says which, because the denominator isn't a column. The cells are on a red ramp, so the two rows that are almost certainly a sample of one are the loudest thing in the panel. The second is the tile row: Delayed 25.2%, then beside it "Delayed vs 1 week earlier—76.9%". Seventy-six point nine percent of what? It could be last week's rate, it could be this week as a proportion of last week, it could be the change. Three different numbers, one label, and the tile picks whichever the query returned. What the page gets right is the filtering: a KQL bar for people who know the syntax and three declared controls underneath for people who don't, both visible at once. Hotspots in this capture: - [Ratio and rate](https://patterns.konigi.com/dashboards/ratio-and-rate) — Delay rates up to 100% with no denominator anywhere. One flight and a thousand flights render identically. - [Compare periods](https://patterns.konigi.com/dashboards/compare-periods) — "vs 1 week earlier, 76.9%"—the comparison base is named and the expression isn't. - [Share and embed](https://patterns.konigi.com/dashboards/share-and-embed) — Share, export and full-screen in the header. Whether the range and filters travel with them is the whole question. - [Filter bar](https://patterns.konigi.com/dashboards/filter-bar) — Declared controls under the query bar: two pickers and a price range. Both mechanisms on screen at once. - [Panel grid](https://patterns.konigi.com/dashboards/panel-grid) — Twelve columns, and the biggest panel is a table rather than the headline chart. Size isn't carrying priority here. - [Stacked composition](https://patterns.konigi.com/dashboards/stacked-composition) — Stacked to 100%, so the total is discarded on purpose and only the mix of delay types remains. - [Annotation](https://patterns.konigi.com/dashboards/annotation) *(this pattern)* — Event markers along the top of the series, numbered and grouped, on the data's own axis. - [Header KPI strip](https://patterns.konigi.com/dashboards/header-kpi-strip) — Five tiles in three different sizes and two different layouts, so the row reads as five things. ## Related patterns - [Time series](https://patterns.konigi.com/dashboards/time-series) — The viewer needs to see how a value changed over time and spot the moment it changed. - [Comment and annotate](https://patterns.konigi.com/dashboards/comment-and-annotate) — Two people are looking at the same spike and need to talk about it in place. - [Threshold line and region](https://patterns.konigi.com/dashboards/threshold-line) — A flat metric has a line it must not cross, and the chart should show where that line is. - [Status history](https://patterns.konigi.com/dashboards/status-history) — The viewer needs to see when something was up, down, or degraded, over days, in one row. - [Zoom and pan on time](https://patterns.konigi.com/dashboards/zoom-and-pan) — The interesting thing is ten minutes wide on a seven-day chart. ## Sources - [Grafana, Annotate visualizations](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/annotate-visualizations/) - [Nielsen Norman Group, Visibility of System Status](https://www.nngroup.com/articles/visibility-system-status/) - [Bach et al., Dashboard Design Patterns](https://dashboarddesignpatterns.github.io/patterns.html) --- Screenshots on patterns.konigi.com are reproduced for commentary and criticism. Product names and marks belong to their owners.