Chart Notes & Markers
Every metric chart has a marker rail: a thin strip above the plot that shows what happened while the chart was recorded. Most markers are written by people as notes, such as "Rolled back v2.3.1" or "Maintenance: kernel upgrade". The rest come from the system: alert windows, deploys, config changes and agent offline events.
Notes are the main marker type. The automatic types that would flood a chart are off by default.
Notes
Scope: where a note shows
A note is attached to one of three levels. You cannot change the level after the note is created.
| Scope | Shows on |
|---|---|
| Host | That host's charts. |
| Environment | The environment's charts and the charts of every host in it, including hosts added later. |
| Client | The client's charts and every environment and host chart under it. |
So an environment chart shows its own notes, the notes on each of its hosts, and its client's notes. A host chart shows its own notes, plus the notes on its environment and client.
Kind and shape
- Kind:
note(default),maintenanceordeploy. Thedeploykind is for deploys you record by hand. There is noincidentkind, because incidents come only from real alerts. - Point or range: a note marks one moment, or a time range when it has an end time (
ends_at, which must be after the start). A range note is drawn as a light band across the plot, with its symbol at the start. - Text: 1–500 characters. The limit counts characters, not bytes, so a Cyrillic note has as much room as a Latin one.
Adding a note
Three ways to open the note composer:
- Double-click a chart. The note is placed at that moment.
- Hover a chart and press
N. The note is placed at the hovered moment, or at the end of the window if you have not hovered yet. - Click Add note in the dashboard toolbar. The note is placed at now.
All three appear only if you can add a note on at least one level of the page (you hold annotations:write there). A read-only viewer sees notes but gets no button, and double-click and N do nothing, rather than a form they could not save. The same goes for Keep as note on a deploy card.
In the composer you choose the kind, point or range, the time or times, and Show on (scope). Show on lists only the page's own level and the levels above it. A host page offers this host, its environment and its client. An environment page offers the environment and its client. A client page offers the client only. If you cannot use a level, the option is disabled and the reason is shown next to it. For example, you may lack permission there, or the page's environment or client is still loading.
Auto-refresh pauses while the composer is open. A click outside the composer does not close it, so a half-written note is not lost.
Who can do what
| Action | Who |
|---|---|
| See a note | Anyone who can see the chart (metrics:read on it). A client note is visible to everyone who holds metrics:read on any environment of that client. |
| Create | annotations:write at the note's scope. A host or environment note accepts an environment-scoped grant for that environment. A client note needs a client-wide grant, because an environment grant is narrower than the note. The notes need a signed-in user: API keys and service accounts cannot author notes (403 "notes need a signed-in user"). |
| Edit | The author only, and only while they can still see the note. Super-admins are not exempt. You can edit the kind, time range and text. The scope and the author never change. |
| Delete | The author (while they can see the note), a moderator who holds annotations:write at the note's scope (client-wide for a client note), or a super-admin. The note card asks you to confirm before it deletes. |
annotations:write ships with the Admin and Engineer system roles. Client roles stay read-only. Before this release, notes checked only that you belonged to the host's or environment's client, not your role: a read-only member could create and list notes, and nothing was audited.
If a note is outside your scope, the API answers 404 for it, not 403, so a guessed id does not confirm that the note exists.
Audit
Creating, editing and deleting a note each write an audit-log entry: annotation_created, annotation_updated or annotation_deleted. The resource type is annotation. An edit records the text, kind and times before and after the change. A delete records whether the author or a moderator deleted it.
Automatic markers
| Marker | Rail symbol | Default | What it is |
|---|---|---|---|
| Alerts | triangle and a shaded window, coloured by severity (red P1/P2, amber P3, grey P4/P5 and unknown) | on | Alert groups whose firing window overlaps the chart range. The symbol sits at the fire time, and the band runs to the resolution time, or to the end of the window while the alert is still open. An alert that fired before the window but is still open inside it keeps its symbol, pinned to the left edge ("before this window"). |
| Deploys | diamond (red when failed) | off | Completed deploys only: ArgoCD sync and sync failed, a GitHub release, and a GitLab tag. GitLab webhooks send tag pushes and never a "release" event, so a tag stands in for a release. Pushes, merge requests and CI runs are never drawn. |
| Config changes | grey square | off | File changes detected by the agent's change detection. |
| Agent offline | grey ring | on | The agent stopped reporting. |
Toggle the automatic markers under Events in the dashboard's Customize panel (⚙). The toggles are stored per browser. You cannot turn notes off.
Console's own audit events (config pushed, credential updated, …) are no longer drawn on charts. Before this release they were labelled "Deploy". They are listed on the Changes page.
Client dashboards show notes, alerts and deploys, but not config changes or agent offline, because the events timeline has no client-level filter.
Who sees which markers
The markers need the same permission as the chart itself (metrics:read). Each automatic type also has its own check at the chart's scope:
- Alerts need
alerts:read. - Deploys need
changes:read.
If you lack one of those permissions, that type is left empty and the chart still renders. You do not get an error.
On a host chart, only that host's alerts are shown.
A deploy that belongs to the client as a whole, with no environment (for example a webhook source that is not mapped to an environment), is shown on every chart of that client. A client-wide alert (no environment and no host) is shown on the client chart only. Charts show these client-wide rows even to users whose grants cover only some environments, although the Alerts and Changes list pages hide them from those users. When a host is deleted, its deploys that carry no environment become client-wide in the same way.
Cards
Click a symbol, or focus it and press Enter, to open its card. Symbols that are close together merge into a "+N" bubble, and its card lists each marker.
- Note: the kind, scope, text, author and time, and Edit or Delete when you are allowed to use them.
- Alert: severity, a Firing chip while the alert is open, the name, how long it fired ("Firing 12 min · 14:03 – 14:15" or "Firing since 14:03"), and Open alert.
- Deploy: the source, app and revision, a summary, a link to the provider (shown only for http/https URLs), and Keep as note.
- Config change / Agent offline: the event title.
Keep as note opens the composer prefilled from the deploy: kind deploy, its summary as the text, and its time. The note attaches at the chart's own level. Use it when a deploy matters enough to keep on the chart after you turn the Deploys toggle off.
API
| Method | Path | Description |
|---|---|---|
GET | /api/v1/annotations?host_id=…|environment_id=…|client_id=…&start=…&end=… | The notes a chart inherits in [start, end]: point notes inside the range and range notes that overlap it. Pass exactly one target. Keeps the newest 500 notes, returned oldest first. The range can span at most 30 days (400 beyond, like /chart-markers), so a chart over a longer custom range shows no notes or markers — the dashboard does not request them and says "Notes and markers show for ranges up to 30 days" beside the time picker. |
POST | /api/v1/annotations | Create: {scope, host_id | environment_id | client_id, kind?, timestamp, ends_at?, text}. 201 with the note. |
PUT | /api/v1/annotations/{id} | Author edit: {kind?, timestamp, ends_at?, text}. If you leave out kind, the note keeps its kind. If you leave out ends_at, a range note becomes a point note. 200 with the note. |
DELETE | /api/v1/annotations/{id} | Author, moderator or super-admin. 204. |
GET | /api/v1/chart-markers?host_id=…|environment_id=…|client_id=…&start=…&end=…&types=alerts,deploys | {alerts: [...], deploys: [...]}: alert windows that overlap the range and completed deploys inside it. Keeps the newest 200 alerts and 100 deploys, returned oldest first. The range can span at most 30 days. |
An alert group that is marked resolved but has no resolution time is treated as ending when it fired, so it is never drawn as open forever.
Metrics: proxima_annotations_created_total, proxima_annotations_updated_total, proxima_annotations_deleted_total, proxima_annotations_query_seconds.