chore: generate openapi specs

Assisted-by: Claude Fable 5.1

.github/CODEOWNERS

@@ -209,6 +209,10 @@ go.mod @therealpandey
 /frontend/src/types/api/alerts/ @SigNoz/pulse-frontend
 /frontend/src/providers/Alert.tsx @SigNoz/pulse-frontend
 /frontend/src/constants/alerts.ts @SigNoz/pulse-frontend
+/frontend/src/container/PlannedDowntime/ @SigNoz/pulse-frontend
+/frontend/src/hooks/alerts/ @SigNoz/pulse-frontend
+/frontend/src/container/Home/AlertRules/ @SigNoz/pulse-frontend
+/frontend/src/container/Home/__tests__/AlertRules.test.tsx @SigNoz/pulse-frontend
 
 ## Notification Channels
 /frontend/src/pages/ChannelsEdit/ @SigNoz/pulse-frontend
@@ -217,6 +221,11 @@ go.mod @therealpandey
 /frontend/src/container/FormAlertChannels/ @SigNoz/pulse-frontend
 /frontend/src/hooks/notificationChannels/ @SigNoz/pulse-frontend
 
+## List filter + views (dashboards and alerts lists)
+/frontend/src/components/ListFilter/ @SigNoz/pulse-frontend
+/frontend/src/components/ListViews/ @SigNoz/pulse-frontend
+/frontend/src/hooks/listViews/ @SigNoz/pulse-frontend
+
 ## OpenAPI Schema - Generated
 /frontend/src/api/generated/services/ @therealpandey @vikrantgupta25 @srikanthccv
 /docs/api/openapi.yml @therealpandey @vikrantgupta25 @srikanthccv

.github/workflows/build-community.yaml

@@ -63,7 +63,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
       GO_NAME: signoz-community
       GO_INPUT_ARTIFACT_CACHE_KEY: community-jsbuild-${{ github.sha }}
       GO_INPUT_ARTIFACT_PATH: frontend/build

.github/workflows/build-enterprise.yaml

@@ -89,7 +89,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
       GO_INPUT_ARTIFACT_CACHE_KEY: enterprise-jsbuild-${{ github.sha }}
       GO_INPUT_ARTIFACT_PATH: frontend/build
       GO_BUILD_CONTEXT: ./cmd/enterprise

.github/workflows/build-staging.yaml

@@ -95,7 +95,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
       GO_INPUT_ARTIFACT_CACHE_KEY: staging-jsbuild-${{ github.sha }}
       GO_INPUT_ARTIFACT_PATH: frontend/build
       GO_BUILD_CONTEXT: ./cmd/enterprise

.github/workflows/goci.yaml

@@ -22,7 +22,7 @@ jobs:
     with:
       PRIMUS_REF: main
       GO_TEST_CONTEXT: ./...
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
   fmt:
     if: |
       github.event_name == 'merge_group' ||
@@ -32,7 +32,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
   lint:
     if: |
       github.event_name == 'merge_group' ||
@@ -42,7 +42,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
   deps:
     if: |
       github.event_name == 'merge_group' ||
@@ -52,7 +52,7 @@ jobs:
     secrets: inherit
     with:
       PRIMUS_REF: main
-      GO_VERSION: 1.24
+      GO_VERSION: 1.25
   semconv-generated:
     if: |
       github.event_name == 'merge_group' ||
@@ -65,7 +65,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: check-semconv-generated-files
         run: make semconv-check
   build:
@@ -80,7 +80,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: qemu-install
         uses: docker/setup-qemu-action@v3
       - name: aarch64-install
