Merge branch 'main' into agent/legacy-span-error-status

Author: kodiakhq[bot]

.changeset/alert-resolve-vanished-group-values.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/api': patch
+---
+
+fix: A grouped alert whose group vanishes from the data now resolves with the group's values in `{{attributes.*}}` (alert title and message) and `{{var.*}}` (webhook body)

.changeset/v2-alerts-list-filters.md

@@ -0,0 +1,5 @@
+---
+'@hyperdx/api': minor
+---
+
+feat: filter the v2 list alerts endpoint by tag, search, source and state

docs/alert-webhook-template-variables.md

@@ -21,7 +21,7 @@ a HyperDX alert without parsing the human-readable message body.
 | `{{thresholdMax}}` | number | Upper bound of a `between`/`outside` condition. Always unset for every other comparator, even if the alert was once a range, so guard it (see below). |
 | `{{value}}` | number | The value that triggered or resolved the alert. |
 | `{{groupKey}}` | string | The breaching group, for a grouped alert. |
-| `{{var}}` | object | The breaching group's values by group-by column or SQL alias. Use one value at a time, e.g. `{{var.customer_id}}`, or `{{var.[service.name]}}` for a name with dots. Empty when not grouped, and on the resolve of a group that has no rows left. |
+| `{{var}}` | object | The breaching group's values by group-by column or SQL alias. Use one value at a time, e.g. `{{var.customer_id}}`, or `{{var.[service.name]}}` for a name with dots. Empty when not grouped. |
 | `{{sourceQuery}}` | string | The condition behind the alert — search expression or SQL (see below). |
 | `{{teamId}}` | string | Team the alert belongs to. |
 | `{{note}}` | string | The alert's freeform note — commonly a runbook link. |

packages/api/openapi.json

@@ -6386,7 +6386,7 @@
     "/api/v2/alerts": {
       "get": {
         "summary": "List Alerts",
-        "description": "Retrieves alerts for the authenticated team (paginated). Results are capped at `limit` (default and maximum 1000). When more records exist than are returned, `meta.total` exceeds `data.length`; clients with large collections must page with `limit`/`offset` to retrieve them all.",
+        "description": "Retrieves alerts for the authenticated team (paginated). Results are capped at `limit` (default and maximum 1000). When more records exist than are returned, `meta.total` exceeds `data.length`; clients with large collections must page with `limit`/`offset` to retrieve them all. Optional filters narrow the result set, and `meta.total` counts only the matching alerts.",
         "operationId": "listAlerts",
         "tags": [
           "Alerts"
@@ -6414,6 +6414,54 @@
               "default": 0
             },
             "description": "Number of alerts to skip before returning results."
+          },
+          {
+            "name": "tag",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 32
+              },
+              "maxItems": 50
+            },
+            "description": "Only return alerts that have any of the given tags. Repeat the parameter to pass several tags. Matches the tags stored on the alert, not tags inherited from the linked dashboard or saved search."
+          },
+          {
+            "name": "search",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "maxLength": 512
+            },
+            "description": "Only return alerts whose display name contains this text (case-insensitive). Matches the display name stored on the alert, not a name derived from the linked dashboard or saved search."
+          },
+          {
+            "name": "source",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/AlertSource"
+              }
+            },
+            "description": "Only return alerts of any of the given sources. Repeat the parameter to pass several sources."
+          },
+          {
+            "name": "state",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/AlertState"
+              }
+            },
+            "description": "Only return alerts in any of the given states. Repeat the parameter to pass several states."
           }
         ],
         "responses": {
@@ -6463,6 +6511,16 @@
               }
             }
           },
