Skip to content

Commit d3a5a57

Browse files
authored
[HDX-3044] Add optional note field to alerts (#2210)
## Summary Adds an optional freeform note/reason field to alerts, allowing on-call responders to document why an alert exists, threshold decision history, and links to runbooks. The note field supports markdown formatting. Additionally, this PR brings the saved-search alert UX in line with dashboards by adding visual indicators for firing alerts: - Alert tabs in the saved-search alert modal show a red bell firing indicator alongside the webhook channel icon, using the shared `AlertStatusIcon` component (same pattern as dashboard tiles and app nav) - The Alerts button on the search page shows a red bell icon when at least one alert in the saved search is firing **Changes across the codebase:** - **Backend**: Added `note` field to Mongoose model, Zod validation schemas (shared `alertNoteSchema` in common-utils + API), controller mapping, internal API response formatting, external API type + transformer, and OpenAPI docs - **Frontend (note field)**: Extracted shared `AlertNoteField` component with empty→null onChange transform. Notes are displayed on the `/alerts` page in a collapsible section (hidden by default) with markdown rendering gated behind the expanded state. Custom `<a>` and `<img>` overrides for link security and referrer privacy. - **Frontend (alert status indicators)**: Alert tabs in the saved-search modal show `AlertStatusIcon` alongside the webhook channel icon. The Alerts button on the search page shows `AlertStatusIcon` when alerts are configured. - **E2E tests**: Two Playwright tests covering note creation from both saved-search and dashboard tile flows, with markdown rendering and link attribute verification - **Unit/integration tests**: External API transformer tests for note null/undefined/string handling. Internal API round-trip test for note create, update, and clear. ### Screenshots or video https://github.com/user-attachments/assets/144b86c6-ef0a-4186-be88-49bf415a408c ### How to test locally or on Vercel 1. Create a saved search, open the alerts modal, fill in the note field with markdown (e.g. `Threshold set to **1**. See [runbook](https://example.com).`), and create the alert 2. Navigate to `/alerts` — the alert row should show a "Note" toggle 3. Click the toggle to expand — verify markdown renders correctly (bold, links open in new tab) 4. Repeat from a dashboard tile alert editor 5. Trigger an alert (or set state to ALERT in the DB) — verify the saved-search alert modal tab shows a red bell icon next to the webhook icon, and the Alerts button on the search page shows a red bell icon ### References - Linear Issue: https://linear.app/clickhouse/issue/HDX-3044/add-an-optional-reasonnote-field-to-alerts - Related PRs: None
1 parent b0905dd commit d3a5a57

22 files changed

Lines changed: 449 additions & 10 deletions

File tree

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
'@hyperdx/common-utils': minor
3+
'@hyperdx/api': minor
4+
'@hyperdx/app': minor
5+
---
6+
7+
feat: add optional note field to alerts
8+
9+
Adds a freeform note/reason field to alerts that supports markdown formatting,
10+
allowing on-call responders to document why an alert exists, threshold decision
11+
history, and links to runbooks.
12+
13+
- New `note` field on the Alert model (optional, max 4096 chars, supports
14+
markdown)
15+
- Note textarea in both the saved-search alert modal and the dashboard tile
16+
alert editor
17+
- Notes displayed on the /alerts page in a collapsible section (hidden by
18+
default) with full markdown rendering
19+
- Alert tabs in the saved-search modal show a red bell firing indicator
20+
alongside the webhook channel icon, matching the AlertStatusIcon pattern
21+
used on dashboard tiles and the app nav
22+
- The Alerts button on the search page shows a red bell icon when at least one
23+
alert in the saved search is firing
24+
- External API v2 updated with `note` field in OpenAPI docs

‎packages/api/openapi.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,14 @@
276276
"description": "Alert message template.",
277277
"nullable": true,
278278
"example": "Test Alert Message"
279+
},
280+
"note": {
281+
"type": "string",
282+
"description": "Freeform note for the alert. Supports markdown formatting.",
283+
"nullable": true,
284+
"minLength": 1,
285+
"maxLength": 4096,
286+
"example": "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
279287
}
280288
}
281289
},

