refactor: extract the shared query model behind dashboards and alerts

.agents/skills/maple-telemetry-conventions/rules/service-map-attribution.md

@@ -94,6 +94,12 @@ Keep these names consistent across services to avoid edge fragmentation on the m
 | `cloudflare-logpush` | Cloudflare logpush source |
 | `clerk` | Clerk auth |
 | `autumn` | Autumn metering |
+| `github` | GitHub REST API (VCS sync) |
+| `planetscale-metrics` | PlanetScale per-branch `/metrics` data plane, via the scrape proxy |
+| `scrape-target` | Any other user-configured Prometheus scrape target, via the scrape proxy |
+
+The last two are deliberately generic. Scrape targets are user-configured and unbounded, so
+naming a peer per target would grow the service map a node at a time. Bucket by target type.
 
 Add new peers to this list as they're introduced — single source of truth.
 

apps/api/package.json

@@ -44,6 +44,7 @@
 		"@maple/llm": "workspace:*",
 		"@maple/query-engine": "workspace:*",
 		"@maple/query-engine-integrations": "workspace:*",
+		"@maple/query-model": "workspace:*",
 		"@maple/widgets": "workspace:*",
 		"@tinybirdco/sdk": "catalog:tinybird",
 		"drizzle-orm": "^0.45.1",

apps/api/src/dashboard-templates/application/error-tracking.ts

@@ -9,6 +9,7 @@ import {
 	templateId,
 } from "@/dashboard-templates/helpers"
 import type { TemplateDefinition, WidgetDef } from "@/dashboard-templates/types"