@@ -116,7 +116,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: generate-openapi
         run: |
           go run cmd/enterprise/*.go generate openapi
@@ -133,7 +133,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: generate-authz
         run: |
           go run cmd/enterprise/*.go generate authz
@@ -150,7 +150,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: generate-web-settings
         run: |
           go run cmd/enterprise/*.go generate config web-settings
@@ -167,7 +167,7 @@ jobs:
       - name: go-install
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: generate-transaction-groups
         run: |
           go run cmd/enterprise/*.go generate config transaction-groups

.github/workflows/gor-signoz-community.yaml

@@ -66,7 +66,7 @@ jobs:
       - name: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: cross-compilation-tools
         if: matrix.os == 'ubuntu-latest'
         run: |
@@ -130,7 +130,7 @@ jobs:
       - name: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
 
       # copy the caches from build
       - name: get-sha

.github/workflows/gor-signoz.yaml

@@ -75,7 +75,7 @@ jobs:
       - name: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
       - name: cross-compilation-tools
         if: matrix.os == 'ubuntu-latest'
         run: |
@@ -138,7 +138,7 @@ jobs:
       - name: setup-go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.25"
 
       # copy the caches from build
       - name: get-sha

docs/api/openapi.yml

@@ -32729,6 +32729,305 @@ paths:
                   requestType: time_series
                   schemaVersion: v1
                   start: 1640995200000
+              function_anomaly_request_rate:
+                description: 'anomaly is the one function with named arguments. seasonality
+                  says which past periods predict the current value: hourly, daily
+                  or weekly, daily when absent. z_score_threshold is how many standard
+                  deviations from the prediction count as an anomaly. It has no default:
+                  a request without it gets bounds of zero width, so send it. 3 is
+                  the value the UI sends. The response carries, next to the values,
+                  a predicted series, an upper and a lower bound series and an anomaly
+                  score series. The scoring runs in the enterprise build; the community
+                  build returns the series unchanged.'
+                summary: 'anomaly: request rate scored against its daily pattern'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: http.server.duration.count
+                          spaceAggregation: sum
+                          timeAggregation: rate
+                        functions:
+                        - args:
+                          - name: seasonality
+                            value: daily
+                          - name: z_score_threshold
+                            value: 3
+                          name: anomaly
+                        groupBy:
+                        - fieldContext: resource
+                          name: service.name
+                        name: A
+                        signal: metrics
+                        stepInterval: 300s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_cumulativesum_errors_so_far:
+                description: cumulativeSum replaces each point with the sum of every
+                  point up to and including it, so a per-step count becomes a running
+                  total whose first point is the first count. It takes no arguments.
+                  The total resets with the window, so a longer time range gives a
+                  larger final value; it is a view of the window, not a counter.
+                summary: 'cumulativeSum: 5xx responses since the start of the window'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - alias: server_errors
+                          expression: count()
+                        filter:
+                          expression: http.response.status_code >= 500
+                        functions:
+                        - name: cumulativeSum
+                        groupBy:
+                        - fieldContext: resource
+                          name: service.name
+                        name: A
+                        signal: traces
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_cutoffmin_hide_idle_hosts:
+                description: The four threshold functions take one number. cutOffMin
+                  and cutOffMax remove the points below or above the threshold, so
+                  an idle host disappears from the chart instead of drawing a line
+                  along the bottom. clampMin and clampMax keep the points and replace
+                  the value with the threshold, which caps spikes without hiding them.
+                  system.cpu.utilization is a ratio, so 0.05 is 5%.
+                summary: 'cutOffMin: drop hosts below 5% CPU from the chart'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: system.cpu.utilization
+                          spaceAggregation: avg
+                          timeAggregation: avg
+                        functions:
+                        - args:
+                          - value: 0.05
+                          name: cutOffMin
+                        groupBy:
+                        - fieldContext: resource
+                          name: host.name
+                        name: A
+                        signal: metrics
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_ewma_smoothed_latency:
+                description: 'ewma3, ewma5 and ewma7 replace each point with an exponentially
+                  weighted average of the point and the points before it. The number
+                  in the name is the window the default weight is derived from: alpha
+                  = 2 / (n + 1), so 0.5, 0.333 and 0.25. One optional argument overrides
+                  alpha; a value close to 1 follows the raw series, a value close
+                  to 0 smooths harder. 0.3 here smooths a little more than ewma5''s
+                  default.'
+                summary: 'ewma5: smoothed p95 latency'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: http.server.duration.bucket
+                          spaceAggregation: p95
+                        functions:
+                        - args:
+                          - value: 0.3
+                          name: ewma5
+                        groupBy:
+                        - fieldContext: resource
+                          name: service.name
+                        name: A
+                        signal: metrics
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_fillzero_sparse_errors:
+                description: A count over sparse events returns a point only for steps
+                  that had a match, so a chart of failed spans has gaps where nothing
+                  failed. fillZero adds a zero at every missing step. With no arguments
+                  the server fills the request window at the query's step, which is
+                  the common case. The three optional arguments are start, end and
+                  step in milliseconds, for callers that want to fill a different
+                  grid.
+                summary: 'fillZero: a zero at every step with no failed spans'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - alias: failed_spans
+                          expression: count()
+                        filter:
+                          expression: has_error = true
+                        functions:
+                        - name: fillZero
+                        groupBy:
+                        - fieldContext: resource
+                          name: service.name
+                        name: A
+                        signal: traces
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_log10_network_bytes:
+                description: log2 and log10 replace each value with its logarithm,
+                  so a loopback device moving kilobytes and an uplink moving gigabytes
+                  fit on one chart. They take no arguments. Zero and negative values
+                  have no logarithm and are not drawn. absolute, also without arguments,
+                  is the usual companion for a signed series before a logarithm.
+                summary: 'log10: network throughput across devices that differ by
+                  orders of magnitude'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: system.network.io
+                          spaceAggregation: sum
+                          timeAggregation: rate
+                        filter:
+                          expression: direction = 'transmit'
+                        functions:
+                        - name: log10
+                        groupBy:
+                        - fieldContext: attribute
+                          name: device
+                        name: A
+                        signal: metrics
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_median_despiked_request_rate:
+                description: median3, median5 and median7 replace each point with
+                  the median of the surrounding 3, 5 or 7 points. A spike that lasts
+                  one step vanishes, a shift that lasts longer than half the window
+                  stays. The first and last half window, 2 points each for median5,
+                  have no full window and keep their values, so the newest spike stays
+                  visible; a series shorter than the window is returned unchanged.
+                  They take no arguments. Use them when the raw series is noisy and
+                  the chart is for a trend, not for catching the spike.
+                summary: 'median5: request rate without one-step spikes'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: http.server.duration.count
+                          spaceAggregation: sum
+                          timeAggregation: rate
+                        functions:
+                        - name: median5
+                        groupBy:
+                        - fieldContext: resource
+                          name: service.name
+                        name: A
+                        signal: metrics
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_runningdiff_disk_growth:
+                description: 'runningDiff turns a gauge into the change between consecutive
+                  points, so a filesystem usage gauge becomes bytes written per step.
+                  It takes no arguments and drops the first point of the window, since
+                  that point has nothing to difference against; the server reads one
+                  step before the window to keep the first interval. Functions apply
+                  in order: clampMin with 0 runs on the differences and replaces the
+                  negative value a cleanup or a volume reset produces with zero.'
+                summary: 'runningDiff then clampMin: bytes written to disk per step'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - metricName: system.filesystem.usage
+                          spaceAggregation: sum
+                          timeAggregation: latest
+                        filter:
+                          expression: state = 'used'
+                        functions:
+                        - name: runningDiff
+                        - args:
+                          - value: 0
+                          name: clampMin
+                        groupBy:
+                        - fieldContext: resource
+                          name: host.name
+                        name: A
+                        signal: metrics
+                        stepInterval: 60s
+                      type: builder_query
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
+              function_timeshift_week_over_week:
+                description: timeShift moves every point of its query forward by the
+                  argument, in seconds, so a series read from the past lands on the
+                  current timestamps. B here reads the hour exactly seven days (604800
+                  s) before the requested window and comes back on this week's timestamps,
+                  so it overlays A on a chart and the formula can subtract it point
+                  by point. The argument is positive; it says how far back to read.
+                summary: 'timeShift: this week''s error logs next to last week''s'
+                value:
+                  compositeQuery:
+                    queries:
+                    - spec:
+                        aggregations:
+                        - alias: errors
+                          expression: count()
+                        filter:
+                          expression: severity_text = 'ERROR'
+                        name: A
+                        signal: logs
+                        stepInterval: 60s
+                      type: builder_query
+                    - spec:
+                        aggregations:
+                        - alias: errors
+                          expression: count()
+                        filter:
+                          expression: severity_text = 'ERROR'
+                        functions:
+                        - args:
+                          - value: 604800
+                          name: timeShift
+                        name: B
+                        signal: logs
+                        stepInterval: 60s
+                      type: builder_query
+                    - spec:
+                        expression: A - B
+                        name: F1
+                      type: builder_formula
+                  end: 1640998800000
+                  requestType: time_series
+                  schemaVersion: v1
+                  start: 1640995200000
               logs_raw:
                 summary: 'Raw: fetch raw log records'
                 value:

frontend/src/container/AIAssistant/components/ChatInput/ChatInput.tsx

@@ -21,14 +21,15 @@ import {
 	useListDashboardsForUserV2,
 } from 'api/generated/services/dashboard';
 import {
-	getListRulesQueryKey,
-	useListRules,
+	getListRulesV3QueryKey,
+	useListRulesV3,
 } from 'api/generated/services/rules';
 import type {
 	DashboardtypesListedDashboardForUserV2DTO,
 	ListDashboardsForUserV2200,
 	ListDashboardsForUserV2Params,
-	ListRules200,
+	ListRulesV3200,
+	ListRulesV3Params,
 } from 'api/generated/services/sigNoz.schemas';
 import logEvent from 'api/common/logEvent';
 import { useQueryService } from 'hooks/useQueryService';
@@ -179,6 +180,9 @@ const VOICE_UNAVAILABLE_KEY = 'ai-assistant-voice-unavailable';
  */
 const DASHBOARD_LIST_PARAMS: ListDashboardsForUserV2Params = { limit: 1000 };
 