‎packages/api/src/controllers/alerts.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -143,11 +143,11 @@ const makeAlert = (alert: AlertInput, userId?: ObjectId): Partial<IAlert> => {
143143
...(userId && { createdBy: userId }),
144144

145145
// Message template
146-
// If they're undefined/null, set it to null so we clear out the field
147-
// due to mongoose behavior:
146+
// Coerce undefined to null so Mongoose clears the field on update.
148147
// https://mongoosejs.com/docs/migrating_to_6.html#removed-omitundefined
149-
name: alert.name == null ? null : alert.name,
150-
message: alert.message == null ? null : alert.message,
148+
name: alert.name ?? null,
149+
message: alert.message ?? null,
150+
note: alert.note ?? null,
151151

152152
// Log alerts
153153
savedSearch: alert.savedSearchId as unknown as ObjectId,

‎packages/api/src/models/alert.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,9 @@ export interface IAlert {
6666
name?: string | null;
6767
message?: string | null;
6868

69+
// Freeform note (supports markdown)
70+
note?: string | null;
71+
6972
// SavedSearch alerts
7073
groupBy?: string;
7174
savedSearch?: ObjectId;
@@ -161,6 +164,10 @@ const AlertSchema = new Schema<IAlert>(
161164
type: String,
162165
required: false,
163166
},
167+
note: {
168+
type: String,
169+
required: false,
170+
},
164171

165172
// Log alerts
166173
savedSearch: {

‎packages/api/src/routers/api/__tests__/alerts.test.ts‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,69 @@ describe('alerts router', () => {
127127
expect(allAlerts.body.data[0].threshold).toBe(10);
128128
});
129129

130+
it('round-trips note through create, update, and clear', async () => {
131+
const dashboard = await agent
132+
.post('/dashboards')
133+
.send(MOCK_DASHBOARD)
134+
.expect(200);
135+
136+
// Create with a note
137+
const alert = await agent
138+
.post('/alerts')
139+
.send({
140+
...makeAlertInput({
141+
dashboardId: dashboard.body.id,
142+
tileId: dashboard.body.tiles[0].id,
143+
webhookId: webhook._id.toString(),
144+
}),
145+
note: 'initial note',
146+
})
147+
.expect(200);
148+
149+
// Verify note is returned in GET list
150+
const listAfterCreate = await agent.get('/alerts').expect(200);
151+
const created = listAfterCreate.body.data.find(
152+
(a: { _id: string }) => a._id === alert.body.data._id,
153+
);
154+
expect(created.note).toBe('initial note');
155+
156+
// Verify note is returned in GET single
157+
const single = await agent
158+
.get(`/alerts/${alert.body.data._id}`)
159+
.expect(200);
160+
expect(single.body.data.note).toBe('initial note');
161+
162+
// Update the note
163+
await agent
164+
.put(`/alerts/${alert.body.data._id}`)
165+
.send({
166+
...alert.body.data,
167+
dashboardId: dashboard.body.id,
168+
note: 'updated note',
169+
})
170+
.expect(200);
171+
172+
const afterUpdate = await agent
173+
.get(`/alerts/${alert.body.data._id}`)
174+
.expect(200);
175+
expect(afterUpdate.body.data.note).toBe('updated note');
176+
177+
// Clear the note
178+
await agent
179+
.put(`/alerts/${alert.body.data._id}`)
180+
.send({
181+
...alert.body.data,
182+
dashboardId: dashboard.body.id,
183+
note: null,
184+
})
185+
.expect(200);
186+
187+
const afterClear = await agent
188+
.get(`/alerts/${alert.body.data._id}`)
189+
.expect(200);
190+
expect(afterClear.body.data.note).toBeNull();
191+
});
192+
130193
it('preserves scheduleStartAt when omitted in updates and clears when null', async () => {
131194
const dashboard = await agent
132195
.post('/dashboards')

‎packages/api/src/routers/api/alerts.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ const formatAlertResponse = (
8080
'state',
8181
'source',
8282
'tileId',
83+
'note',
8384
'createdAt',
8485
'updatedAt',
8586
'executionErrors',

‎packages/api/src/routers/external-api/__tests__/alerts.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ describe('External API Alerts', () => {
222222
id: expect.any(String),
223223
name: 'Format Test Alert',
224224
message: 'This is a test alert for format verification',
225+
note: null,
225226
threshold: 123,
226227
interval: '15m',
227228
source: AlertSource.TILE,

‎packages/api/src/routers/external-api/v2/alerts.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,13 @@ import { alertSchema, objectIdSchema } from '@/utils/zod';
179179
* description: Alert message template.
180180
* nullable: true
181181
* example: "Test Alert Message"
182+
* note:
183+
* type: string
184+
* description: Freeform note for the alert. Supports markdown formatting.
185+
* nullable: true
186+
* minLength: 1
187+
* maxLength: 4096
188+
* example: "Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook)."
182189
*
183190
* AlertResponse:
184191
* allOf:

‎packages/api/src/utils/__tests__/externalApi.test.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,30 @@ describe('utils/externalApi', () => {
4545
expect(translated.scheduleStartAt).toBeUndefined();
4646
});
4747
});
48+
49+
describe('note handling', () => {
50+
it('returns note as null when the value is null', () => {
51+
const alert = createAlertDocument({ note: null });
52+
53+
const translated = translateAlertDocumentToExternalAlert(alert);
54+
55+
expect(translated.note).toBeNull();
56+
});
57+
58+
it('returns note as null when the value is undefined', () => {
59+
const alert = createAlertDocument({ note: undefined });
60+
61+
const translated = translateAlertDocumentToExternalAlert(alert);
62+
63+
expect(translated.note).toBeNull();
64+
});
65+
66+
it('returns note when the value is a non-empty string', () => {
67+
const alert = createAlertDocument({ note: 'threshold raised to 100' });
68+
69+
const translated = translateAlertDocumentToExternalAlert(alert);
70+
71+
expect(translated.note).toBe('threshold raised to 100');
72+
});
73+
});
4874
});

‎packages/api/src/utils/externalApi.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,7 @@ export type ExternalAlert = {
231231
id: string;
232232
name?: string | null;
233233
message?: string | null;
234+
note?: string | null;
234235
threshold: number;
235236
thresholdMax?: number;
236237
interval: AlertInterval;
@@ -329,6 +330,7 @@ export function translateAlertDocumentToExternalAlert(
329330
id: alertObj._id.toString(),
330331
name: alertObj.name,
331332
message: alertObj.message,
333+
note: alertObj.note ?? null,
332334
threshold: alertObj.threshold,
333335
thresholdMax: alertObj.thresholdMax,
334336
interval: alertObj.interval,

0 commit comments

Comments
 (0)