+import { makeRouteDataSource } from "@maple/widgets/dashboard"
 
 function widgets(serviceName?: string): WidgetDef[] {
 	const where = serviceWhereClause(serviceName)
@@ -33,13 +34,10 @@ function widgets(serviceName?: string): WidgetDef[] {
 		{
 			id: "errors-by-type",
 			visualization: "table",
-			dataSource: {
-				endpoint: "errors_by_type",
-				params: {
-					...(serviceName && { services: [serviceName] }),
-					limit: 20,
-				},
-			},
+			dataSource: makeRouteDataSource("errors_by_type", {
+				...(serviceName && { services: [serviceName] }),
+				limit: 20,
+			}),
 			display: {
 				title: "Errors by Type",
 				columns: [
@@ -53,14 +51,11 @@ function widgets(serviceName?: string): WidgetDef[] {
 		{
 			id: "recent-error-traces",
 			visualization: "list",
-			dataSource: {
-				endpoint: "list_traces",
-				params: {
-					...(serviceName && { service: serviceName }),
-					hasError: true,
-					limit: 10,
-				},
-			},
+			dataSource: makeRouteDataSource("list_traces", {
+				...(serviceName && { service: serviceName }),
+				hasError: true,
+				limit: 10,
+			}),
 			display: {
 				title: "Recent Error Traces",
 				listDataSource: "traces",

apps/api/src/dashboard-templates/application/http-endpoints.ts

@@ -10,6 +10,7 @@ import {
 	templateId,
 } from "@/dashboard-templates/helpers"
 import type { TemplateDefinition, WidgetDef } from "@/dashboard-templates/types"
+import { makeRouteDataSource } from "@maple/widgets/dashboard"
 
 function widgets(serviceName?: string): WidgetDef[] {
 	const where = serviceWhereClause(serviceName)
@@ -77,13 +78,10 @@ function widgets(serviceName?: string): WidgetDef[] {
 		{
 			id: "recent-traces",
 			visualization: "list",
-			dataSource: {
-				endpoint: "list_traces",
-				params: {
-					...(serviceName && { service: serviceName }),
-					limit: 10,
-				},
-			},
+			dataSource: makeRouteDataSource("list_traces", {
+				...(serviceName && { service: serviceName }),
+				limit: 10,
+			}),
 			display: {
 				title: "Recent Traces",
 				listDataSource: "traces",

apps/api/src/dashboard-templates/application/metric-overview.ts

@@ -10,10 +10,12 @@ import {
 	templateId,
 } from "@/dashboard-templates/helpers"
 import type { TemplateDefinition, WidgetDef } from "@/dashboard-templates/types"
+import { type QueryBuilderMetricType, toQueryBuilderMetricType } from "@maple/query-model"
+import { makeRouteDataSource } from "@maple/widgets/dashboard"
 
 function widgets(opts: {
 	metricName: string
-	metricType: string
+	metricType: QueryBuilderMetricType
 	serviceName?: string
 	aggregation?: string
 }): WidgetDef[] {
@@ -28,42 +30,42 @@ function widgets(opts: {
 		{
 			id: "metric-current",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "custom_timeseries",
-				params: { source: "metrics", metric: agg, groupBy: "none", filters: metricsFilters },
-				transform: {
+			dataSource: makeRouteDataSource(
+				"custom_timeseries",
+				{ source: "metrics", metric: agg, groupBy: "none", filters: metricsFilters },
+				{
 					flattenSeries: { valueField: "value" },
 					reduceToValue: { field: "value", aggregate: "avg" },
 				},
-			},
+			),
 			display: { title: `${opts.metricName} (${agg})` },
 			layout: { x: 0, y: 0, w: 4, h: 2 },
 		},
 		{
 			id: "metric-max",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "custom_timeseries",
-				params: { source: "metrics", metric: "max", groupBy: "none", filters: metricsFilters },
-				transform: {
+			dataSource: makeRouteDataSource(
+				"custom_timeseries",
+				{ source: "metrics", metric: "max", groupBy: "none", filters: metricsFilters },
+				{
 					flattenSeries: { valueField: "value" },
 					reduceToValue: { field: "value", aggregate: "max" },
 				},
-			},
+			),
 			display: { title: `${opts.metricName} (max)` },
 			layout: { x: 4, y: 0, w: 4, h: 2 },
 		},
 		{
 			id: "metric-count",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "custom_timeseries",
-				params: { source: "metrics", metric: "count", groupBy: "none", filters: metricsFilters },
-				transform: {
+			dataSource: makeRouteDataSource(
+				"custom_timeseries",
+				{ source: "metrics", metric: "count", groupBy: "none", filters: metricsFilters },
+				{
 					flattenSeries: { valueField: "value" },
 					reduceToValue: { field: "value", aggregate: "sum" },
 				},
-			},
+			),
 			display: { title: "Data Points", unit: "number" },
 			layout: { x: 8, y: 0, w: 4, h: 2 },
 		},
@@ -154,7 +156,9 @@ export const metricOverviewTemplate: TemplateDefinition = {
 	],
 	build: (params) => {
 		const metricName = paramValue(params, "metric_name") ?? ""
-		const metricType = paramValue(params, "metric_type") ?? "sum"
+		// A template parameter is typed by a human into a text field, so an
+		// unrecognised metric type falls back rather than failing the build.
+		const metricType = toQueryBuilderMetricType(paramValue(params, "metric_type")) ?? "sum"
 		const serviceName = paramValue(params, "service_name")
 		const scope = serviceName ? ` for ${serviceName}` : ""
 		return buildPortableDashboard({

apps/api/src/dashboard-templates/application/platform-overview.ts

@@ -7,53 +7,50 @@ import {
 	templateId,
 } from "@/dashboard-templates/helpers"
 import type { TemplateDefinition, WidgetDef } from "@/dashboard-templates/types"
+import { makeRouteDataSource } from "@maple/widgets/dashboard"
 
 function widgets(): WidgetDef[] {
 	return [
 		{
 			id: "total-throughput",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "service_usage",
-				transform: { reduceToValue: { field: "totalTraceCount", aggregate: "sum" } },
-			},
+			dataSource: makeRouteDataSource("service_usage", undefined, {
+				reduceToValue: { field: "totalTraceCount", aggregate: "sum" },
+			}),
 			display: { title: "Total Traces", unit: "number" },
 			layout: { x: 0, y: 0, w: 3, h: 2 },
 		},
 		{
 			id: "total-errors",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "errors_summary",
-				transform: { reduceToValue: { field: "totalErrors", aggregate: "first" } },
-			},
+			dataSource: makeRouteDataSource("errors_summary", undefined, {
+				reduceToValue: { field: "totalErrors", aggregate: "first" },
+			}),
 			display: { title: "Total Errors", unit: "number" },
 			layout: { x: 3, y: 0, w: 3, h: 2 },
 		},
 		{
 			id: "error-rate",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "errors_summary",
-				transform: { reduceToValue: { field: "errorRate", aggregate: "first" } },
-			},
+			dataSource: makeRouteDataSource("errors_summary", undefined, {
+				reduceToValue: { field: "errorRate", aggregate: "first" },
+			}),
 			display: { title: "Error Rate", unit: "percent" },
 			layout: { x: 6, y: 0, w: 3, h: 2 },
 		},
 		{
 			id: "affected-services",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "errors_summary",
-				transform: { reduceToValue: { field: "affectedServicesCount", aggregate: "first" } },
-			},
+			dataSource: makeRouteDataSource("errors_summary", undefined, {
+				reduceToValue: { field: "affectedServicesCount", aggregate: "first" },
+			}),
 			display: { title: "Affected Services", unit: "number" },
 			layout: { x: 9, y: 0, w: 3, h: 2 },
 		},
 		{
 			id: "service-overview",
 			visualization: "table",
-			dataSource: { endpoint: "service_overview" },
+			dataSource: makeRouteDataSource("service_overview"),
 			display: {
 				title: "Service Overview",
 				columns: [
@@ -98,10 +95,7 @@ function widgets(): WidgetDef[] {
 		{
 			id: "recent-error-traces",
 			visualization: "list",
-			dataSource: {
-				endpoint: "list_traces",
-				params: { hasError: true, limit: 10 },
-			},
+			dataSource: makeRouteDataSource("list_traces", { hasError: true, limit: 10 }),
 			display: {
 				title: "Recent Error Traces",
 				listDataSource: "traces",

apps/api/src/dashboard-templates/application/service-health.ts

@@ -10,6 +10,7 @@ import {
 	templateId,
 } from "@/dashboard-templates/helpers"
 import type { TemplateDefinition, WidgetDef } from "@/dashboard-templates/types"
+import { makeRouteDataSource } from "@maple/widgets/dashboard"
 
 function widgets(serviceName?: string): WidgetDef[] {
 	const where = serviceWhereClause(serviceName)
@@ -18,11 +19,11 @@ function widgets(serviceName?: string): WidgetDef[] {
 		{
 			id: "throughput",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "service_overview",
-				params: serviceName ? { service_name: serviceName } : {},
-				transform: { reduceToValue: { field: "throughput", aggregate: "sum" } },
-			},
+			dataSource: makeRouteDataSource(
+				"service_overview",
+				serviceName ? { service_name: serviceName } : {},
+				{ reduceToValue: { field: "throughput", aggregate: "sum" } },
+			),
 			display: { title: "Throughput", unit: "number" },
 			layout: { x: 0, y: 0, w: 3, h: 2 },
 		},
@@ -48,22 +49,22 @@ function widgets(serviceName?: string): WidgetDef[] {
 		{
 			id: "p50",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "service_overview",
-				params: serviceName ? { service_name: serviceName } : {},
-				transform: { reduceToValue: { field: "p50LatencyMs", aggregate: "avg" } },
-			},
+			dataSource: makeRouteDataSource(
+				"service_overview",
+				serviceName ? { service_name: serviceName } : {},
+				{ reduceToValue: { field: "p50LatencyMs", aggregate: "avg" } },
+			),
 			display: { title: "P50 Latency", unit: "duration_ms" },
 			layout: { x: 6, y: 0, w: 3, h: 2 },
 		},
 		{
 			id: "p95",
 			visualization: "stat",
-			dataSource: {
-				endpoint: "service_overview",
-				params: serviceName ? { service_name: serviceName } : {},
-				transform: { reduceToValue: { field: "p95LatencyMs", aggregate: "avg" } },
-			},
+			dataSource: makeRouteDataSource(
+				"service_overview",
+				serviceName ? { service_name: serviceName } : {},
+				{ reduceToValue: { field: "p95LatencyMs", aggregate: "avg" } },
+			),
 			display: { title: "P95 Latency", unit: "duration_ms" },
 			layout: { x: 9, y: 0, w: 3, h: 2 },
 		},