feat: add rate of change as alert trigger condition

.changeset/rate-of-change-alerts.md

@@ -0,0 +1,7 @@
+---
+'@hyperdx/common-utils': minor
+'@hyperdx/api': minor
+'@hyperdx/app': minor
+---
+
+feat: add rate of change as alert trigger condition alongside existing threshold rules

packages/api/src/controllers/alerts.ts

@@ -6,7 +6,9 @@ import { z } from 'zod';
 
 import type { ObjectId } from '@/models';
 import Alert, {
+  AlertChangeType,
   AlertChannel,
+  AlertConditionType,
   AlertInterval,
   AlertSource,
   AlertThresholdType,
@@ -24,6 +26,8 @@ export type AlertInput = {
   id?: string;
   source?: AlertSource;
   channel: AlertChannel;
+  conditionType?: AlertConditionType;
+  changeType?: AlertChangeType;
   interval: AlertInterval;
   scheduleOffsetMinutes?: number;
   scheduleStartAt?: string | null;
@@ -141,6 +145,8 @@ const makeAlert = (alert: AlertInput, userId?: ObjectId): Partial<IAlert> => {
     source: alert.source,
     threshold: alert.threshold,
     thresholdType: alert.thresholdType,
+    conditionType: alert.conditionType,
+    changeType: alert.changeType,
     ...(userId && { createdBy: userId }),
 
     // Message template

packages/api/src/models/alert.ts

@@ -9,6 +9,16 @@ export enum AlertThresholdType {
   BELOW = 'below',
 }
 
+export enum AlertConditionType {
+  THRESHOLD = 'threshold',
+  RATE_OF_CHANGE = 'rate_of_change',
+}
+
+export enum AlertChangeType {
+  ABSOLUTE = 'absolute',
+  PERCENTAGE = 'percentage',
+}
+
 export enum AlertState {
   ALERT = 'ALERT',
   DISABLED = 'DISABLED',
@@ -44,6 +54,8 @@ export enum AlertSource {
 export interface IAlert {
   id: string;
   channel: AlertChannel;
+  conditionType?: AlertConditionType;
+  changeType?: AlertChangeType;
   interval: AlertInterval;
   scheduleOffsetMinutes?: number;
   scheduleStartAt?: Date | null;
@@ -87,6 +99,17 @@ const AlertSchema = new Schema<IAlert>(
       enum: AlertThresholdType,
       required: false,
     },
+    conditionType: {
+      type: String,
+      enum: AlertConditionType,
+      default: AlertConditionType.THRESHOLD,
+      required: false,
+    },
+    changeType: {
+      type: String,
+      enum: AlertChangeType,
+      required: false,
+    },
     interval: {
       type: String,
       required: true,

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

@@ -3,10 +3,18 @@ import {
   getServer,
   makeAlertInput,
   makeRawSqlTile,
+  makeSavedSearchAlertInput,
   makeTile,
   randomMongoId,
 } from '@/fixtures';
-import Alert, { AlertSource, AlertThresholdType } from '@/models/alert';
+import Alert, {
+  AlertChangeType,
+  AlertConditionType,
+  AlertSource,
+  AlertThresholdType,
+} from '@/models/alert';
+import { SavedSearch } from '@/models/savedSearch';
+import { Source } from '@/models/source';
 import Webhook, { WebhookDocument, WebhookService } from '@/models/webhook';
 
 const MOCK_TILES = [makeTile(), makeTile(), makeTile(), makeTile(), makeTile()];
@@ -607,4 +615,153 @@ describe('alerts router', () => {
       })
       .expect(400);
   });
+
+  describe('rate of change alerts', () => {
+    it('creates a rate-of-change alert with absolute change type', async () => {
+      const dashboard = await agent
+        .post('/dashboards')
+        .send({
+          name: 'RoC Dashboard',
+          tiles: MOCK_TILES,
+          tags: [],
+        })
+        .expect(200);
+
+      const resp = await agent
+        .post('/alerts')
+        .send({
+          ...makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+          conditionType: AlertConditionType.RATE_OF_CHANGE,
+          changeType: AlertChangeType.ABSOLUTE,
+        })
+        .expect(200);
+
+      expect(resp.body.data.conditionType).toBe(
+        AlertConditionType.RATE_OF_CHANGE,
+      );
+      expect(resp.body.data.changeType).toBe(AlertChangeType.ABSOLUTE);
+    });
+
+    it('creates a rate-of-change alert with percentage change type', async () => {
+      const dashboard = await agent
+        .post('/dashboards')
+        .send({
+          name: 'RoC Dashboard',
+          tiles: MOCK_TILES,
+          tags: [],
+        })
+        .expect(200);
+
+      const resp = await agent
+        .post('/alerts')
+        .send({
+          ...makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+          conditionType: AlertConditionType.RATE_OF_CHANGE,
+          changeType: AlertChangeType.PERCENTAGE,
+        })
+        .expect(200);
+
+      expect(resp.body.data.conditionType).toBe(
+        AlertConditionType.RATE_OF_CHANGE,
+      );
+      expect(resp.body.data.changeType).toBe(AlertChangeType.PERCENTAGE);
+    });
+
+    it('rejects rate-of-change alert without changeType', async () => {
+      const dashboard = await agent
+        .post('/dashboards')
+        .send({
+          name: 'RoC Dashboard',
+          tiles: MOCK_TILES,
+          tags: [],
+        })
+        .expect(200);
+
+      await agent
+        .post('/alerts')
+        .send({
+          ...makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+          conditionType: AlertConditionType.RATE_OF_CHANGE,
+        })
+        .expect(400);
+    });
+
+    it('creates a threshold alert without conditionType (backward compat)', async () => {
+      const dashboard = await agent
+        .post('/dashboards')
+        .send({
+          name: 'Backward Compat Dashboard',
+          tiles: MOCK_TILES,
+          tags: [],
+        })
+        .expect(200);
+
+      const resp = await agent
+        .post('/alerts')
+        .send(
+          makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+        )
+        .expect(200);
+
+      expect(resp.body.data.conditionType).toBeUndefined();
+    });
+
+    it('updates an existing alert to rate-of-change', async () => {
+      const dashboard = await agent
+        .post('/dashboards')
+        .send({
+          name: 'Update RoC Dashboard',
+          tiles: MOCK_TILES,
+          tags: [],
+        })
+        .expect(200);
+
+      const createResp = await agent
+        .post('/alerts')
+        .send(
+          makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+        )
+        .expect(200);
+
+      const alertId = createResp.body.data._id;
+
+      const updateResp = await agent
+        .put(`/alerts/${alertId}`)
+        .send({
+          ...makeAlertInput({
+            dashboardId: dashboard.body.id,
+            tileId: MOCK_TILES[0].id,
+            webhookId: webhook._id.toString(),
+          }),
+          conditionType: AlertConditionType.RATE_OF_CHANGE,
+          changeType: AlertChangeType.PERCENTAGE,
+        })
+        .expect(200);
+
+      expect(updateResp.body.data.conditionType).toBe(
+        AlertConditionType.RATE_OF_CHANGE,
+      );
+      expect(updateResp.body.data.changeType).toBe(AlertChangeType.PERCENTAGE);
+    });
+  });
 });

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

@@ -42,6 +42,8 @@ router.get('/', async (req, res: AlertsExpRes, next) => {
           scheduleStartAt: alert.scheduleStartAt?.toISOString() ?? undefined,
           threshold: alert.threshold,
           thresholdType: alert.thresholdType,
+          conditionType: alert.conditionType,
+          changeType: alert.changeType,
           channel: { type: alert.channel.type ?? undefined },
           state: alert.state,
           source: alert.source,

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

@@ -3,7 +3,12 @@ import { ObjectId } from 'mongodb';
 import request from 'supertest';
 
 import { getLoggedInAgent, getServer } from '../../../fixtures';
-import { AlertSource, AlertThresholdType } from '../../../models/alert';
+import {
+  AlertChangeType,
+  AlertConditionType,
+  AlertSource,
+  AlertThresholdType,
+} from '../../../models/alert';
 import Alert from '../../../models/alert';
 import Dashboard from '../../../models/dashboard';
 import { SavedSearch } from '../../../models/savedSearch';
@@ -883,4 +888,47 @@ describe('External API Alerts', () => {
         .expect(401);
     });
   });
+
+  describe('Rate of Change Alerts', () => {
+    it('should create and retrieve a rate-of-change alert', async () => {
+      const { alert } = await createTestAlert({
+        conditionType: AlertConditionType.RATE_OF_CHANGE,
+        changeType: AlertChangeType.PERCENTAGE,
+      });
+
+      expect(alert.conditionType).toBe(AlertConditionType.RATE_OF_CHANGE);
+      expect(alert.changeType).toBe(AlertChangeType.PERCENTAGE);
+
+      const getResp = await authRequest(
+        'get',
+        `${ALERTS_BASE_URL}/${alert.id}`,
+      ).expect(200);
+
+      expect(getResp.body.data.conditionType).toBe(
+        AlertConditionType.RATE_OF_CHANGE,
+      );
+      expect(getResp.body.data.changeType).toBe(AlertChangeType.PERCENTAGE);
+    });
+
+    it('should reject rate-of-change without changeType', async () => {
+      const dashboard = await createTestDashboard();
+      const webhook = await createTestWebhook();
+
+      await authRequest('post', ALERTS_BASE_URL)
+        .send({
+          dashboardId: dashboard._id.toString(),
+          tileId: dashboard.tiles[0].id,
+          threshold: 50,
+          interval: '5m',
+          source: AlertSource.TILE,
+          thresholdType: AlertThresholdType.ABOVE,
+          conditionType: AlertConditionType.RATE_OF_CHANGE,
+          channel: {
+            type: 'webhook',
+            webhookId: webhook._id.toString(),
+          },
+        })
+        .expect(400);
+    });
+  });
 });