+/** Same as dashboards. 200 is the most the rules list returns per call. */
+const ALERT_RULE_LIST_PARAMS: ListRulesV3Params = { limit: 200 };
+
 function dashboardTitle(
 	dashboard: DashboardtypesListedDashboardForUserV2DTO,
 ): string {
@@ -755,7 +759,7 @@ export default function ChatInput({
 		data: alertsResponse,
 		isLoading: isAlertsLoading,
 		isError: isAlertsError,
-	} = useListRules({
+	} = useListRulesV3(ALERT_RULE_LIST_PARAMS, {
 		query: {
 			enabled: isContextPickerOpen && activeContextCategory === 'Alerts',
 			staleTime: Infinity,
@@ -804,10 +808,10 @@ export default function ChatInput({
 				}
 			}
 			if (ctx.type === 'alert' && ctx.resourceId) {
-				const cached = queryClient.getQueryData<ListRules200>(
-					getListRulesQueryKey(),
+				const cached = queryClient.getQueryData<ListRulesV3200>(
+					getListRulesV3QueryKey(ALERT_RULE_LIST_PARAMS),
 				);
-				const rule = cached?.data?.find((r) => r.id === ctx.resourceId);
+				const rule = cached?.data.rules.find((r) => r.id === ctx.resourceId);
 				if (rule?.alert) {
 					return rule.alert;
 				}
@@ -835,8 +839,8 @@ export default function ChatInput({
 					value: dashboardTitle(dashboard),
 				})) ?? [],
 			Alerts:
-				alertsResponse?.data
-					?.filter((alertRule) => Boolean(alertRule.alert))
+				alertsResponse?.data.rules
+					.filter((alertRule) => Boolean(alertRule.alert))
 					.map((alertRule) => ({
 						id: alertRule.id,
 						value: alertRule.alert,
@@ -1059,6 +1063,7 @@ export default function ChatInput({
 												color="secondary"
 												size="sm"
 												id={`ai-context-tab-${category}`}
+												testId={`ai-context-tab-${category}`}
 												// Single stable panel id shared by every tab: only the
 												// active category's tabpanel is rendered, so per-category
 												// `aria-controls` ids would point at nonexistent nodes

frontend/src/container/AIAssistant/components/ChatInput/__tests__/ChatInput.alertsPicker.test.tsx

@@ -0,0 +1,70 @@
+import {
+	alertRulesFixture,
+	listRulesV3Response,
+} from 'mocks-server/__mockdata__/alert_rules';
+import { rest, server } from 'mocks-server/server';
+import { render, screen, userEvent } from 'tests/test-utils';
+
+jest.mock('api/generated/services/dashboard', () => ({
+	useListDashboardsForUserV2: (): unknown => ({
+		data: undefined,
+		isLoading: false,
+		isError: false,
+	}),
+	getListDashboardsForUserV2QueryKey: (): string[] => ['dashboards'],
+}));
+
+jest.mock('hooks/useQueryService', () => ({
+	useQueryService: (): unknown => ({
+		data: [],
+		isLoading: false,
+		isFetching: false,
+		isError: false,
+	}),
+}));
+
+jest.mock('../../../hooks/useSpeechRecognition', () => ({
+	useSpeechRecognition: (): unknown => ({
+		isListening: false,
+		isSupported: false,
+		permission: 'prompt',
+		start: jest.fn(),
+		discard: jest.fn(),
+	}),
+}));
+
+jest.mock('../../../hooks/useAIAssistantAnalyticsContext', () => ({
+	useAIAssistantAnalyticsContext: (): unknown => ({
+		threadId: undefined,
+		page: '/',
+		mode: 'sidepane',
+	}),
+}));
+
+// eslint-disable-next-line import/first
+import ChatInput from '../ChatInput';
+
+describe('ChatInput — alerts context picker', () => {
+	it('lists the rules from one v3 rules request', async () => {
+		const [first, second] = alertRulesFixture;
+		const requests: string[] = [];
+		server.use(
+			rest.get('http://localhost/api/v3/rules', (req, res, ctx) => {
+				requests.push(req.url.search);
+				return res(
+					ctx.status(200),
+					ctx.json(listRulesV3Response([first, second], req.url.searchParams)),
+				);
+			}),
+		);
+
+		render(<ChatInput onSend={jest.fn()} />);
+
+		await userEvent.click(screen.getByRole('button', { name: /add context/i }));
+		await userEvent.click(await screen.findByTestId('ai-context-tab-Alerts'));
+
+		await expect(screen.findByText(first.alert)).resolves.toBeInTheDocument();
+		expect(screen.getByText(second.alert)).toBeInTheDocument();
+		expect(requests).toStrictEqual(['?limit=200']);
+	});
+});

frontend/src/container/AIAssistant/components/ChatInput/__tests__/ChatInput.prefill.test.tsx

@@ -12,8 +12,12 @@ jest.mock('api/generated/services/dashboard', () => ({
 }));
 
 jest.mock('api/generated/services/rules', () => ({
-	useListRules: (): unknown => ({ data: [], isLoading: false, isError: false }),
-	getListRulesQueryKey: (): string[] => ['rules'],
+	useListRulesV3: (): unknown => ({
+		data: undefined,
+		isLoading: false,
+		isError: false,
+	}),
+	getListRulesV3QueryKey: (): string[] => ['rules'],
 }));
 
 jest.mock('hooks/useQueryService', () => ({

frontend/src/container/CreateAlertV2/Footer/Footer.tsx

@@ -18,7 +18,7 @@ import { buildCreateAlertRulePayload, validateCreateAlertState } from './utils';
 import './styles.scss';
 import {
 	invalidateGetRuleByID,
-	invalidateListRules,
+	invalidateListRulesV3,
 } from 'api/generated/services/rules';
 import { useQueryClient } from 'react-query';
 
@@ -137,7 +137,7 @@ function Footer(): JSX.Element {
 				{
 					onSuccess: () => {
 						void invalidateGetRuleByID(queryClient, { id: ruleId });
-						void invalidateListRules(queryClient);
+						void invalidateListRulesV3(queryClient);
 
 						toast.success('Alert rule updated successfully');
 						safeNavigate('/alerts');

frontend/src/container/Home/AlertRules/AlertRules.tsx

@@ -1,24 +1,22 @@
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import { Button, Skeleton } from 'antd';
 import { Badge } from '@signozhq/ui/badge';
 import logEvent from 'api/common/logEvent';
-import { useListRules } from 'api/generated/services/rules';
-import type { RuletypesRuleDTO } from 'api/generated/services/sigNoz.schemas';
+import type { RuletypesListableRuleDTO } from 'api/generated/services/sigNoz.schemas';
 import { QueryParams } from 'constants/query';
 import ROUTES from 'constants/routes';
 import { AppLink } from 'lib/router/AppLink';
 import { navigate } from 'lib/router/navigation';
 import { useAppLocation } from 'lib/router/useAppLocation';
-import { mapQueryDataFromApi } from 'lib/newQueryBuilder/queryBuilderMappers/mapQueryDataFromApi';
 import { ArrowRight, ArrowUpRight, Plus } from '@signozhq/icons';
 import Card from 'periscope/components/Card/Card';
 import { useAppContext } from 'providers/App/App';
-import { toCompositeMetricQuery } from 'types/api/alerts/convert';
 import { USER_ROLES } from 'types/roles';
 
 import beaconUrl from '@/assets/Icons/beacon.svg';
 
 import { getItemIcon } from '../constants';
+import { useHomeAlertRules } from './useHomeAlertRules';
 
 export default function AlertRules({
 	onUpdateChecklistDoneItem,
@@ -28,49 +26,19 @@ export default function AlertRules({
 	loadingUserPreferences: boolean;
 }): JSX.Element {
 	const { user } = useAppContext();
-	const [rulesExist, setRulesExist] = useState(false);
-
-	const [sortedAlertRules, setSortedAlertRules] = useState<RuletypesRuleDTO[]>(
-		[],
-	);
 
 	const location = useAppLocation();
 	const params = new URLSearchParams(location.search);
 
 	// Fetch Alerts
-	const {
-		data: alerts,
-		isError,
-		isLoading,
-	} = useListRules({
-		query: { cacheTime: 0 },
-	});
+	const { rules: alertRules, isError, isLoading } = useHomeAlertRules();
+	const rulesExist = alertRules.length > 0;
 
 	useEffect(() => {
-		const rules = alerts?.data ?? [];
-		setRulesExist(rules.length > 0);
-
-		const sortedRules = [...rules].sort((a, b) => {
-			// First, prioritize firing alerts
-			if (a.state === 'firing' && b.state !== 'firing') {
-				return -1;
-			}
-			if (a.state !== 'firing' && b.state === 'firing') {
-				return 1;
-			}
-
-			// Then sort by updatedAt timestamp
-			return (
-				new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime()
-			);
-		});
-
-		if (sortedRules.length > 0 && !loadingUserPreferences) {
+		if (rulesExist && !loadingUserPreferences) {
 			onUpdateChecklistDoneItem('SETUP_ALERTS');
 		}
-
-		setSortedAlertRules(sortedRules.slice(0, 5));
-	}, [alerts, onUpdateChecklistDoneItem, loadingUserPreferences]);
+	}, [rulesExist, onUpdateChecklistDoneItem, loadingUserPreferences]);
 
 	const emptyStateCard = (): JSX.Element => (
 		<div className="empty-state-container">
@@ -95,7 +63,7 @@ export default function AlertRules({
 								className="periscope-btn secondary"
 								icon={<Plus size={16} />}
 								onClick={(): void => {
-									logEvent('Homepage: Create alert rule clicked', {});
+									void logEvent('Homepage: Create alert rule clicked', {});
 								}}
 							>
 								Create Alert Rule
@@ -106,7 +74,7 @@ export default function AlertRules({
 							type="link"
 							className="learn-more-link"
 							onClick={(): void => {
-								logEvent('Homepage: Learn more clicked', {
+								void logEvent('Homepage: Learn more clicked', {
 									source: 'Alert Rules',
 								});
 
@@ -125,26 +93,13 @@ export default function AlertRules({
 		</div>
 	);
 
-	const onEditHandler = (record: RuletypesRuleDTO) => (): void => {
-		logEvent('Homepage: Alert clicked', {
+	const onEditHandler = (record: RuletypesListableRuleDTO) => (): void => {
+		void logEvent('Homepage: Alert clicked', {
 			ruleId: record.id,
 			ruleName: record.alert,
 			ruleState: record.state,
 		});
 
-		const compositeQuery = mapQueryDataFromApi(
-			toCompositeMetricQuery(record.condition.compositeQuery),
-		);
-		params.set(
-			QueryParams.compositeQuery,
-			encodeURIComponent(JSON.stringify(compositeQuery)),
-		);
-
-		const panelType = record.condition.compositeQuery.panelType;
-		if (panelType) {
-			params.set(QueryParams.panelTypes, panelType);
-		}
-
 		params.set(QueryParams.ruleId, record.id);
 
 		navigate(`${ROUTES.ALERT_OVERVIEW}?${params.toString()}`);
@@ -153,11 +108,12 @@ export default function AlertRules({
 	const renderAlertRules = (): JSX.Element => (
 		<div className="alert-rules-container home-data-item-container">
 			<div className="alert-rules-list">
-				{sortedAlertRules.map((rule) => (
+				{alertRules.map((rule) => (
 					<div
 						role="button"
 						tabIndex={0}
 						className="alert-rule-item home-data-item"
+						data-testid={`home-alert-rule-${rule.id}`}
 						key={rule.id}
 						onClick={onEditHandler(rule)}
 						onKeyDown={(e): void => {
@@ -239,7 +195,7 @@ export default function AlertRules({
 								type="link"
 								className="periscope-btn link learn-more-link"
 								onClick={(): void => {
-									logEvent('Homepage: All alert rules clicked', {});
+									void logEvent('Homepage: All alert rules clicked', {});
 								}}
 							>
 								All Alert Rules <ArrowRight size={12} />

frontend/src/container/Home/AlertRules/useHomeAlertRules.ts

@@ -0,0 +1,64 @@
+import { useMemo } from 'react';
+import { useListRulesV3 } from 'api/generated/services/rules';
+import {
+	type ListRulesV3200,
+	type ListRulesV3Params,
+	RuletypesAlertStateDTO,
+	type RuletypesListableRuleDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { GeneratedAPIInstance } from 'api/generatedAPIInstance';
+
+const HOME_ALERT_RULES_LIMIT = 5;
+
+const FIRING_RULES_PARAMS: ListRulesV3Params = {
+	states: [RuletypesAlertStateDTO.firing],
+	limit: HOME_ALERT_RULES_LIMIT,
+};
+
+interface HomeAlertRules {
+	rules: RuletypesListableRuleDTO[];
+	isLoading: boolean;
+	isError: boolean;
+}
+
+export function useHomeAlertRules(): HomeAlertRules {
+	const firing = useListRulesV3(FIRING_RULES_PARAMS, {
+		query: {
+			cacheTime: 0,
+			// The backend binds repeated `states=` keys; axios' default sends `states[]=`.
+			queryFn: ({ signal }) =>
+				GeneratedAPIInstance<ListRulesV3200>({
+					url: '/api/v3/rules',
+					method: 'GET',
+					params: FIRING_RULES_PARAMS,
+					paramsSerializer: { indexes: null },
+					signal,
+				}),
+		},
+	});
+	const firingRules = firing.data?.data.rules;
+	const latest = useListRulesV3(
+		{ limit: HOME_ALERT_RULES_LIMIT },
+		{
+			query: {
+				cacheTime: 0,
+				enabled:
+					firingRules !== undefined && firingRules.length < HOME_ALERT_RULES_LIMIT,
+			},
+		},
+	);
+
+	const rules = useMemo(() => {
+		const firingIds = new Set(firingRules?.map(({ id }) => id));
+		const others = (latest.data?.data.rules ?? []).filter(
+			({ id }) => !firingIds.has(id),
+		);
+		return [...(firingRules ?? []), ...others].slice(0, HOME_ALERT_RULES_LIMIT);
+	}, [firingRules, latest.data]);
+
+	return {
+		rules,
+		isLoading: firing.isLoading || latest.isLoading,
+		isError: firing.isError || latest.isError,
+	};
+}

frontend/src/container/Home/__tests__/AlertRules.test.tsx

@@ -0,0 +1,119 @@
+import {
+	RuletypesAlertStateDTO,
+	type RuletypesRuleDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { QueryParams } from 'constants/query';
+import ROUTES from 'constants/routes';
+import { navigate } from 'lib/router/navigation';
+import {
+	alertRulesFixture,
+	listRulesV3Response,
+} from 'mocks-server/__mockdata__/alert_rules';
+import { rest, server } from 'mocks-server/server';
+import { render, screen, userEvent } from 'tests/test-utils';
+
+import AlertRules from '../AlertRules/AlertRules';
+
+jest.mock('lib/router/navigation', () => ({
+	...jest.requireActual('lib/router/navigation'),
+	navigate: jest.fn(),
+}));
+
+const rule = (id: string, state: RuletypesAlertStateDTO): RuletypesRuleDTO => ({
+	...alertRulesFixture[0],
+	id,
+	alert: `${id} rule`,
+	state,
+});
+
+const burning = rule('burning', RuletypesAlertStateDTO.firing);
+const quiet = rule('quiet', RuletypesAlertStateDTO.inactive);
+const waiting = rule('waiting', RuletypesAlertStateDTO.pending);
+
+const serveRules = (
+	rules: RuletypesRuleDTO[],
+	rulesForLatest = rules,
+): string[] => {
+	const requestedStates: string[] = [];
+	server.use(
+		rest.get('http://localhost/api/v3/rules', (req, res, ctx) => {
+			const states = req.url.searchParams.getAll('states').join();
+			requestedStates.push(states);
+			return res(
+				ctx.status(200),
+				ctx.json(
+					listRulesV3Response(
+						states === 'firing' ? rules : rulesForLatest,
+						req.url.searchParams,
+					),
+				),
+			);
+		}),
+	);
+	return requestedStates;
+};
+
+const renderAlertRules = (): void => {
+	render(
+		<AlertRules
+			onUpdateChecklistDoneItem={jest.fn()}
+			loadingUserPreferences={false}
+		/>,
+	);
+};
+
+const renderedRuleIds = (): (string | undefined)[] =>
+	screen.getAllByTestId(/^home-alert-rule-/).map((row) => row.dataset.testid);
+
+describe('Home alert rules', () => {
+	it('lists firing rules first, then the latest others, and opens the clicked rule', async () => {
+		const requestedStates = serveRules([quiet, burning, waiting]);
+		renderAlertRules();
+
+		await expect(
+			screen.findByTestId('home-alert-rule-waiting'),
+		).resolves.toBeInTheDocument();
+		expect(renderedRuleIds()).toStrictEqual([
+			'home-alert-rule-burning',
+			'home-alert-rule-quiet',
+			'home-alert-rule-waiting',
+		]);
+		expect(requestedStates).toStrictEqual(['firing', '']);
+
+		const user = userEvent.setup({ pointerEventsCheck: 0 });
+		await user.click(screen.getByTestId('home-alert-rule-burning'));
+		expect(navigate).toHaveBeenCalledWith(
+			`${ROUTES.ALERT_OVERVIEW}?${QueryParams.ruleId}=burning`,
+		);
+	});
+
+	it('skips the latest rules request when 5 rules are firing', async () => {
+		const firing = Array.from({ length: 5 }, (_, index) =>
+			rule(`firing-${index}`, RuletypesAlertStateDTO.firing),
+		);
+		const requestedStates = serveRules([quiet, ...firing]);
+		renderAlertRules();
+
+		await expect(
+			screen.findByTestId('home-alert-rule-firing-4'),
+		).resolves.toBeInTheDocument();
+		expect(renderedRuleIds()).toStrictEqual(
+			firing.map(({ id }) => `home-alert-rule-${id}`),
+		);
+		expect(requestedStates).toStrictEqual(['firing']);
+	});
+
+	it('shows a rule once when it stops firing between the two requests', async () => {
+		const settled = { ...burning, state: RuletypesAlertStateDTO.inactive };
+		serveRules([burning], [settled, quiet]);
+		renderAlertRules();
+
+		await expect(
+			screen.findByTestId('home-alert-rule-quiet'),
+		).resolves.toBeInTheDocument();
+		expect(renderedRuleIds()).toStrictEqual([
+			'home-alert-rule-burning',
+			'home-alert-rule-quiet',
+		]);
+	});
+});

frontend/src/container/PlannedDowntime/PlannedDowntime.tsx

@@ -16,11 +16,11 @@ import {
 	useDeleteDowntimeScheduleByID,
 	useListDowntimeSchedules,
 } from 'api/generated/services/downtimeschedules';
-import { useListRules } from 'api/generated/services/rules';
 import type { AlertmanagertypesPlannedMaintenanceDTO } from 'api/generated/services/sigNoz.schemas';
 import { ColumnSelector } from 'components/TanStackTableView';
 import TextToolTip from 'components/TextToolTip';
 import dayjs from 'dayjs';
+import { useListAllRules } from 'hooks/alerts/useListAllRules';
 import useDebouncedFn from 'hooks/useDebouncedFunction';
 import { useNotifications } from 'hooks/useNotifications';
 import useUrlQuery from 'hooks/useUrlQuery';
@@ -55,9 +55,7 @@ export function PlannedDowntime(): JSX.Element {
 		isError,
 		isLoading,
 		isFetching: isFetchingAlerts,
-	} = useListRules({
-		query: { cacheTime: 0 },
-	});
+	} = useListAllRules({ cacheTime: 0 });
 	const [isOpen, setIsOpen] = React.useState(false);
 	const [form] = Form.useForm();
 	const { user } = useAppContext();
@@ -73,7 +71,7 @@ export function PlannedDowntime(): JSX.Element {
 	const downtimeSchedules = useListDowntimeSchedules();
 	const alertOptions = React.useMemo(
 		() =>
-			alertsData?.data?.map((i) => ({
+			alertsData?.map((i) => ({
 				label: i.alert,
 				value: i.id,
 			})),
@@ -181,7 +179,7 @@ export function PlannedDowntime(): JSX.Element {
 	};
 
 	const refetchAllSchedules = (): void => {
-		downtimeSchedules.refetch();
+		void downtimeSchedules.refetch();
 	};
 
 	const {

frontend/src/container/PlannedDowntime/__test__/PlannedDowntime.test.tsx

@@ -4,6 +4,7 @@ import { fireEvent, screen } from '@testing-library/react';
 import type {
 	ListDowntimeSchedules200,
 	RenderErrorResponseDTO,
+	RuletypesListableRuleDTO,
 } from 'api/generated/services/sigNoz.schemas';
 import {
 	AlertmanagertypesRepeatOnDTO,
@@ -126,19 +127,19 @@ jest.mock('api/generated/services/downtimeschedules', () => ({
 }));
 
 let mockRulesState: {
-	data?: { data: Array<{ id: number | string; alert: string }> };
+	data?: Pick<RuletypesListableRuleDTO, 'id' | 'alert'>[];
 	isError: boolean;
 	isLoading: boolean;
 	isFetching: boolean;
 } = {
-	data: { data: [] },
+	data: [],
 	isError: false,
 	isLoading: false,
 	isFetching: false,
 };
 
-jest.mock('api/generated/services/rules', () => ({
-	useListRules: (): typeof mockRulesState => mockRulesState,
+jest.mock('hooks/alerts/useListAllRules', () => ({
+	useListAllRules: (): typeof mockRulesState => mockRulesState,
 }));
 
 describe('PlannedDowntime Component', () => {
@@ -151,7 +152,7 @@ describe('PlannedDowntime Component', () => {
 		});
 		mockDowntimeQueryResult.data = MOCK_DOWNTIME_RESPONSE;
 		mockRulesState = {
-			data: { data: [] },
+			data: [],
 			isError: false,
 			isLoading: false,
 			isFetching: false,
@@ -362,7 +363,7 @@ describe('PlannedDowntime Component', () => {
 
 	it('shows "Unknown rule" when scoped rule IDs cannot be resolved (Bug 56)', async () => {
 		mockRulesState = {
-			data: { data: [] },
+			data: [],
 			isError: false,
 			isLoading: false,
 			isFetching: false,
@@ -387,14 +388,7 @@ describe('PlannedDowntime Component', () => {
 
 	it('shows resolved alert rule name when scoped rule ID exists', async () => {
 		mockRulesState = {
-			data: {
-				data: [
-					{
-						id: 'rule-42',
-						alert: 'Disk Space High',
-					} as any,
-				],
-			},
+			data: [{ id: 'rule-42', alert: 'Disk Space High' }],
 			isError: false,
 			isLoading: false,
 			isFetching: false,

frontend/src/hooks/alerts/__tests__/useListAllRules.test.tsx

@@ -0,0 +1,40 @@
+import {
+	alertRulesFixture,
+	listRulesV3Response,
+} from 'mocks-server/__mockdata__/alert_rules';
+import { rest, server } from 'mocks-server/server';
+import { AllTheProviders, renderHook, waitFor } from 'tests/test-utils';
+
+import { useListAllRules } from '../useListAllRules';
+
+const TOTAL = 250;
+
+const rules = Array.from({ length: TOTAL }, (_, index) => ({
+	...alertRulesFixture[0],
+	id: `rule-${index}`,
+	alert: `Rule ${index}`,
+}));
+
+describe('useListAllRules', () => {
+	it('fetches every page past the 200-rule cap', async () => {
+		const offsets: string[] = [];
+		server.use(
+			rest.get('http://localhost/api/v3/rules', (req, res, ctx) => {
+				offsets.push(req.url.searchParams.get('offset') ?? '');
+				return res(
+					ctx.status(200),
+					ctx.json(listRulesV3Response(rules, req.url.searchParams)),
+				);
+			}),
+		);
+
+		const { result } = renderHook(() => useListAllRules(), {
+			wrapper: AllTheProviders,
+		});
+
+		await waitFor(() => expect(result.current.isSuccess).toBe(true));
+		expect(result.current.data).toHaveLength(TOTAL);
+		expect(result.current.data?.[TOTAL - 1]?.id).toBe(`rule-${TOTAL - 1}`);
+		expect(offsets.sort()).toStrictEqual(['0', '200']);
+	});
+});

frontend/src/hooks/alerts/useListAllRules.ts

@@ -0,0 +1,40 @@
+import { useQuery, UseQueryOptions, UseQueryResult } from 'react-query';
+import {
+	getListRulesV3QueryKey,
+	listRulesV3,
+} from 'api/generated/services/rules';
+import type { RuletypesListableRuleDTO } from 'api/generated/services/sigNoz.schemas';
+import { range } from 'lodash-es';
+
+// The list API clamps any larger limit to 200.
+const PAGE_SIZE = 200;
+
+export const LIST_ALL_RULES_QUERY_KEY = [...getListRulesV3QueryKey(), 'all'];
+
+function fetchPage(offset: number): ReturnType<typeof listRulesV3> {
+	return listRulesV3({ limit: PAGE_SIZE, offset });
+}
+
+// TODO(AshwinBhatkal): temporary. Replace with server-side search plus a lookup of saved rules by ID once
+// /api/v3/rules can filter by IDs: https://github.com/SigNoz/pulse-pod/issues/715
+async function fetchAllRules(): Promise<RuletypesListableRuleDTO[]> {
+	const first = await fetchPage(0);
+	const rest = await Promise.all(
+		range(PAGE_SIZE, first.data.total, PAGE_SIZE).map(fetchPage),
+	);
+
+	return [...first.data.rules, ...rest.flatMap((page) => page.data.rules)];
+}
+
+export function useListAllRules(
+	options?: Omit<
+		UseQueryOptions<RuletypesListableRuleDTO[], Error>,
+		'queryKey' | 'queryFn'
+	>,
+): UseQueryResult<RuletypesListableRuleDTO[], Error> {
+	return useQuery<RuletypesListableRuleDTO[], Error>({
+		queryKey: LIST_ALL_RULES_QUERY_KEY,
+		queryFn: fetchAllRules,
+		...options,
+	});
+}

frontend/src/pages/AlertDetails/hooks.tsx

@@ -10,7 +10,7 @@ import {
 	getGetRuleByIDQueryKey,
 	getGetRuleHistoryTimelineQueryOptions,
 	invalidateGetRuleByID,
-	invalidateListRules,
+	invalidateListRulesV3,
 	updateRuleByID,
 	useGetRuleByID,
 	useGetRuleHistoryOverallStatus,
@@ -443,7 +443,7 @@ export const useAlertRuleClone = ({
 					message: `Success`,
 				});
 
-				await invalidateListRules(queryClient);
+				await invalidateListRulesV3(queryClient);
 
 				params.set(QueryParams.ruleId, response.data.id);
 				navigate(`${ROUTES.ALERT_OVERVIEW}?${params.toString()}`);
@@ -494,7 +494,7 @@ export const useAlertRuleUpdate = ({
 						data: { ...existingRule.data, alert: intermediateName },
 					});
 				}
-				void invalidateListRules(queryClient);
+				void invalidateListRulesV3(queryClient);
 				notifications.success({ message: 'Alert renamed successfully' });
 			},
 			onError: (error) => {

frontend/src/pages/AlertList/PlannedDowntime/stories/PlannedDowntime.stories.mocks.tsx

@@ -17,10 +17,8 @@ import {
 	FIRST_DOWNTIME_NAME,
 } from './__story_mockdata__/plannedDowntime';
 
-import {
-	alertRulesResponse,
-	RULE_MAX,
-} from '../../stories/__story_mockdata__/alerts';
+import { alertRulesPage } from '../../AlertRules/stories/__story_mockdata__/ruleViews';
+import { RULE_MAX } from '../../stories/__story_mockdata__/alerts';
 import { AlertListSubTabs, AlertListTabs } from '../../types';
 
 const LIST = 'Planned downtime · list';
@@ -86,18 +84,20 @@ export const plannedDowntimeMocks = defineStoryMocks({
 				res(ctx.status(200), ctx.json({ status: 'success', data: null })),
 		),
 
-		rest.get('http://localhost/api/v2/rules', (_req, res, ctx) =>
-			values.rulesState === 'error'
-				? res(ctx.status(500), ctx.json({ status: 'error' }))
-				: res(
-						ctx.json(
-							alertRulesResponse(values.silencedRules, {
-								severity: 'mixed',
-								state: 'mixed',
-							}),
-						),
+		rest.get('http://localhost/api/v3/rules', (req, res, ctx) => {
+			if (values.rulesState === 'error') {
+				return res(ctx.status(500), ctx.json({ status: 'error' }));
+			}
+			return res(
+				ctx.json(
+					alertRulesPage(
+						values.silencedRules,
+						{ severity: 'mixed', state: 'mixed' },
+						req.url.searchParams,
 					),
-		),
+				),
+			);
+		}),
 	],
 	config: () => ({
 		route: `/alerts?tab=${AlertListTabs.CONFIGURATION}&subTab=${AlertListSubTabs.PLANNED_DOWNTIME}`,

frontend/src/pages/HomePage/stories/HomePage.stories.mocks.tsx

@@ -3,6 +3,7 @@
  * Do not hand-edit: regenerate instead.
  */
 
+import { listRulesV3Response } from 'mocks-server/__mockdata__/alert_rules';
 import { rest } from 'msw';
 
 import {
@@ -156,11 +157,13 @@ export const homeMocks = defineStoryMocks({
 		),
 
 		rest.get(
-			'http://localhost/api/v2/rules',
-			response.json(() => ({
-				status: 'success',
-				data: buildAlertRules(values.alertRules),
-			})),
+			'http://localhost/api/v3/rules',
+			response.json((req) =>
+				listRulesV3Response(
+					buildAlertRules(values.alertRules),
+					req.url.searchParams,
+				),
+			),
 		),
 
 		rest.get(

pkg/alertmanager/alertmanagernotify/email/email_test.go

@@ -11,6 +11,7 @@ import (
 	"log/slog"
 	"net"
 	"net/http"
+	"net/textproto"
 	"net/url"
 	"os"
 	"strconv"
@@ -706,7 +707,9 @@ func TestEmailRejected(t *testing.T) {
 
 	// Send the alert to mock SMTP server.
 	retry, err := e.Notify(context.Background(), firingAlert)
-	require.ErrorContains(t, err, "501 5.5.4 Rejected!")
+	var smtpErr *textproto.Error
+	require.ErrorAs(t, err, &smtpErr)
+	assert.Equal(t, 501, smtpErr.Code)
 	assert.True(t, retry)
 	require.NoError(t, srv.Shutdown(ctx))
 

pkg/apiserver/signozapiserver/querier.go

@@ -30,7 +30,7 @@ func (provider *provider) addQuerierRoutes(router *mux.Router) error {
 		Description:        "Execute a composite query over a time range. Supports builder queries (traces, logs, metrics), formulas, trace operators, PromQL, and ClickHouse SQL.",
 		Request:            new(qbtypes.QueryRangeRequest),
 		RequestContentType: "application/json",
-		RequestExamples: []handler.OpenAPIExample{
+		RequestExamples: append([]handler.OpenAPIExample{
 			{
 				Name:    "traces_time_series",
 				Summary: "Time series: count spans grouped by service",
@@ -598,7 +598,7 @@ func (provider *provider) addQuerierRoutes(router *mux.Router) error {
 					},
 				},
 			},
-		},
+		}, queryRangeFunctionExamples()...),
 		Response:            new(qbtypes.QueryRangeResponse),
 		ResponseContentType: "application/json",
 		SuccessStatusCode:   http.StatusOK,

pkg/apiserver/signozapiserver/querier_examples.go

@@ -0,0 +1,202 @@
+package signozapiserver
+
+import "github.com/SigNoz/signoz/pkg/http/handler"
+
+// timeSeriesExample wraps builder query specs in a one hour time series
+// request, the shape every function example shares.
+func timeSeriesExample(name, summary, description string, queries ...map[string]any) handler.OpenAPIExample {
+	list := make([]any, 0, len(queries))
+	for _, query := range queries {
+		list = append(list, query)
+	}
+	return handler.OpenAPIExample{
+		Name:        name,
+		Summary:     summary,
+		Description: description,
+		Value: map[string]any{
+			"schemaVersion":  "v1",
+			"start":          1640995200000,
+			"end":            1640998800000,
+			"requestType":    "time_series",
+			"compositeQuery": map[string]any{"queries": list},
+		},
+	}
+}
+
+func builderQueryEnvelope(spec map[string]any) map[string]any {
+	return map[string]any{"type": "builder_query", "spec": spec}
+}
+
+// function builds a function entry with positional arguments; anomaly is the
+// one function that takes named arguments and is written out in full.
+func function(name string, args ...any) map[string]any {
+	list := make([]any, 0, len(args))
+	for _, arg := range args {
+		list = append(list, map[string]any{"value": arg})
+	}
+	entry := map[string]any{"name": name}
+	if len(list) > 0 {
+		entry["args"] = list
+	}
+	return entry
+}
+
+// queryRangeFunctionExamples shows every function a builder query can carry,
+// what its arguments mean and the values they take. Functions run in the
+// order listed, after the aggregation and before formulas.
+func queryRangeFunctionExamples() []handler.OpenAPIExample {
+	return []handler.OpenAPIExample{
+		timeSeriesExample(
+			"function_timeshift_week_over_week",
+			"timeShift: this week's error logs next to last week's",
+			"timeShift moves every point of its query forward by the argument, in seconds, so a series read from the past lands on the current timestamps. B here reads the hour exactly seven days (604800 s) before the requested window and comes back on this week's timestamps, so it overlays A on a chart and the formula can subtract it point by point. The argument is positive; it says how far back to read.",
+			builderQueryEnvelope(map[string]any{
+				"name":         "A",
+				"signal":       "logs",
+				"aggregations": []any{map[string]any{"expression": "count()", "alias": "errors"}},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "severity_text = 'ERROR'"},
+			}),
+			builderQueryEnvelope(map[string]any{
+				"name":         "B",
+				"signal":       "logs",
+				"aggregations": []any{map[string]any{"expression": "count()", "alias": "errors"}},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "severity_text = 'ERROR'"},
+				"functions":    []any{function("timeShift", 604800)},
+			}),
+			map[string]any{
+				"type": "builder_formula",
+				"spec": map[string]any{"name": "F1", "expression": "A - B"},
+			},
+		),
+		timeSeriesExample(
+			"function_fillzero_sparse_errors",
+			"fillZero: a zero at every step with no failed spans",
+			"A count over sparse events returns a point only for steps that had a match, so a chart of failed spans has gaps where nothing failed. fillZero adds a zero at every missing step. With no arguments the server fills the request window at the query's step, which is the common case. The three optional arguments are start, end and step in milliseconds, for callers that want to fill a different grid.",
+			builderQueryEnvelope(map[string]any{
+				"name":         "A",
+				"signal":       "traces",
+				"aggregations": []any{map[string]any{"expression": "count()", "alias": "failed_spans"}},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "has_error = true"},
+				"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+				"functions":    []any{function("fillZero")},
+			}),
+		),
+		timeSeriesExample(
+			"function_cutoffmin_hide_idle_hosts",
+			"cutOffMin: drop hosts below 5% CPU from the chart",
+			"The four threshold functions take one number. cutOffMin and cutOffMax remove the points below or above the threshold, so an idle host disappears from the chart instead of drawing a line along the bottom. clampMin and clampMax keep the points and replace the value with the threshold, which caps spikes without hiding them. system.cpu.utilization is a ratio, so 0.05 is 5%.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "system.cpu.utilization", "timeAggregation": "avg", "spaceAggregation": "avg"},
+				},
+				"stepInterval": "60s",
+				"groupBy":      []any{map[string]any{"name": "host.name", "fieldContext": "resource"}},
+				"functions":    []any{function("cutOffMin", 0.05)},
+			}),
+		),
+		timeSeriesExample(
+			"function_runningdiff_disk_growth",
+			"runningDiff then clampMin: bytes written to disk per step",
+			"runningDiff turns a gauge into the change between consecutive points, so a filesystem usage gauge becomes bytes written per step. It takes no arguments and drops the first point of the window, since that point has nothing to difference against; the server reads one step before the window to keep the first interval. Functions apply in order: clampMin with 0 runs on the differences and replaces the negative value a cleanup or a volume reset produces with zero.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "system.filesystem.usage", "timeAggregation": "latest", "spaceAggregation": "sum"},
+				},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "state = 'used'"},
+				"groupBy":      []any{map[string]any{"name": "host.name", "fieldContext": "resource"}},
+				"functions":    []any{function("runningDiff"), function("clampMin", 0)},
+			}),
+		),
+		timeSeriesExample(
+			"function_ewma_smoothed_latency",
+			"ewma5: smoothed p95 latency",
+			"ewma3, ewma5 and ewma7 replace each point with an exponentially weighted average of the point and the points before it. The number in the name is the window the default weight is derived from: alpha = 2 / (n + 1), so 0.5, 0.333 and 0.25. One optional argument overrides alpha; a value close to 1 follows the raw series, a value close to 0 smooths harder. 0.3 here smooths a little more than ewma5's default.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "http.server.duration.bucket", "spaceAggregation": "p95"},
+				},
+				"stepInterval": "60s",
+				"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+				"functions":    []any{function("ewma5", 0.3)},
+			}),
+		),
+		timeSeriesExample(
+			"function_median_despiked_request_rate",
+			"median5: request rate without one-step spikes",
+			"median3, median5 and median7 replace each point with the median of the surrounding 3, 5 or 7 points. A spike that lasts one step vanishes, a shift that lasts longer than half the window stays. The first and last half window, 2 points each for median5, have no full window and keep their values, so the newest spike stays visible; a series shorter than the window is returned unchanged. They take no arguments. Use them when the raw series is noisy and the chart is for a trend, not for catching the spike.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum"},
+				},
+				"stepInterval": "60s",
+				"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+				"functions":    []any{function("median5")},
+			}),
+		),
+		timeSeriesExample(
+			"function_cumulativesum_errors_so_far",
+			"cumulativeSum: 5xx responses since the start of the window",
+			"cumulativeSum replaces each point with the sum of every point up to and including it, so a per-step count becomes a running total whose first point is the first count. It takes no arguments. The total resets with the window, so a longer time range gives a larger final value; it is a view of the window, not a counter.",
+			builderQueryEnvelope(map[string]any{
+				"name":         "A",
+				"signal":       "traces",
+				"aggregations": []any{map[string]any{"expression": "count()", "alias": "server_errors"}},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "http.response.status_code >= 500"},
+				"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+				"functions":    []any{function("cumulativeSum")},
+			}),
+		),
+		timeSeriesExample(
+			"function_log10_network_bytes",
+			"log10: network throughput across devices that differ by orders of magnitude",
+			"log2 and log10 replace each value with its logarithm, so a loopback device moving kilobytes and an uplink moving gigabytes fit on one chart. They take no arguments. Zero and negative values have no logarithm and are not drawn. absolute, also without arguments, is the usual companion for a signed series before a logarithm.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "system.network.io", "timeAggregation": "rate", "spaceAggregation": "sum"},
+				},
+				"stepInterval": "60s",
+				"filter":       map[string]any{"expression": "direction = 'transmit'"},
+				"groupBy":      []any{map[string]any{"name": "device", "fieldContext": "attribute"}},
+				"functions":    []any{function("log10")},
+			}),
+		),
+		timeSeriesExample(
+			"function_anomaly_request_rate",
+			"anomaly: request rate scored against its daily pattern",
+			"anomaly is the one function with named arguments. seasonality says which past periods predict the current value: hourly, daily or weekly, daily when absent. z_score_threshold is how many standard deviations from the prediction count as an anomaly. It has no default: a request without it gets bounds of zero width, so send it. 3 is the value the UI sends. The response carries, next to the values, a predicted series, an upper and a lower bound series and an anomaly score series. The scoring runs in the enterprise build; the community build returns the series unchanged.",
+			builderQueryEnvelope(map[string]any{
+				"name":   "A",
+				"signal": "metrics",
+				"aggregations": []any{
+					map[string]any{"metricName": "http.server.duration.count", "timeAggregation": "rate", "spaceAggregation": "sum"},
+				},
+				"stepInterval": "300s",
+				"groupBy":      []any{map[string]any{"name": "service.name", "fieldContext": "resource"}},
+				"functions": []any{
+					map[string]any{
+						"name": "anomaly",
+						"args": []any{
+							map[string]any{"name": "seasonality", "value": "daily"},
+							map[string]any{"name": "z_score_threshold", "value": 3},
+						},
+					},
+				},
+			}),
+		),
+	}
+}

pkg/apiserver/signozapiserver/querier_examples_test.go

@@ -0,0 +1,23 @@
+package signozapiserver
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+)
+
+func TestQueryRangeFunctionExamplesAreValidRequests(t *testing.T) {
+	for _, example := range queryRangeFunctionExamples() {
+		t.Run(example.Name, func(t *testing.T) {
+			raw, err := json.Marshal(example.Value)
+			require.NoError(t, err)
+			var req qbtypes.QueryRangeRequest
+			require.NoError(t, json.Unmarshal(raw, &req))
+			assert.NoError(t, req.Validate())
+		})
+	}
+}