Annotations
Mark deploys and releases as vertical lines on your time-series charts so you can tie a change in the data to the moment it happened.
Annotations are vertical marker lines you drop onto your charts to record when something happened, like a deploy or a release. When a metric jumps or dips, an annotation lets you see at a glance whether it lines up with a change you made.
Why you would use this
Say you ship version 2.3.0 and your error count doubles ten minutes later.
If you added an annotation for that deploy, the line sits right at the spike
and the cause is obvious. Without it, you are left guessing what changed.
How they work
Open annotations with the Annotations button on any dashboard. Each annotation is a single point in time with a label, and it draws as a vertical line across your time-series charts at that moment.
An annotation is not tied to one chart or one dashboard. It belongs to an environment (production or development), so once you add it, it shows up on every dashboard for that environment. Add a "deploy" marker once and it appears everywhere you look at that environment's data.
What an annotation has
Prop
Type
The label can be 1 to 120 characters, and the description up to 500. Colour is a hex value, and if you leave it out the line is purple.
Adding an annotation
Open the annotations panel
On the dashboard for the environment you want to mark, click the Annotations button.
Fill in the details
Give it a label (like v2.3.0 deploy), an optional description
(like Rolled out the new matchmaking service), pick the time it happened, and
optionally choose a colour. Leave the colour blank to use the default purple.
Save
The marker now appears on every time-series chart in that environment, so long as its time falls inside the chart's visible range.
When a marker is not drawn
An annotation only shows up where it makes sense, so it will not always be visible:
- On non-time charts. Markers only draw on time-bucketed charts (the ones with a time axis, like time series, area, line, and bar over time). A categorical chart, such as a breakdown bar or pie, has no time axis, so nothing is drawn there.
- Outside the visible window. If the annotation's time is before or after the chart's current time range, its line falls off the edge and is not shown. Widen the dashboard time range to bring it back into view.
Who can manage them
Any workspace member can see annotations on the charts they are viewing. Creating, editing, and deleting annotations needs the Developer role or higher, in line with the rest of the dashboard tools. See Roles and permissions for the full breakdown.
API reference
Annotations are managed by the app from your signed-in session. Reading a list is open to any member; creating, updating, and deleting need the Developer role or higher.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/annotations?environment= | List annotations for an environment. |
| POST | /v1/annotations | Create an annotation. |
| PATCH | /v1/annotations/:id | Update an annotation. |
| DELETE | /v1/annotations/:id | Delete an annotation. |
All paths live under https://topstats.gg. See the full
API reference for every endpoint.