+          "400": {
+            "description": "Invalid query parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Unauthorized",
             "content": {

packages/api/src/controllers/alerts.ts

@@ -11,7 +11,7 @@ import {
 } from '@hyperdx/common-utils/dist/guards';
 import { isRangeThresholdType } from '@hyperdx/common-utils/dist/types';
 import { groupBy } from 'lodash';
-import { Types } from 'mongoose';
+import { type FilterQuery, Types } from 'mongoose';
 import { z } from 'zod';
 
 import { recordOnboardingTaskCompletion } from '@/controllers/user';
@@ -389,8 +389,11 @@ export const updateAlert = async (
   return alert;
 };
 
-export const countAlerts = async (teamId: ObjectId) => {
-  return Alert.countDocuments({ team: teamId });
+export const countAlerts = async (
+  teamId: ObjectId,
+  filter: FilterQuery<IAlert> = {},
+) => {
+  return Alert.countDocuments({ ...filter, team: teamId });
 };
 
 export const getAlertById = async (
@@ -506,8 +509,9 @@ const DISPLAY_REF_POPULATE = [
 export const getAlertsWithDisplayRefs = async (
   teamId: ObjectId,
   { limit, offset }: { limit: number; offset: number },
+  filter: FilterQuery<IAlert> = {},
 ) => {
-  return Alert.find({ team: teamId })
+  return Alert.find({ ...filter, team: teamId })
     .sort({ _id: 1 })
     .skip(offset)
     .limit(limit)

packages/api/src/controllers/alertsPage.ts

@@ -11,6 +11,15 @@ import { objectIdSchema, stringListQueryParam, tagsSchema } from '@/utils/zod';
 
 const MAX_PAGE_LIMIT = 500;
 
+/** States an alert document can hold; ERROR only appears on history records. */
+const ALERT_FILTER_STATES = [
+  AlertState.ALERT,
+  AlertState.DISABLED,
+  AlertState.INSUFFICIENT_DATA,
+  AlertState.OK,
+  AlertState.PENDING,
+] as const;
+
 /** The page cursor's payload: the sort key of the last item on the page. */
 const alertsPageCursorSchema = z.object({
   n: z.string().nullable(),
@@ -19,6 +28,34 @@ const alertsPageCursorSchema = z.object({
 
 type AlertsPageCursor = z.infer<typeof alertsPageCursorSchema>;
 
+/** Filter parameters shared by the internal alerts page and the v2 list endpoint. */
+export const alertsFilterShape = {
+  /** A list of tags to filter alerts by. Returns alerts that have any of the specified tags */
+  tag: stringListQueryParam.pipe(tagsSchema).optional(),
+  /** A list of alert sources to filter by. Returns alerts that match any of the specified sources */
+  source: stringListQueryParam
+    .pipe(
+      z
+        .array(z.nativeEnum(AlertSource))
+        .optional()
+        .transform(v => v && [...new Set(v)]),
+    )
+    .optional(),
+  /** A list of alert states to filter by. Returns alerts that match any of the specified states */
+  state: stringListQueryParam
+    .pipe(
+      z
+        .array(z.enum(ALERT_FILTER_STATES))
+        .optional()
+        .transform(v => v && [...new Set(v)]),
+    )
+    .optional(),
+  /** A search string to filter alerts by their display name. Substring, case-insensitive match */
+  search: z.string().trim().max(MAX_ALERT_DISPLAY_NAME_LENGTH).optional(),
+};
+
+export type AlertsFilterParams = z.infer<z.ZodObject<typeof alertsFilterShape>>;
+
 /** Query parameters schema for the list alerts endpoint. */
 export const alertsPageQuerySchema = z
   .object({
@@ -28,18 +65,7 @@ export const alertsPageQuerySchema = z
     cursor: z.string().optional(),
     /** A user ID, to filter for alerts created by a specific user */
     createdBy: objectIdSchema.optional(),
-    /** A list of tags to filter alerts by. Returns alerts that have any of the specified tags */
-    tag: stringListQueryParam.pipe(tagsSchema).optional(),
-    /** A list of alert sources to filter by. Returns alerts that match any of the specified sources */
-    source: stringListQueryParam
-      .pipe(z.array(z.nativeEnum(AlertSource)).optional())
-      .optional(),
-    /** A list of alert states to filter by. Returns alerts that match any of the specified states */
-    state: stringListQueryParam
-      .pipe(z.array(z.nativeEnum(AlertState)).optional())
-      .optional(),
-    /** A search string to filter alerts by their display name. Substring, case-insensitive match */
-    search: z.string().trim().max(MAX_ALERT_DISPLAY_NAME_LENGTH).optional(),
+    ...alertsFilterShape,
   })
   .superRefine((query, ctx) => {
     if (query.cursor == null) {
@@ -64,19 +90,13 @@ export const alertsPageQuerySchema = z
 
 export type AlertsPageParams = z.infer<typeof alertsPageQuerySchema>;
 
-/**
- * Mongo filters for a single page.
- */
-export function buildAlertsPageFilter(
+/** Mongo filter for the shared filter parameters, scoped to the team. */
+export function buildAlertsFilter(
   teamId: ObjectId | string,
-  params: AlertsPageParams,
+  params: AlertsFilterParams,
 ): FilterQuery<IAlert> {
   const filter: FilterQuery<IAlert> = { team: teamId };
 
-  if (params.createdBy != null) {
-    filter.createdBy = params.createdBy;
-  }
-
   if (params.tag != null) {
     filter.tags = { $in: params.tag };
   }
@@ -101,6 +121,22 @@ export function buildAlertsPageFilter(
     };
   }
 
+  return filter;
+}
+
+/**
+ * Mongo filters for a single page.
+ */
+export function buildAlertsPageFilter(
+  teamId: ObjectId | string,
+  params: AlertsPageParams,
+): FilterQuery<IAlert> {
+  const filter = buildAlertsFilter(teamId, params);
+
+  if (params.createdBy != null) {
+    filter.createdBy = params.createdBy;
+  }
+
   const cursor = params.cursor
     ? decodeCursor(params.cursor, alertsPageCursorSchema)
     : null;

packages/api/src/models/alertHistory.ts

@@ -32,6 +32,25 @@ export interface IAlertHistoryAnalytics {
   notificationTargets?: AlertNotificationTargetTiming[];
 }
 
+/** One group-by column and its value, stored as a pair. */
+export type GroupValue = { key: string; value: string };
+
+export const attributesToGroupValues = (
+  attributes: Record<string, string>,
+): GroupValue[] | undefined => {
+  const entries = Object.entries(attributes);
+  return entries.length > 0
+    ? entries.map(([key, value]) => ({ key, value }))
+    : undefined;
+};
+
+export const groupValuesToAttributes = (
+  groupValues: GroupValue[] | null | undefined,
+): Record<string, string> | undefined =>
+  groupValues?.length
+    ? Object.fromEntries(groupValues.map(v => [v.key, v.value]))
+    : undefined;
+
 export interface IAlertHistory {
   alert: ObjectId;
   counts: number;
@@ -40,6 +59,13 @@ export interface IAlertHistory {
   lastValues: { startTime: Date; count: number }[];
   group?: string; // For group-by alerts, stores the group identifier
   fired?: boolean;
+  /**
+   * Group-by values of a group-by alert's group. Kept so a group that later
+   * vanishes from the data still resolves with its values, which the joined
+   * `group` string cannot be parsed back into. Stored as pairs because column
+   * names may contain dots, which Mongo would read as nested paths in a key.
+   */
+  groupValues?: GroupValue[];
   /**
    * Errors recorded for this evaluation window. Present on ERROR-state rows
    * (query/processing failures where no normal history is written) and on
@@ -85,6 +111,17 @@ const AlertHistorySchema = new Schema<IAlertHistory>({
     type: Boolean,
     required: false,
   },
+  groupValues: {
+    type: [
+      {
+        _id: false,
+        key: { type: String, required: true },
+        value: { type: String },
+      },
+    ],
+    required: false,
+    default: undefined,
+  },
   errors: {
     type: [
       {