Add a dated marker to every chart whenever something that changes the measurement happens: a new scanner, a rule change, a scope change, a data source update or a threshold edit. Keep the markers in a short change log with an owner. Without them, trend lines mix real change with measurement change.
Why annotation matters
A trend is only meaningful if the instrument is the same across the period. Security tooling changes constantly. A chart that jumps in March might reflect a real surge or a new rule pack, and readers cannot tell which.
Honest dashboards separate "the world changed" from "we measured differently."
Events that deserve a marker
| Event | Likely effect on charts |
|---|---|
| New scanner or engine upgrade | Findings count shifts up or down |
| Rule or policy change | Findings or gate failures change |
| Scope change: repos, images, services added or removed | Coverage and counts both move |
| Advisory database update, large batch | Backfilled findings appear at once |
| Severity rule change, CVSS version switch | Band counts redistribute |
| Dashboard threshold or definition edit | Colours and targets shift |
| Team reorganisation | Ownership splits change |
| Incident or industry event | Short lived attention effects |
CVSS is a good example of a definition issue. FIRST's v4.0 guide asks that scores carry a label showing which metric groups they used, such as CVSS-B for base only. If you change which score you chart, the series is no longer continuous, and the annotation should say so.
What goes in a change log entry
Keep it to a few fields.
- Date and time.
- What changed, in plain words.
- Which charts it affects.
- Expected direction of effect.
- Owner.
Short entries get written. Long ones do not.
Steps to set it up
- Create a single change log, visible from the dashboard.
- Make adding an entry part of the change process for scanners, rules and scope.
- Draw vertical markers on trend charts from the log.
- When the change is large, restate the previous period under the new method for comparison where you can.
- At review time, read the markers before reading the trend.
- Mark gaps in data explicitly rather than drawing a smooth line across them.
Backfill and restate
If you adopt a better method, consider recalculating history so the series is continuous. If you cannot, split the chart into two series and label them. A visible break is more honest than a quiet stitch.
Common mistake
Teams annotate improvements and forget regressions. Include every measurement change, whatever it does to the picture. Selective annotation is a form of spin.
Safeguard offers SBOM and dependency scanning, reachability analysis and policy gates. You can run a free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
Look for the points in a monitoring timeline where a change in scope or detection would deserve a marker.
Quick check
What is the minimum to annotate?
Scanner and rule changes, scope changes and any definition or threshold edit.
Should we restate old data after a method change?
Where you can. If not, split the series and label the break.
Sources
Last reviewed: 19 October 2026.
