diff --git a/apps/ai/src/mcp/lib/dashboard-mutations.ts b/apps/ai/src/mcp/lib/dashboard-mutations.ts index c367cad632..6b2efb1cce 100644 --- a/apps/ai/src/mcp/lib/dashboard-mutations.ts +++ b/apps/ai/src/mcp/lib/dashboard-mutations.ts @@ -144,7 +144,9 @@ export const legacyDataSourceHint = (value: unknown): string | undefined => { /** Every data-source arm with its minimal shape, for errors that would otherwise list union failures. */ export const DATA_SOURCE_VARIANTS = '`{"kind":"query","resultShape":"timeseries"|"breakdown"|"list"|...,"queries":[...]}` (query builder), ' + - '`{"kind":"raw_sql","sql":"SELECT ... WHERE $__orgFilter AND $__timeFilter(Timestamp)"}`, `{"kind":"route","endpoint":"...","params":{...}}`, ' + + '`{"kind":"raw_sql","sql":"SELECT ... WHERE $__orgFilter AND $__timeFilter(Timestamp)"}`, ' + + '`{"kind":"promql","query":"sum(rate(...[$__rate_interval]))","legendFormat":"{{job}}","displayType":"line"}`, ' + + '`{"kind":"route","endpoint":"...","params":{...}}`, ' + 'or `{"kind":"static"}` (markdown note: panel_type markdown with display `{"markdown":{"content":"..."}}`)' const decodeKindField = Schema.decodeUnknownResult(Schema.Struct({ kind: Schema.Unknown })) diff --git a/apps/ai/src/mcp/lib/dashboard-schema-doc.ts b/apps/ai/src/mcp/lib/dashboard-schema-doc.ts index 2b6814ddbb..fbe1659064 100644 --- a/apps/ai/src/mcp/lib/dashboard-schema-doc.ts +++ b/apps/ai/src/mcp/lib/dashboard-schema-doc.ts @@ -1,6 +1,7 @@ import { PANEL_TYPES, WIDGET_TYPES, WIDGET_UNITS, type WidgetTypeMeta } from "@maple/domain/http" import { makeProductEventsFunnelDataSource, + makePromqlDataSource, makeQueryDataSource, makeRawSqlDataSource, makeStaticDataSource, @@ -221,6 +222,24 @@ const dataSourcesSection = (): string => }), ), "", + '### `kind: "promql"`: a PromQL query over the metrics', + "", + "Prometheus names: `http.server.request.duration` answers to", + "`http_server_request_duration_seconds_bucket`, a monotonic sum to `..._total`. Grafana", + "variables work (`$var`, `${var}`, `${var:regex}`, `[[var]]`, an All selection becomes", + "`(a|b)`), plus `$__interval`, `$__rate_interval`, `$__range` and `$__range_s`.", + "`legendFormat` names series with `{{label}}`; `minStepSeconds` floors the step;", + "`displayType` is the panel's raw-SQL display type (a stat reads the newest point of the", + "first series with the `first` reducer on field `value`; a table gets one row per series).", + "", + json( + makePromqlDataSource({ + query: 'sum by (job) (rate(http_server_request_duration_seconds_count{job=~"$service"}[$__rate_interval]))', + legendFormat: "{{job}}", + displayType: "line", + }), + ), + "", '### `kind: "static"`: a markdown note, no request', "", json(makeStaticDataSource()), @@ -584,7 +603,7 @@ const SECTION_RENDERERS = { const SECTION_SUMMARIES = { panel_types: "The 14 panel types, what each persists as, and which need a group-by or a reduction.", - data_sources: "The four `kind` arms of a widget data source, with a decodable example of each.", + data_sources: "The five `kind` arms of a widget data source, with a decodable example of each.", units: "The unit vocabulary, and the percent-vs-percent_100 scale rule.", queries: "Aggregations and group-by tokens per source, the whereClause grammar, formulas.", display: "Display config keys per panel type, including the ones that are stored but inert.", diff --git a/apps/ai/src/mcp/lib/raw-sql-widget.test.ts b/apps/ai/src/mcp/lib/raw-sql-widget.test.ts index 5f3a18b964..7f232ab93a 100644 --- a/apps/ai/src/mcp/lib/raw-sql-widget.test.ts +++ b/apps/ai/src/mcp/lib/raw-sql-widget.test.ts @@ -1,5 +1,11 @@ import { describe, expect, it } from "vitest" -import { buildRawSqlDataSource, validateRawSql, visualizationToDisplayType } from "./raw-sql-widget" +import { makePromqlDataSource } from "@maple/widgets/dashboard" +import { + buildRawSqlDataSource, + validateRawSql, + visualizationToDisplayType, + withScalarReduction, +} from "./raw-sql-widget" describe("visualizationToDisplayType", () => { it("derives line/area/bar for chart based on chartId hint", () => { @@ -115,3 +121,24 @@ describe("validateRawSql", () => { ).toBeNull() }) }) + +describe("withScalarReduction on PromQL", () => { + it("gives a PromQL stat a stat display type, so `first` reads the newest point", () => { + const repaired = withScalarReduction(makePromqlDataSource({ query: "vector(time())" }), true) + expect(repaired).toMatchObject({ + kind: "promql", + displayType: "stat", + transform: { reduceToValue: { field: "value", aggregate: "first" } }, + }) + }) + + it("keeps a display type the caller chose", () => { + const source = makePromqlDataSource({ query: "up", displayType: "gauge" }) + expect(withScalarReduction(source, true)).toMatchObject({ displayType: "gauge" }) + }) + + it("replaces a line display type on a scalar, whose rows would be oldest first", () => { + const source = makePromqlDataSource({ query: "up", displayType: "line" }) + expect(withScalarReduction(source, true)).toMatchObject({ displayType: "stat" }) + }) +}) diff --git a/apps/ai/src/mcp/lib/raw-sql-widget.ts b/apps/ai/src/mcp/lib/raw-sql-widget.ts index 55ddfcc8d3..da8ebe15b6 100644 --- a/apps/ai/src/mcp/lib/raw-sql-widget.ts +++ b/apps/ai/src/mcp/lib/raw-sql-widget.ts @@ -1,7 +1,12 @@ import { rawSqlIssue } from "@maple/domain/raw-sql" import { rawSqlDisplayTypeFor, widgetTypeByVisualization } from "@maple/domain/http" import type { RawSqlDisplayType, WidgetDataSourceSchema } from "@maple/domain/http" -import { dataSourceQuerySet, dataSourceTransform, makeRawSqlDataSource } from "@maple/widgets/dashboard" +import { + dataSourcePromql, + dataSourceQuerySet, + dataSourceTransform, + makeRawSqlDataSource, +} from "@maple/widgets/dashboard" // MCP-side mirror of the web's raw-SQL widget builder so agents can create // raw-SQL widgets without hand-crafting the dataSource JSON. The display type @@ -48,11 +53,21 @@ export function buildRawSqlDataSource(args: { */ export function withScalarReduction(dataSource: WidgetDataSource, isScalar: boolean): WidgetDataSource { if (!isScalar) return dataSource + // A PromQL scalar needs its rows newest first, which only a stat or gauge display type gives; + // any other (absent, or a line chart's) is oldest first, and `first` would read the oldest. + if ( + "kind" in dataSource && + dataSource.kind === "promql" && + dataSource.displayType !== "stat" && + dataSource.displayType !== "gauge" + ) { + return withScalarReduction({ ...dataSource, displayType: "stat" }, isScalar) + } if (dataSourceTransform(dataSource)?.reduceToValue !== undefined) return dataSource const querySet = dataSourceQuerySet(dataSource) - // Only the query arm: a route source owns its own response shape, and a + // Only the query and PromQL arms: a route source owns its own response shape, and a // static source has no response at all. - if (querySet === null) return dataSource + if (querySet === null && dataSourcePromql(dataSource) === null) return dataSource const existing = dataSourceTransform(dataSource) return { diff --git a/apps/ai/src/mcp/lib/validate-widget-renderability.test.ts b/apps/ai/src/mcp/lib/validate-widget-renderability.test.ts index 649e9f6607..4941df8840 100644 --- a/apps/ai/src/mcp/lib/validate-widget-renderability.test.ts +++ b/apps/ai/src/mcp/lib/validate-widget-renderability.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from "vitest" import { makeProductEventsFunnelDataSource, + makePromqlDataSource, makeQueryDataSource, makeRawSqlDataSource, makeStaticDataSource, @@ -272,3 +273,38 @@ describe("all three write paths agree on scalar repair", () => { } }) }) + +describe("a promql data source", () => { + it("renders on a line chart with no issues", () => { + const issues = validateWidgetRenderability( + widget("line", makePromqlDataSource({ query: "up", displayType: "line" })), + ) + expect(issues.fatal).toEqual([]) + expect(issues.warnings).toEqual([]) + }) + + it("needs a query, a reduction on a stat, and is refused on a list", () => { + const empty = validateWidgetRenderability(widget("line", makePromqlDataSource({ query: " " }))) + expect(Arr.join(empty.fatal, " ")).toContain("needs a `query`") + const stat = validateWidgetRenderability( + widget("stat", makePromqlDataSource({ query: "up", displayType: "stat" })), + ) + expect(Arr.join(stat.fatal, " ")).toContain("reduceToValue") + const list = validateWidgetRenderability(widget("list", makePromqlDataSource({ query: "up" }))) + expect(Arr.join(list.fatal, " ")).toContain("cannot draw PromQL") + }) + + it("warns when the display type does not match the panel", () => { + const { warnings } = validateWidgetRenderability( + widget("table", makePromqlDataSource({ query: "up", displayType: "line" })), + ) + expect(Arr.join(warnings, " ")).toContain('displayType: "table"') + }) + + it("reads an absent display type as a line chart, so a table without one is warned", () => { + const table = validateWidgetRenderability(widget("table", makePromqlDataSource({ query: "up" }))) + expect(Arr.join(table.warnings, " ")).toContain('displayType: "table"') + const line = validateWidgetRenderability(widget("line", makePromqlDataSource({ query: "up" }))) + expect(line.warnings).toEqual([]) + }) +}) diff --git a/apps/ai/src/mcp/lib/validate-widget-renderability.ts b/apps/ai/src/mcp/lib/validate-widget-renderability.ts index 5e25cda560..389773e3f2 100644 --- a/apps/ai/src/mcp/lib/validate-widget-renderability.ts +++ b/apps/ai/src/mcp/lib/validate-widget-renderability.ts @@ -6,7 +6,12 @@ import { type DashboardWidgetSchema, type PanelType, } from "@maple/domain/http" -import { dataSourceQuerySet, dataSourceRawSql, dataSourceTransform } from "@maple/widgets/dashboard" +import { + dataSourcePromql, + dataSourceQuerySet, + dataSourceRawSql, + dataSourceTransform, +} from "@maple/widgets/dashboard" import { FUNNEL_MAX_STEPS, PATHS_MAX_BRANCHES, PATHS_MAX_DEPTH } from "@maple/query-model" import { isGroupByRequested } from "./inspect-widget" import { stringifyJson } from "./json" @@ -111,6 +116,29 @@ export const validateWidgetRenderability = (input: ValidateWidgetRenderabilityIn ) } + const promql = dataSourcePromql(widget.dataSource) + if (promql !== null) { + if (Str.trim(promql.query) === "") fatal.push('A `kind: "promql"` data source needs a `query`.') + if (panelType === "list") { + fatal.push( + '`panel_type: "list"` cannot draw PromQL. Use `panel_type: "table"` for one row per series.', + ) + } + const expected = meta.rawSqlDisplayType + // An absent displayType shapes rows for a line chart, so it is checked as "line". + const rowsFor = promql.displayType ?? "line" + if (expected !== undefined && rowsFor !== expected) { + warnings.push( + `The PromQL \`displayType\` is \`${promql.displayType ?? "unset (line)"}\` but a \`${panelType}\` panel draws \`${expected}\` rows; set \`displayType: "${expected}"\`.`, + ) + } + if (meta.isScalar && transform?.reduceToValue === undefined) { + fatal.push( + `\`panel_type: "${panelType}"\` needs \`transform: { "reduceToValue": { "field": "value", "aggregate": "first" } }\` on a PromQL source (\`first\` is the newest point).`, + ) + } + } + // A scalar tile reads `data[0].value`; without the reduction it receives a row // object and renders `[object Object]`. if (meta.isScalar && querySet !== null && transform?.reduceToValue === undefined) { diff --git a/apps/ai/src/mcp/tool-descriptors.generated.ts b/apps/ai/src/mcp/tool-descriptors.generated.ts index e67eed36ed..9a04c5e9a6 100644 --- a/apps/ai/src/mcp/tool-descriptors.generated.ts +++ b/apps/ai/src/mcp/tool-descriptors.generated.ts @@ -59,7 +59,7 @@ export const MCP_TOOL_DESCRIPTORS: ReadonlyArray = [ {"name":"delete_oncall_override","title":"Delete On-Call Override","description":"Delete an override so the schedule's layers decide again. Override ids come from create_oncall_override or the REST overrides list.","inputSchema":{"type":"object","properties":{"schedule_id":{"type":"string","description":"On-call schedule the override is on: its UUID or its REST id (onc_\u2026)"},"override_id":{"type":"string","description":"Override to delete: its UUID or its REST id (ovr_\u2026)"}},"required":["schedule_id","override_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"scheduleId":{"type":"string"},"scheduleName":{"type":"string"}},"required":["id","scheduleId","scheduleName"],"additionalProperties":true},"annotations":{"title":"Delete On-Call Override","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}}, {"name":"describe_dashboard_schema","title":"Describe Dashboard Schema","description":"What a dashboard widget can be: panel types, the four data-source kinds, the unit vocabulary, aggregations and group-by tokens, the display config, and (section templates) the create_dashboard templates. Generated from the live schema; read it before authoring or editing widgets rather than working from a remembered example.","inputSchema":{"type":"object","properties":{"section":{"type":"string","enum":["panel_types","data_sources","units","queries","display","raw_sql","templates"],"description":"Omit for the index plus the panel-type table."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"section":{"type":"string"},"markdown":{"type":"string"}},"required":["markdown"],"additionalProperties":true},"annotations":{"title":"Describe Dashboard Schema","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"list_dashboards","title":"List Dashboards","description":"List all dashboards with widget counts and timestamps. Use get_dashboard to see full widget configuration.","inputSchema":{"type":"object","properties":{"search":{"type":"string","description":"Filter dashboards by name (case-insensitive contains)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"dashboards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"widgetCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","publicId","name","widgetCount","createdAt","updatedAt"],"additionalProperties":true}},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"search":{"type":"string"}},"required":["dashboards","total"],"additionalProperties":true},"annotations":{"title":"List Dashboards","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, - {"name":"get_dashboard","title":"Get Dashboard","description":"Full configuration of one dashboard: every widget with its id, visualization, dataSource, display, layout and any pinned timeRange. Widgets come back in the shape update_dashboard_widget and replace_dashboard_widgets take. Ids from list_dashboards.","inputSchema":{"type":"object","properties":{"dashboard_id":{"type":"string","description":"Dashboard ID: its UUID or its REST id (dash_\u2026)"}},"required":["dashboard_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"publicId":{"type":"string"},"dashboard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"timeRange":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"},"endTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"}},"required":["type","startTime","endTime"],"additionalProperties":true}]},"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"visualization":{"type":"string","enum":["chart","hbar","stat","gauge","table","list","pie","histogram","heatmap","funnel","paths","markdown"]},"dataSource":{"$ref":"#/$defs/@maple~1WidgetDataSource"},"display":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"chartId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chartPresentation":{"anyOf":[{"type":"object","properties":{"legend":{"anyOf":[{"type":"string","enum":["visible","hidden","right"]},{"type":"null"}]},"seriesStats":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"tooltip":{"anyOf":[{"type":"string","enum":["visible","hidden"]},{"type":"null"}]},"showPoints":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fillNulls":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"boolean","enum":[false]},{"type":"null"}]},"compareToPreviousPeriod":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"xAxis":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"visible":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"yAxis":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"min":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"softMin":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"softMax":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"logScale":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fitYAxisToData":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"visible":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"seriesMapping":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"colorOverrides":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"stacked":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"curveType":{"anyOf":[{"type":"string","enum":["linear","monotone"]},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"thresholds":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"color":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["value","color"],"additionalProperties":true}},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"sparkline":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"dataSource":{"anyOf":[{"$ref":"#/$defs/@maple~1WidgetDataSource"},{"type":"null"}]}},"required":["enabled"],"additionalProperties":true},{"type":"null"}]},"columns":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"header":{"type":"string"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"align":{"anyOf":[{"type":"string","enum":["left","center","right"]},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"thresholds":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"color":{"type":"string"}},"required":["value","color"],"additionalProperties":true}},{"type":"null"}]}},"required":["field","header"],"additionalProperties":true}},{"type":"null"}]},"listDataSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"listWhereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"listLimit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"listRootOnly":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pie":{"anyOf":[{"type":"object","properties":{"donut":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"innerRadius":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"showLabels":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"showPercent":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"funnel":{"anyOf":[{"type":"object","properties":{"showStepPercent":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"steps":{"anyOf":[{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"eventName":{"type":"string"},"attributeEquals":{"type":"object","additionalProperties":{"type":"string"}}},"required":["kind","eventName"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"pagePath":{"type":"string"},"host":{"type":"string"}},"required":["kind","pagePath"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["session"]},"dimension":{"type":"string","enum":["referrerHost","utmSource","utmMedium","utmCampaign","country","host"]},"value":{"type":"string"}},"required":["kind","dimension","value"],"additionalProperties":true}]}},{"type":"null"}]},"keyBy":{"anyOf":[{"type":"string","enum":["person","visitor","user","session"]},{"type":"null"}]},"windowSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"breakdownBy":{"anyOf":[{"type":"string","enum":["referrerHost","utmSource","utmMedium","utmCampaign","country","host"]},{"type":"string","pattern":"^attribute:[\\s\\S]*?$"},{"type":"null"}]},"filters":{"anyOf":[{"type":"object","properties":{"host":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagePath":{"anyOf":[{"type":"string"},{"type":"null"}]},"referrerHost":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"browserName":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmMedium":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmCampaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"visitorType":{"anyOf":[{"type":"string","enum":["new","returning"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"variant":{"anyOf":[{"type":"string","enum":["bars","dropoff"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"paths":{"anyOf":[{"type":"object","properties":{"anchor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"eventName":{"type":"string"},"attributeEquals":{"type":"object","additionalProperties":{"type":"string"}}},"required":["kind","eventName"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"pagePath":{"type":"string"},"host":{"type":"string"}},"required":["kind","pagePath"],"additionalProperties":true}]},"direction":{"anyOf":[{"type":"string","enum":["after","before"]},{"type":"null"}]},"depth":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"branches":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"keyBy":{"anyOf":[{"type":"string","enum":["person","visitor","user","session"]},{"type":"null"}]},"windowSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"include":{"anyOf":[{"type":"string","enum":["all","events","pages"]},{"type":"null"}]},"exclude":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"filters":{"anyOf":[{"type":"object","properties":{"host":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagePath":{"anyOf":[{"type":"string"},{"type":"null"}]},"referrerHost":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"browserName":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmMedium":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmCampaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"visitorType":{"anyOf":[{"type":"string","enum":["new","returning"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]}},"required":["anchor"],"additionalProperties":true},{"type":"null"}]},"histogram":{"anyOf":[{"type":"object","properties":{"bucketCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"bucketWidth":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"logScaleY":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"heatmap":{"anyOf":[{"type":"object","properties":{"colorScale":{"anyOf":[{"type":"string","enum":["amber","blues","reds","viridis","magma","cividis"]},{"type":"null"}]},"scaleType":{"anyOf":[{"type":"string","enum":["linear","log"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"gauge":{"anyOf":[{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"style":{"anyOf":[{"type":"string","enum":["radial","bar"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"markdown":{"anyOf":[{"type":"object","properties":{"content":{"type":"string"}},"required":["content"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true},"layout":{"type":"object","properties":{"x":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"y":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"w":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"h":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"minW":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"minH":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"maxW":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"maxH":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]}},"required":["x","y","w","h"],"additionalProperties":true},"timeRange":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"},"endTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"}},"required":["type","startTime","endTime"],"additionalProperties":true}]},"sectionId":{"type":"string"},"tabId":{"type":"string"}},"required":["id","visualization","dataSource","display","layout"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","tags","timeRange","widgets","createdAt","updatedAt"],"additionalProperties":true}},"required":["publicId","dashboard"],"additionalProperties":true,"$defs":{"@maple/IsoDateTimeString":{"type":"string"},"@maple/QueryWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["query"]},"resultShape":{"type":"string","enum":["timeseries","breakdown","list"]},"queries":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["traces"]},"valueField":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["logs"]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["metrics"]},"signalSource":{"anyOf":[{"type":"string","enum":["default","meter"]},{"type":"null"}]},"metricName":{"anyOf":[{"type":"string"},{"type":"null"}]},"metricType":{"anyOf":[{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"]},{"type":"null"}]},"isMonotonic":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"spaceAggregation":{"anyOf":[{"type":"string","enum":["sum","avg","min","max","count"]},{"type":"null"}]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["product_events"]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true}]}},"formulas":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"expression":{"type":"string"},"legend":{"type":"string"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","name","expression","legend"],"additionalProperties":true}},{"type":"null"}]},"comparison":{"anyOf":[{"type":"object","properties":{"mode":{"anyOf":[{"type":"string","enum":["none","previous_period"]},{"type":"null"}]},"includePercentChange":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"defaultLimit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"columns":{"type":"array","items":{"type":"string"}},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","resultShape","queries"],"additionalProperties":true,"title":"Query widget data source"},"@maple/RawSqlWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["raw_sql"]},"sql":{"type":"string"},"displayType":{"type":"string"},"granularitySeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","sql"],"additionalProperties":true,"title":"Raw SQL widget data source"},"@maple/RouteWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["route"]},"endpoint":{"type":"string"},"params":{"type":"object"},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","endpoint"],"additionalProperties":true,"title":"Route widget data source"},"@maple/StaticWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind"],"additionalProperties":true,"title":"Static widget data source"},"@maple/WidgetDataSource":{"anyOf":[{"$ref":"#/$defs/@maple~1QueryWidgetDataSource"},{"$ref":"#/$defs/@maple~1RawSqlWidgetDataSource"},{"$ref":"#/$defs/@maple~1RouteWidgetDataSource"},{"$ref":"#/$defs/@maple~1StaticWidgetDataSource"}],"title":"Widget data source"}}},"annotations":{"title":"Get Dashboard","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, + {"name":"get_dashboard","title":"Get Dashboard","description":"Full configuration of one dashboard: every widget with its id, visualization, dataSource, display, layout and any pinned timeRange. Widgets come back in the shape update_dashboard_widget and replace_dashboard_widgets take. Ids from list_dashboards.","inputSchema":{"type":"object","properties":{"dashboard_id":{"type":"string","description":"Dashboard ID: its UUID or its REST id (dash_\u2026)"}},"required":["dashboard_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"publicId":{"type":"string"},"dashboard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"timeRange":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"},"endTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"}},"required":["type","startTime","endTime"],"additionalProperties":true}]},"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"visualization":{"type":"string","enum":["chart","hbar","stat","gauge","table","list","pie","histogram","heatmap","funnel","paths","markdown"]},"dataSource":{"$ref":"#/$defs/@maple~1WidgetDataSource"},"display":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"chartId":{"anyOf":[{"type":"string"},{"type":"null"}]},"chartPresentation":{"anyOf":[{"type":"object","properties":{"legend":{"anyOf":[{"type":"string","enum":["visible","hidden","right"]},{"type":"null"}]},"seriesStats":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"tooltip":{"anyOf":[{"type":"string","enum":["visible","hidden"]},{"type":"null"}]},"showPoints":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fillNulls":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"boolean","enum":[false]},{"type":"null"}]},"compareToPreviousPeriod":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"xAxis":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"visible":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"yAxis":{"anyOf":[{"type":"object","properties":{"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"min":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"softMin":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"softMax":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"logScale":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fitYAxisToData":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"visible":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"seriesMapping":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"colorOverrides":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"stacked":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"curveType":{"anyOf":[{"type":"string","enum":["linear","monotone"]},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"thresholds":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"color":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["value","color"],"additionalProperties":true}},{"type":"null"}]},"prefix":{"anyOf":[{"type":"string"},{"type":"null"}]},"suffix":{"anyOf":[{"type":"string"},{"type":"null"}]},"sparkline":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"dataSource":{"anyOf":[{"$ref":"#/$defs/@maple~1WidgetDataSource"},{"type":"null"}]}},"required":["enabled"],"additionalProperties":true},{"type":"null"}]},"columns":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"header":{"type":"string"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"align":{"anyOf":[{"type":"string","enum":["left","center","right"]},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"thresholds":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"color":{"type":"string"}},"required":["value","color"],"additionalProperties":true}},{"type":"null"}]}},"required":["field","header"],"additionalProperties":true}},{"type":"null"}]},"listDataSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"listWhereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"listLimit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"listRootOnly":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pie":{"anyOf":[{"type":"object","properties":{"donut":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"innerRadius":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"showLabels":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"showPercent":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"funnel":{"anyOf":[{"type":"object","properties":{"showStepPercent":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"steps":{"anyOf":[{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"eventName":{"type":"string"},"attributeEquals":{"type":"object","additionalProperties":{"type":"string"}}},"required":["kind","eventName"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"pagePath":{"type":"string"},"host":{"type":"string"}},"required":["kind","pagePath"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["session"]},"dimension":{"type":"string","enum":["referrerHost","utmSource","utmMedium","utmCampaign","country","host"]},"value":{"type":"string"}},"required":["kind","dimension","value"],"additionalProperties":true}]}},{"type":"null"}]},"keyBy":{"anyOf":[{"type":"string","enum":["person","visitor","user","session"]},{"type":"null"}]},"windowSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"breakdownBy":{"anyOf":[{"type":"string","enum":["referrerHost","utmSource","utmMedium","utmCampaign","country","host"]},{"type":"string","pattern":"^attribute:[\\s\\S]*?$"},{"type":"null"}]},"filters":{"anyOf":[{"type":"object","properties":{"host":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagePath":{"anyOf":[{"type":"string"},{"type":"null"}]},"referrerHost":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"browserName":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmMedium":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmCampaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"visitorType":{"anyOf":[{"type":"string","enum":["new","returning"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"variant":{"anyOf":[{"type":"string","enum":["bars","dropoff"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"paths":{"anyOf":[{"type":"object","properties":{"anchor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"eventName":{"type":"string"},"attributeEquals":{"type":"object","additionalProperties":{"type":"string"}}},"required":["kind","eventName"],"additionalProperties":true},{"type":"object","properties":{"kind":{"type":"string","enum":["page"]},"pagePath":{"type":"string"},"host":{"type":"string"}},"required":["kind","pagePath"],"additionalProperties":true}]},"direction":{"anyOf":[{"type":"string","enum":["after","before"]},{"type":"null"}]},"depth":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"branches":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"keyBy":{"anyOf":[{"type":"string","enum":["person","visitor","user","session"]},{"type":"null"}]},"windowSeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"include":{"anyOf":[{"type":"string","enum":["all","events","pages"]},{"type":"null"}]},"exclude":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"filters":{"anyOf":[{"type":"object","properties":{"host":{"anyOf":[{"type":"string"},{"type":"null"}]},"pagePath":{"anyOf":[{"type":"string"},{"type":"null"}]},"referrerHost":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"deviceType":{"anyOf":[{"type":"string"},{"type":"null"}]},"browserName":{"anyOf":[{"type":"string"},{"type":"null"}]},"osName":{"anyOf":[{"type":"string"},{"type":"null"}]},"language":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmSource":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmMedium":{"anyOf":[{"type":"string"},{"type":"null"}]},"utmCampaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"visitorType":{"anyOf":[{"type":"string","enum":["new","returning"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]}},"required":["anchor"],"additionalProperties":true},{"type":"null"}]},"histogram":{"anyOf":[{"type":"object","properties":{"bucketCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"bucketWidth":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"logScaleY":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"heatmap":{"anyOf":[{"type":"object","properties":{"colorScale":{"anyOf":[{"type":"string","enum":["amber","blues","reds","viridis","magma","cividis"]},{"type":"null"}]},"scaleType":{"anyOf":[{"type":"string","enum":["linear","log"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"gauge":{"anyOf":[{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"style":{"anyOf":[{"type":"string","enum":["radial","bar"]},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"markdown":{"anyOf":[{"type":"object","properties":{"content":{"type":"string"}},"required":["content"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true},"layout":{"type":"object","properties":{"x":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"y":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"w":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"h":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"minW":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"minH":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"maxW":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"maxH":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]}},"required":["x","y","w","h"],"additionalProperties":true},"timeRange":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"},"endTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"}},"required":["type","startTime","endTime"],"additionalProperties":true}]},"sectionId":{"type":"string"},"tabId":{"type":"string"}},"required":["id","visualization","dataSource","display","layout"],"additionalProperties":true}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","tags","timeRange","widgets","createdAt","updatedAt"],"additionalProperties":true}},"required":["publicId","dashboard"],"additionalProperties":true,"$defs":{"@maple/IsoDateTimeString":{"type":"string"},"@maple/QueryWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["query"]},"resultShape":{"type":"string","enum":["timeseries","breakdown","list"]},"queries":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["traces"]},"valueField":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["logs"]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["metrics"]},"signalSource":{"anyOf":[{"type":"string","enum":["default","meter"]},{"type":"null"}]},"metricName":{"anyOf":[{"type":"string"},{"type":"null"}]},"metricType":{"anyOf":[{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"]},{"type":"null"}]},"isMonotonic":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"spaceAggregation":{"anyOf":[{"type":"string","enum":["sum","avg","min","max","count"]},{"type":"null"}]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"whereClause":{"anyOf":[{"type":"string"},{"type":"null"}]},"aggregation":{"type":"string"},"stepInterval":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderByDirection":{"anyOf":[{"type":"string","enum":["desc","asc"]},{"type":"null"}]},"addOns":{"anyOf":[{"type":"object","properties":{"groupBy":{"type":"boolean"},"having":{"type":"boolean"},"orderBy":{"type":"boolean"},"limit":{"type":"boolean"},"legend":{"type":"boolean"}},"required":["groupBy","having","orderBy","limit","legend"],"additionalProperties":true},{"type":"null"}]},"groupBy":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"having":{"anyOf":[{"type":"string"},{"type":"null"}]},"orderBy":{"anyOf":[{"type":"string"},{"type":"null"}]},"limit":{"anyOf":[{"type":"string"},{"type":"null"}]},"seriesLimit":{"anyOf":[{"type":"string"},{"type":"null"}]},"legend":{"anyOf":[{"type":"string"},{"type":"null"}]},"dataSource":{"type":"string","enum":["product_events"]}},"required":["id","name","aggregation","dataSource"],"additionalProperties":true}]}},"formulas":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"expression":{"type":"string"},"legend":{"type":"string"},"hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","name","expression","legend"],"additionalProperties":true}},{"type":"null"}]},"comparison":{"anyOf":[{"type":"object","properties":{"mode":{"anyOf":[{"type":"string","enum":["none","previous_period"]},{"type":"null"}]},"includePercentChange":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"additionalProperties":true},{"type":"null"}]},"defaultLimit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"columns":{"type":"array","items":{"type":"string"}},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","resultShape","queries"],"additionalProperties":true,"title":"Query widget data source"},"@maple/RawSqlWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["raw_sql"]},"sql":{"type":"string"},"displayType":{"type":"string"},"granularitySeconds":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","sql"],"additionalProperties":true,"title":"Raw SQL widget data source"},"@maple/PromqlWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["promql"]},"query":{"type":"string","maxLength":10000},"legendFormat":{"type":"string","maxLength":500},"minStepSeconds":{"type":"number","exclusiveMinimum":0},"displayType":{"type":"string"},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","query"],"additionalProperties":true,"title":"PromQL widget data source"},"@maple/RouteWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["route"]},"endpoint":{"type":"string"},"params":{"type":"object"},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind","endpoint"],"additionalProperties":true,"title":"Route widget data source"},"@maple/StaticWidgetDataSource":{"type":"object","properties":{"kind":{"type":"string","enum":["static"]},"transform":{"type":"object","properties":{"fieldMap":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"hideSeries":{"anyOf":[{"type":"object","properties":{"baseNames":{"type":"array","items":{"type":"string"}}},"required":["baseNames"],"additionalProperties":true},{"type":"null"}]},"flattenSeries":{"anyOf":[{"type":"object","properties":{"valueField":{"type":"string"}},"required":["valueField"],"additionalProperties":true},{"type":"null"}]},"reduceToValue":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"aggregate":{"anyOf":[{"type":"string","enum":["first","sum","count","avg","max","min"]},{"type":"null"}]}},"required":["field"],"additionalProperties":true},{"type":"null"}]},"computeRatio":{"anyOf":[{"type":"object","properties":{"numeratorName":{"type":"string"},"denominatorNames":{"type":"array","items":{"type":"string"}}},"required":["numeratorName","denominatorNames"],"additionalProperties":true},{"type":"null"}]},"limit":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]},{"type":"null"}]},"sortBy":{"anyOf":[{"type":"object","properties":{"field":{"type":"string"},"direction":{"type":"string","enum":["asc","desc"]}},"required":["field","direction"],"additionalProperties":true},{"type":"null"}]}},"additionalProperties":true}},"required":["kind"],"additionalProperties":true,"title":"Static widget data source"},"@maple/WidgetDataSource":{"anyOf":[{"$ref":"#/$defs/@maple~1QueryWidgetDataSource"},{"$ref":"#/$defs/@maple~1RawSqlWidgetDataSource"},{"$ref":"#/$defs/@maple~1PromqlWidgetDataSource"},{"$ref":"#/$defs/@maple~1RouteWidgetDataSource"},{"$ref":"#/$defs/@maple~1StaticWidgetDataSource"}],"title":"Widget data source"}}},"annotations":{"title":"Get Dashboard","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, {"name":"create_dashboard","title":"Create Dashboard","description":"Create a dashboard one of three ways: a `template`, simplified `widgets` specs, or full `dashboard_json`. Templates (service health, errors, HTTP, runtimes, databases, integrations) are listed by describe_dashboard_schema section \"templates\".\n\nTemplates chart one service or host at a time. To compare entities in one chart (CPU per host, memory per pod), use `widgets` on source=metrics with group_by `resource.host.name` / `resource.k8s.pod.name`; list_infra names the metrics.\n\nCreated widgets are inspected (up to 12) and returned with a verdict (looks_healthy / suspicious / broken). Use inspect_chart_data beyond the cap, or validate=false to skip.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Dashboard name"},"template":{"type":"string","enum":["service-health","error-tracking","platform-overview","http-endpoints","top-errors","metric-overview","jvm-runtime","nodejs-runtime","grpc-service","blank","postgres-overview","mongodb-overview","redis-overview","mysql-overview","cloudflare","planetscale","gcp","vercel","host-metrics","kubernetes-cluster","kubernetes-pod","docker-containers","kafka-overview","nats-overview","rabbitmq-overview","custom"],"description":"Default service-health when neither widgets nor dashboard_json is given; dashboard_json alone selects custom. What each charts: describe_dashboard_schema section \"templates\"."},"service":{"type":"string","description":"Scope template widgets to a specific service"},"time_range":{"type":"string","description":"Dashboard window as relative shorthand: 15m, 6h, 24h, 7d, 2w, 3mo or \"today\". Up to 32 days (default 1h). List widgets (recent traces/logs) only render up to 7 days and ask the viewer to narrow a wider range."},"description":{"type":"string","description":"Dashboard description"},"metric_name":{"type":"string","description":"Metric name for the metric-overview template (use list_metrics to discover). Example: http.server.duration"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"],"description":"Metric type for the metric-overview template"},"widgets":{"type":"string","contentMediaType":"application/json","contentSchema":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"visualization":{"type":"string","enum":["chart","stat","table","list"]},"source":{"type":"string","enum":["traces","logs","metrics","product_events"]},"metric":{"type":"string"},"metric_name":{"type":"string"},"metric_type":{"type":"string","enum":["sum","gauge","histogram","exponential_histogram"]},"service":{"type":"string"},"service_name":{"type":"string"},"group_by":{"type":"string"},"where":{"type":"string"},"unit":{"type":"string","enum":["none","number","percent","percent_100","duration_ms","duration_s","duration_us","duration_ns","bytes","requests_per_sec","short"]}},"required":["title","source"],"additionalProperties":false}},"description":"Simplified widget specs, one per widget: { title, visualization?: chart|stat|table|list, source: traces|logs|metrics|product_events, metric?, metric_name?, metric_type?, service?, group_by?, where?, unit?: none|number|percent|percent_100|duration_ms|duration_s|duration_us|duration_ns|bytes|requests_per_sec|short }. group_by is service.name|span.name|status.code|http.method|none|attr. for traces, service.name|severity|none for logs, service.name|none|attr.|resource. for metrics, event.name|event.kind|source|host|page.path|service.name|group.id|none|attr. for product_events (query_data spellings like service, span_name also work). table needs a group_by; list shows recent traces or logs. Charts default to group_by service.name. where is a whereClause (describe_dashboard_schema \"queries\"), e.g. attr.state = \"idle\" to read one state of a per-state metric like system.cpu.utilization (unscoped it averages to about 1/states). unit percent expects a 0-1 fraction, percent_100 a 0-100 value."},"dashboard_json":{"type":"string","description":"The whole dashboard as JSON text, in the shape get_dashboard returns. Read describe_dashboard_schema first for the data-source kinds, units, aggregations and group-by tokens.","contentMediaType":"application/json"},"validate":{"type":"boolean","description":"Pass false to skip the post-create inspection"}},"required":["name"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"dashboard":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"widgetCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","publicId","name","widgetCount","createdAt","updatedAt"],"additionalProperties":true},"validation":{"type":"object","properties":{"ran":{"type":"boolean"},"inspected":{"type":"array","items":{"type":"object","properties":{"widgetId":{"type":"string"},"title":{"type":"string"},"visualization":{"type":"string"},"verdict":{"type":"string","enum":["looks_healthy","suspicious","broken","unsupported","skipped","error"]},"flags":{"type":"array","items":{"type":"string","enum":["EMPTY","ALL_NULLS","ALL_ZEROS","SINGLE_POINT","FLAT_LINE","SUSPICIOUS_GAP","NEGATIVE_VALUES","UNREALISTIC_MAGNITUDE","SINGLE_SERIES_DOMINATES","CARDINALITY_EXPLOSION","UNIT_MISMATCH","PERCENT_SCALE_MISMATCH","BROKEN_BREAKDOWN","EMPTY_GROUPING","METRIC_NOT_FOUND","BUILDER_WARNINGS"]}},"note":{"type":"string"},"seriesCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["widgetId","visualization","verdict","flags"],"additionalProperties":true}},"healthyCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"suspiciousCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"brokenCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"skippedCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"capped":{"type":"boolean"},"timeRange":{"type":"object","properties":{"startTime":{"type":"string"},"endTime":{"type":"string"},"source":{"type":"string","enum":["override","widget","dashboard","fallback"]}},"required":["startTime","endTime","source"],"additionalProperties":true}},"required":["ran","inspected","healthyCount","suspiciousCount","brokenCount","skippedCount","capped"],"additionalProperties":true},"source":{"type":"string","enum":["template","widgets","dashboard_json"]},"template":{"type":"string"},"renderWarnings":{"type":"array","items":{"type":"string"}}},"required":["dashboard","source","renderWarnings"],"additionalProperties":true},"annotations":{"title":"Create Dashboard","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}}, {"name":"update_dashboard","title":"Update Dashboard","description":"Change a dashboard's name, description or time_range. For widgets use add_dashboard_widget, update_dashboard_widget, remove_dashboard_widget, reorder_dashboard_widgets, or replace_dashboard_widgets for a validated rewrite of the whole list. `dashboard_json` replaces everything unvalidated; use it only to restore a saved document.","inputSchema":{"type":"object","properties":{"dashboard_id":{"type":"string","description":"Dashboard ID (ids from list_dashboards): its UUID or its REST id (dash_\u2026)"},"name":{"type":"string","description":"New dashboard name"},"description":{"type":"string","description":"New dashboard description"},"time_range":{"type":"string","description":"Relative shorthand: 15m, 6h, 24h, 7d, 2w, 3mo or \"today\". Up to 32 days."},"dashboard_json":{"type":"string","description":"The whole dashboard as JSON text, in the shape get_dashboard returns; replaces every widget. Prefer replace_dashboard_widgets.","contentMediaType":"application/json"}},"required":["dashboard_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"dashboard":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"widgetCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","publicId","name","widgetCount","createdAt","updatedAt"],"additionalProperties":true},"replaced":{"type":"boolean"},"renderWarnings":{"type":"array","items":{"type":"string"}}},"required":["dashboard","replaced","renderWarnings"],"additionalProperties":true},"annotations":{"title":"Update Dashboard","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}}, {"name":"add_dashboard_widget","title":"Add Dashboard Widget","description":"Add one widget to a dashboard. Pick `panel_type`, then one of: `data_source_json` plus `display_json` (query builder); `sql` (raw ClickHouse, must reference `$__orgFilter`; read describe_warehouse_tables first for table and column names); `display_json.funnel.steps` with panel_type funnel; `display_json.paths` with panel_type paths (the last two derive their data source). Read describe_dashboard_schema before authoring: data-source kinds, units (`percent` is a 0-1 fraction, `percent_100` is 0-100, the reverse of Grafana), aggregations, group-by tokens. Layout is auto-placed unless layout_json is given. The result carries a validation verdict; suspicious or broken means the chart will not render meaningfully as saved.","inputSchema":{"type":"object","properties":{"dashboard_id":{"type":"string","description":"Dashboard ID (ids from list_dashboards): its UUID or its REST id (dash_\u2026)"},"panel_type":{"type":"string","enum":["line","bar","hbar","area","pie","stat","gauge","table","list","histogram","heatmap","funnel","paths","markdown"],"description":"The widget kind, not its title (title goes in display_json.title). chartId and the raw-SQL display type are derived from it."},"visualization":{"type":"string","enum":["chart","hbar","pie","stat","gauge","table","list","histogram","heatmap","funnel","paths","markdown"],"description":"Legacy spelling of panel_type. It folds line/bar/area into `chart` and needs display_json.chartId to tell them apart; prefer panel_type."},"sql":{"type":"string","description":"Raw ClickHouse SQL with macros; `$__orgFilter` is required. Builds a `kind: \"raw_sql\"` data source and ignores data_source_json."},"display_type":{"type":"string","enum":["line","area","bar","table","stat","pie","histogram","heatmap","funnel","hbar"],"description":"Raw-SQL rendering when `sql` is set. Derived from panel_type; pass it only to override."},"granularity_seconds":{"type":"number","description":"Bucket size for a raw-SQL timeseries; computed from the dashboard range when omitted."},"data_source_json":{"type":"string","description":"The widget's `kind`-discriminated data source as JSON text (describe_dashboard_schema section data_sources). Required for the query-builder path; ignored with `sql`, derived for funnel and paths.","contentMediaType":"application/json"},"display_json":{"type":"string","description":"Display config as JSON text: { title?, unit?, thresholds?, chartId?, columns?, funnel?, paths?, ... } (describe_dashboard_schema section display). Required for the query-builder path; defaults to {} with `sql`.","contentMediaType":"application/json"},"layout_json":{"type":"string","description":"Grid rectangle { x, y, w, h } on the 12-column grid, as JSON text. Omit to auto-place.","contentMediaType":"application/json"},"widget_id":{"type":"string","description":"Stable id for the widget; a UUID when omitted."},"time_range_json":{"type":"string","contentMediaType":"application/json","contentSchema":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"type":"string"},"endTime":{"type":"string"}},"required":["type","startTime","endTime"],"additionalProperties":false}]},"description":"Pin the widget to its own window instead of the dashboard's: {\"type\":\"relative\",\"value\":\"30m\"} or {\"type\":\"absolute\",\"startTime\":\"...\",\"endTime\":\"...\"} (ISO 8601). Only for a tile that means a different window (a 30-minute \"active now\" stat on a 7-day board); the header labels the override."}},"required":["dashboard_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"dashboard":{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"widgetCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","publicId","name","widgetCount","createdAt","updatedAt"],"additionalProperties":true},"widgetId":{"type":"string"},"validation":{"type":"object","properties":{"ran":{"type":"boolean"},"inspected":{"type":"array","items":{"type":"object","properties":{"widgetId":{"type":"string"},"title":{"type":"string"},"visualization":{"type":"string"},"verdict":{"type":"string","enum":["looks_healthy","suspicious","broken","unsupported","skipped","error"]},"flags":{"type":"array","items":{"type":"string","enum":["EMPTY","ALL_NULLS","ALL_ZEROS","SINGLE_POINT","FLAT_LINE","SUSPICIOUS_GAP","NEGATIVE_VALUES","UNREALISTIC_MAGNITUDE","SINGLE_SERIES_DOMINATES","CARDINALITY_EXPLOSION","UNIT_MISMATCH","PERCENT_SCALE_MISMATCH","BROKEN_BREAKDOWN","EMPTY_GROUPING","METRIC_NOT_FOUND","BUILDER_WARNINGS"]}},"note":{"type":"string"},"seriesCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["widgetId","visualization","verdict","flags"],"additionalProperties":true}},"healthyCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"suspiciousCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"brokenCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"skippedCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"capped":{"type":"boolean"},"timeRange":{"type":"object","properties":{"startTime":{"type":"string"},"endTime":{"type":"string"},"source":{"type":"string","enum":["override","widget","dashboard","fallback"]}},"required":["startTime","endTime","source"],"additionalProperties":true}},"required":["ran","inspected","healthyCount","suspiciousCount","brokenCount","skippedCount","capped"],"additionalProperties":true},"panelType":{"type":"string"},"visualization":{"type":"string"},"layout":{"type":"object","properties":{"x":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"y":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"w":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"h":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["x","y","w","h"],"additionalProperties":true},"widgetTimeRange":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["relative"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":true},{"type":"object","properties":{"type":{"type":"string","enum":["absolute"]},"startTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"},"endTime":{"$ref":"#/$defs/@maple~1IsoDateTimeString"}},"required":["type","startTime","endTime"],"additionalProperties":true}]},"renderWarnings":{"type":"array","items":{"type":"string"}}},"required":["dashboard","widgetId","panelType","visualization","renderWarnings"],"additionalProperties":true,"$defs":{"@maple/IsoDateTimeString":{"type":"string"}}},"annotations":{"title":"Add Dashboard Widget","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}}, diff --git a/apps/api/src/routes/internal/query-engine.http.ts b/apps/api/src/routes/internal/query-engine.http.ts index c76c493620..e471777947 100644 --- a/apps/api/src/routes/internal/query-engine.http.ts +++ b/apps/api/src/routes/internal/query-engine.http.ts @@ -7,6 +7,8 @@ import { CurrentTenant, MapleInternalApi, RawSqlExecuteResponse, + PromqlExecuteResponse, + QueryEngineValidationError, SpanHierarchyResponse, ProfileSampleTypesResponse, ProfileStacksResponse, @@ -157,6 +159,7 @@ import { import type { QueryEngineDirectError } from "@maple/query-engine/runtime" import { makeRunAuditedRawSql } from "@maple/backend/services/warehouse/audited-raw-sql" import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { alignServiceApiBucketSeconds, CH, @@ -374,6 +377,7 @@ export const HttpQueryEngineLive = HttpApiBuilder.group(MapleInternalApi, "query Effect.gen(function* () { const queryEngine = yield* QueryEngineService const warehouse = yield* WarehouseQueryService + const promql = yield* PromqlQueryService const runtimeReleases = yield* RuntimeReleaseCatalog const runtimeAdvisories = yield* RuntimeAdvisoryCatalog const reads = makeDashboardReads({ warehouse, queryEngine }) @@ -2715,6 +2719,60 @@ export const HttpQueryEngineLive = HttpApiBuilder.group(MapleInternalApi, "query "productEventTraceSamples", serve.rows(Queries.productEventTraceSamples, ProductEventTraceSamplesResponse), ) + .handle("executePromql", ({ payload }) => + Effect.gen(function* () { + const tenant = yield* CurrentTenant.Context + const result = yield* mapExecError( + promql.widget(tenant, { + query: payload.query, + startTime: payload.startTime, + endTime: payload.endTime, + ...(payload.legendFormat === undefined + ? undefined + : { legendFormat: payload.legendFormat }), + ...(payload.minStepSeconds === undefined + ? undefined + : { minStepSeconds: payload.minStepSeconds }), + ...(payload.maxDataPoints === undefined + ? undefined + : { maxDataPoints: payload.maxDataPoints }), + ...(payload.displayType === undefined + ? undefined + : { displayType: payload.displayType }), + }), + "promql query failed", + ).pipe( + // A query that does not parse or cannot run is the author's to fix: a 400 with the reason. + Effect.catchTags({ + "@maple/backend/promql/PromqlBadQueryError": (error) => + Effect.fail( + new QueryEngineValidationError({ + message: `Invalid PromQL: ${error.message}`, + details: + error.position === undefined + ? [] + : [`position ${error.position}`], + }), + ), + "@maple/backend/promql/PromqlExecutionError": (error) => + Effect.fail( + new QueryEngineValidationError({ + message: error.message, + details: [], + }), + ), + }), + ) + return new PromqlExecuteResponse({ + data: result.rows, + meta: { + resultType: result.resultType, + seriesCount: result.seriesCount, + stepSeconds: result.stepSeconds, + }, + }) + }), + ) .handle("executeRawSql", ({ payload }) => Effect.gen(function* () { const tenant = yield* CurrentTenant.Context diff --git a/apps/api/src/routes/v2/alchemy-provider.integration.test.ts b/apps/api/src/routes/v2/alchemy-provider.integration.test.ts index 83a0047fed..2e063d8ef6 100644 --- a/apps/api/src/routes/v2/alchemy-provider.integration.test.ts +++ b/apps/api/src/routes/v2/alchemy-provider.integration.test.ts @@ -73,6 +73,7 @@ import { InvestigationService } from "@maple/backend/services/errors/Investigati import { compiledQueryOf } from "@maple/query-engine/execution" import { InvestigationStarter } from "@maple/backend/services/errors/InvestigationStarter" import { SloReadService } from "@maple/backend/services/slos/SloReadService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" const createdDbs: TestDb[] = [] afterEach(() => cleanupTestDbs(createdDbs)) @@ -237,7 +238,12 @@ const makeHarness = () => { Layer.provide( Layer.mergeAll( HttpV2DashboardsLive.pipe( - Layer.provide(Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make)), + Layer.provide( + Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make).pipe( + // Over the inert warehouse, not the real one `PromqlQueryService.layer` brings. + Layer.provide(Layer.effect(PromqlQueryService, PromqlQueryService.make)), + ), + ), ), HttpV2AlertDestinationsLive, HttpV2AlertRulesLive, diff --git a/apps/api/src/routes/v2/dashboards.http.test.ts b/apps/api/src/routes/v2/dashboards.http.test.ts index e176ce375c..249798fe10 100644 --- a/apps/api/src/routes/v2/dashboards.http.test.ts +++ b/apps/api/src/routes/v2/dashboards.http.test.ts @@ -39,6 +39,7 @@ import { WarehouseServiceStubLayer, } from "./v2-test-support" import { DashboardWidgetDataService } from "@maple/backend/services/dashboards/DashboardWidgetDataService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { HttpV2DashboardsLive } from "./dashboards.http" import { HttpV2SharePublicLive } from "./share.http" import { OrganizationService } from "@maple/backend/services/org/OrganizationService" @@ -152,7 +153,12 @@ const makeHarness = () => { Layer.mergeAll( // Real widget evaluation over the inert warehouse and query engine below. HttpV2DashboardsLive.pipe( - Layer.provide(Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make)), + Layer.provide( + Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make).pipe( + // Over the inert warehouse below, not the real one `PromqlQueryService.layer` brings. + Layer.provide(Layer.effect(PromqlQueryService, PromqlQueryService.make)), + ), + ), ), SharePublicLive, ), diff --git a/apps/api/src/runtime/query-http-graph.ts b/apps/api/src/runtime/query-http-graph.ts index b2744c1b7c..c555a7cbdd 100644 --- a/apps/api/src/runtime/query-http-graph.ts +++ b/apps/api/src/runtime/query-http-graph.ts @@ -15,6 +15,7 @@ import { OrganizationRegionService } from "@maple/backend/services/org/Organizat import { OrganizationFeatureFlagsService } from "@maple/backend/services/org/OrganizationFeatureFlagsService" import { AuditLogService } from "@maple/backend/services/audit/AuditLogService" import { QueryEngineService } from "@maple/backend/services/warehouse/QueryEngineService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { RuntimeAdvisoryCatalog } from "@maple/backend/services/security/RuntimeAdvisoryCatalog" import { RuntimeReleaseCatalog } from "@maple/backend/services/security/RuntimeReleaseCatalog" @@ -40,6 +41,7 @@ export const QueryRoutes = Layer.mergeAll( Layer.mergeAll( QueryEngineService.layer, WarehouseQueryService.layer, + PromqlQueryService.layer, AuditLogService.layer, OrganizationRegionService.layer, RuntimeReleaseCatalog.layer, diff --git a/apps/api/src/runtime/service-graph.ts b/apps/api/src/runtime/service-graph.ts index 9cce5f10cf..3c7f335127 100644 --- a/apps/api/src/runtime/service-graph.ts +++ b/apps/api/src/runtime/service-graph.ts @@ -139,8 +139,8 @@ import { AuditDetectionsService } from "@maple/backend/services/audit-trail/Audi import { IntegrationInventoryService } from "@maple/backend/services/integrations/IntegrationInventoryService" import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" import { QueryEngineService } from "@maple/backend/services/warehouse/QueryEngineService" -import { TelemetryReadService } from "@maple/backend/services/warehouse/TelemetryReadService" import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" +import { TelemetryReadService } from "@maple/backend/services/warehouse/TelemetryReadService" import { OrgClickHouseSettingsService } from "@maple/backend/services/org/OrgClickHouseSettingsService" import { VcsSourceService } from "@maple/backend/services/integrations/vcs/VcsSourceService" import { CiAnalyticsService } from "@maple/backend/services/pr-review/CiAnalyticsService" @@ -255,11 +255,11 @@ export const HttpServicesLive = Layer.mergeAll( IntegrationInventoryService.layer, WarehouseQueryService.layer, QueryEngineService.layer, + PromqlQueryService.layer, RuntimeReleaseCatalog.layer, RuntimeAdvisoryCatalog.layer, DependencyScanService.layer, TelemetryReadService.layer, - PromqlQueryService.layer, DashboardWidgetDataService.layer, AlertDestinationsService.layer, AlertReadModelsService.layer, diff --git a/apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json b/apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json index 2ca50d523d..451ba83fd2 100644 --- a/apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json +++ b/apps/ios/Packages/MapleAPI/Sources/MapleAPI/openapi.json @@ -3597,6 +3597,141 @@ ], "type": "object" }, + { + "additionalProperties": false, + "properties": { + "display_type": { + "type": "string" + }, + "kind": { + "enum": [ + "promql" + ], + "type": "string" + }, + "legend_format": { + "maxLength": 500, + "type": "string" + }, + "min_step_seconds": { + "exclusiveMinimum": 0, + "type": "number" + }, + "query": { + "maxLength": 10000, + "type": "string" + }, + "transform": { + "additionalProperties": false, + "properties": { + "compute_ratio": { + "additionalProperties": false, + "properties": { + "denominator_names": { + "items": { + "type": "string" + }, + "type": "array" + }, + "numerator_name": { + "type": "string" + } + }, + "required": [ + "numerator_name", + "denominator_names" + ], + "type": "object" + }, + "field_map": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "flatten_series": { + "additionalProperties": false, + "properties": { + "value_field": { + "type": "string" + } + }, + "required": [ + "value_field" + ], + "type": "object" + }, + "hide_series": { + "additionalProperties": false, + "properties": { + "base_names": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "base_names" + ], + "type": "object" + }, + "limit": { + "type": "number" + }, + "reduce_to_value": { + "additionalProperties": false, + "properties": { + "aggregate": { + "enum": [ + "first", + "sum", + "count", + "avg", + "max", + "min" + ], + "type": "string" + }, + "field": { + "type": "string" + } + }, + "required": [ + "field" + ], + "type": "object" + }, + "sort_by": { + "additionalProperties": false, + "properties": { + "direction": { + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "field": { + "type": "string" + } + }, + "required": [ + "field", + "direction" + ], + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "kind", + "query" + ], + "type": "object" + }, { "additionalProperties": false, "properties": { diff --git a/apps/web/src/lab/entries/promql-widget.ts b/apps/web/src/lab/entries/promql-widget.ts new file mode 100644 index 0000000000..4915ada715 --- /dev/null +++ b/apps/web/src/lab/entries/promql-widget.ts @@ -0,0 +1,6 @@ +import { defineLab } from "../define" +import { Model, init, update, view } from "../promql-widget-lab" + +// `/lab/promql-widget`: the widget editor over a PromQL line chart, `?state=error` for a parse error. + +export const lab = defineLab("PromQL widget", { Model, init, update, view }) diff --git a/apps/web/src/lab/promql-widget-fixture.ts b/apps/web/src/lab/promql-widget-fixture.ts new file mode 100644 index 0000000000..e42dc0a95e --- /dev/null +++ b/apps/web/src/lab/promql-widget-fixture.ts @@ -0,0 +1,31 @@ +import type { PromqlQueryResult } from "@maple/query-engine" +import { Array as Arr } from "effect" + +// Request rate per service over the last hour at a 30s step, as the engine returns a range query. + +const STEP_MS = 30_000 +const STEPS = 121 + +const SERVICES = [ + { job: "checkout", base: 42, swing: 9, phase: 0 }, + { job: "api-gateway", base: 118, swing: 22, phase: 1.3 }, + { job: "payments", base: 17, swing: 5, phase: 2.1 }, +] as const + +export const promqlLabResult = (nowMs: number): PromqlQueryResult => { + const endMs = Math.floor(nowMs / STEP_MS) * STEP_MS + const startMs = endMs - (STEPS - 1) * STEP_MS + return { + resultType: "matrix", + result: Arr.map(SERVICES, ({ job, base, swing, phase }) => ({ + labels: { job, instance: `${job}-0` }, + points: Arr.makeBy(STEPS, (i) => ({ + t: startMs + i * STEP_MS, + v: + Math.round( + (base + swing * Math.sin(i / 9 + phase) + (swing / 3) * Math.sin(i / 2.3)) * 100, + ) / 100, + })), + })), + } +} diff --git a/apps/web/src/lab/promql-widget-lab.ts b/apps/web/src/lab/promql-widget-lab.ts new file mode 100644 index 0000000000..a250eac93c --- /dev/null +++ b/apps/web/src/lab/promql-widget-lab.ts @@ -0,0 +1,135 @@ +import { OrgId } from "@maple/domain" +import { DashboardDocument, RawSqlDisplayType } from "@maple/domain/http" +import { parseWarehouseDateTime, promqlRowsForDisplay } from "@maple/query-engine" +import { Effect, Option, Result, Schema, Array as Arr, String as Str } from "effect" +import { Command } from "foldkit" +import type { Html, HtmlBuilder } from "foldkit/html" +import type { PageContext } from "../page/contract" +import { FetchWidget } from "../page/dashboards/widget/command" +import { Message } from "../page/dashboards/widget/message" +import { Model } from "../page/dashboards/widget/model" +import { update as pageUpdate } from "../page/dashboards/widget/page-update" +import { init as pageInit } from "../page/dashboards/widget/update" +import { view as pageView } from "../page/dashboards/widget/view" +import { promqlLabResult } from "./promql-widget-fixture" + +// The widget editor over a PromQL line chart. Its preview fetches are answered here with +// rows from the real `promqlRowsForDisplay`, so the lab needs no API and no session. + +export { Message, Model } + +const context: PageContext = { + orgId: Schema.decodeSync(OrgId)("org_lab"), + pinnedNamespace: null, + timeZone: "UTC", +} + +const NOW = parseWarehouseDateTime("2026-11-15 12:00:00") + +const document = Schema.decodeSync(DashboardDocument)({ + id: "dash_lab", + name: "Prometheus", + timeRange: { type: "relative", value: "1h" }, + widgets: [ + { + id: "rate", + visualization: "chart", + dataSource: { + kind: "promql", + query: "sum by (job) (rate(http_server_request_duration_seconds_count[$__rate_interval]))", + legendFormat: "{{job}}", + displayType: "line", + }, + display: { title: "Request rate by service", chartId: "query-builder-line" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, + }, + ], + createdAt: "2026-11-01T12:00:00.000Z", + updatedAt: "2026-11-15T12:00:00.000Z", + schemaVersion: 3, +}) + +const PreviewParams = Schema.Struct({ + promql: Schema.String, + legendFormat: Schema.optional(Schema.String), + displayType: Schema.optional(RawSqlDisplayType), +}) + +/** A query whose parentheses do not balance reads as the parser's refusal. */ +const isBalanced = (query: string): boolean => + Arr.reduce(Str.split(query, ""), 0, (depth, char) => + depth < 0 ? depth : char === "(" ? depth + 1 : char === ")" ? depth - 1 : depth, + ) === 0 + +const LabFetchWidget = Command.define("LabFetchPromqlPreview", { + args: { key: Schema.String, params: Schema.Record(Schema.String, Schema.Unknown) }, + messages: [Message.CompletedFetchWidget], + execute: ({ key, params }) => + Effect.sync(() => { + const decoded = Schema.decodeUnknownOption(PreviewParams)(params) + if (Option.isNone(decoded) || !isBalanced(decoded.value.promql)) { + return Message.CompletedFetchWidget({ + key, + result: Result.fail({ + title: null, + message: "Invalid PromQL: 1:72: parse error: unclosed left parenthesis", + kind: "decode", + }), + }) + } + const { legendFormat, displayType } = decoded.value + const rows = promqlRowsForDisplay(promqlLabResult(NOW), { + ...(legendFormat === undefined ? undefined : { legendFormat }), + ...(displayType === undefined ? undefined : { displayType }), + }) + return Message.CompletedFetchWidget({ key, result: Result.succeed({ data: rows }) }) + }), +}) + +const FetchArgs = Schema.Struct({ key: Schema.String, params: Schema.Record(Schema.String, Schema.Unknown) }) + +type PageCommand = NonNullable["commands"]>[number] + +/** Preview fetches answered here; any other request that would reach the API is dropped. */ +const offline = (commands: ReadonlyArray | undefined): ReadonlyArray => + Arr.flatMap(commands ?? [], (command) => { + if (command.name === FetchWidget.name) { + return Option.match(Schema.decodeUnknownOption(FetchArgs)(command.args), { + onNone: () => [], + onSome: (args) => [LabFetchWidget(args)], + }) + } + return Str.startsWith("Fetch")(command.name) || command.name === "SaveWidget" ? [] : [command] + }) + +const BROKEN_QUERY = "sum by (job) (rate(http_server_request_duration_seconds_count[$__rate_interval])" + +/** `?state=error` opens on a query the parser refuses. */ +const wantsError = (): boolean => + typeof window !== "undefined" && new URLSearchParams(window.location.search).get("state") === "error" + +export const init = () => { + const opened = pageInit({ dashboardId: "dash_lab", widgetId: "rate", search: {} }, context) + const seeded = Arr.reduce( + [ + Message.CompletedReadClock({ nowMs: NOW }), + Message.UpdatedDashboard({ orgId: context.orgId, maybeDocument: Option.some(document) }), + ...(wantsError() + ? [Message.ChangedPromql({ value: BROKEN_QUERY }), Message.ClickedRunPreview()] + : []), + ], + { model: opened.model, commands: offline(opened.commands) }, + (step, message) => { + const next = pageUpdate(step.model, message, context) + return { model: next.model, commands: [...step.commands, ...offline(next.commands)] } + }, + ) + return seeded +} + +export const update = (model: Model, message: Message) => { + const next = pageUpdate(model, message, context) + return { model: next.model, commands: offline(next.commands) } +} + +export const view = (model: Model, h: HtmlBuilder): Html => pageView(model, { context }, h) diff --git a/apps/web/src/lab/registry.ts b/apps/web/src/lab/registry.ts index 096714eb03..e557d0486e 100644 --- a/apps/web/src/lab/registry.ts +++ b/apps/web/src/lab/registry.ts @@ -651,6 +651,14 @@ export const LAB_ENTRIES: ReadonlyArray = [ kind: "lab", session: "none", }, + { + path: "/lab/promql-widget", + title: "PromQL widget", + description: + "The widget editor over a PromQL line chart with fixture series; ?state=error shows the parser's message.", + kind: "lab", + session: "none", + }, { path: "/lab/query-builder", title: "Query builder", diff --git a/apps/web/src/page/dashboards/kit/share-support.ts b/apps/web/src/page/dashboards/kit/share-support.ts index 64636b4329..1697fcd2e2 100644 --- a/apps/web/src/page/dashboards/kit/share-support.ts +++ b/apps/web/src/page/dashboards/kit/share-support.ts @@ -16,7 +16,7 @@ const SUPPORTED_ROUTE_ENDPOINTS = new Set([ /** Prose for the dialog, so the copy and the list cannot disagree. */ export const SHAREABLE_WIDGET_KINDS = - "query-builder charts, raw SQL, markdown, funnels, paths, and the errors, service and logs tiles" + "query-builder charts, raw SQL, PromQL, markdown, funnels, paths, and the errors, service and logs tiles" interface WidgetLike { readonly id: string @@ -34,7 +34,7 @@ export const isShareSupported = (dataSource: unknown): boolean => { return Option.match(decodeSource(dataSource), { onNone: () => false, onSome: ({ kind, endpoint }) => - kind === "query" || kind === "raw_sql" || kind === "static" + kind === "query" || kind === "raw_sql" || kind === "promql" || kind === "static" ? true : endpoint !== undefined && SUPPORTED_ROUTE_ENDPOINTS.has(endpoint), }) diff --git a/apps/web/src/page/dashboards/widget/lowering.ts b/apps/web/src/page/dashboards/widget/lowering.ts index 766e2dfde1..938702f354 100644 --- a/apps/web/src/page/dashboards/widget/lowering.ts +++ b/apps/web/src/page/dashboards/widget/lowering.ts @@ -8,6 +8,7 @@ import { import { dataSourceEndpoint, dataSourceQuerySet, + dataSourcePromql, dataSourceRawSql, dataSourceRouteParams, dataSourceTransform, @@ -74,7 +75,7 @@ const toStatAggregate = (value: unknown): EditorState["statAggregate"] => /** The table's row limit input caps at this many rows. */ export const ROW_LIMIT_MAX = 1000 -const parseRowLimit = (raw: string): number | undefined => { +export const parseRowLimit = (raw: string): number | undefined => { const parsed = parsePositiveNumber(raw) return parsed === undefined ? undefined : Math.min(parsed, ROW_LIMIT_MAX) } @@ -126,7 +127,8 @@ export const toInitialState = (widget: Widget): EditorState => { !isProductFunnel && (loaded === null || loaded.queries.length === 0) // A SQL widget is not a preset: it switches to the builder like any other query. - const isSql = dataSourceRawSql(widget.dataSource) !== null + // A Raw SQL or PromQL widget opens the Builder on a fresh query, not a locked stand-in. + const isSql = dataSourceRawSql(widget.dataSource) !== null || dataSourcePromql(widget.dataSource) !== null const routeStandIn = isStandIn && querySet === null && !isSql ? routeStandInOf(routeOf(widget)) : null const standInQuery = routeStandIn?.kind === "builder" diff --git a/apps/web/src/page/dashboards/widget/message.ts b/apps/web/src/page/dashboards/widget/message.ts index 99a6d0652f..6de97c2a91 100644 --- a/apps/web/src/page/dashboards/widget/message.ts +++ b/apps/web/src/page/dashboards/widget/message.ts @@ -60,6 +60,9 @@ export const Message = defineMessageUnion({ ClickedRunPreview: {}, ChangedSql: { value: Schema.String }, ChangedSqlBucket: { value: Schema.String }, + ChangedPromql: { value: Schema.String }, + ChangedPromqlLegend: { value: Schema.String }, + ChangedPromqlMinStep: { value: Schema.String }, ClickedSqlToken: { token: Schema.String }, CompletedInsertSqlToken: { sql: Schema.String, caret: Schema.Number }, CompletedFocusSql: {}, diff --git a/apps/web/src/page/dashboards/widget/model.ts b/apps/web/src/page/dashboards/widget/model.ts index 79f4cf1886..b056becf01 100644 --- a/apps/web/src/page/dashboards/widget/model.ts +++ b/apps/web/src/page/dashboards/widget/model.ts @@ -19,6 +19,7 @@ import { TableSort } from "../kit/tiles" import { WidgetFailure, WidgetGate } from "../kit/widget-data" import { EditorState } from "./editor-state" import { RawSqlState } from "./raw-sql" +import { PromqlState } from "./promql" import { MetricKeysSchema } from "../../kit/query-builder/metrics-body" import { MetricPageSchema } from "../../kit/query-builder/metric-options" import { Suggestion } from "./suggestions" @@ -26,7 +27,7 @@ import { Suggestion } from "./suggestions" export const Status = Schema.Literals(["Loading", "Ready", "Missing"]) export type Status = typeof Status.Type -export const SourceMode = Schema.Literals(["builder", "rawSql"]) +export const SourceMode = Schema.Literals(["builder", "rawSql", "promql"]) export type SourceMode = typeof SourceMode.Type export const Model = Schema.Struct({ @@ -45,6 +46,7 @@ export const Model = Schema.Struct({ /** The source the widget was opened in: switching tabs is an unsaved change. */ initialSourceMode: SourceMode, rawSql: Schema.NullOr(RawSqlState), + promql: Schema.NullOr(PromqlState), /** The preview's window: the board's range on open, then the editor's own picker (never saved). */ timeRange: Schema.NullOr(TimeRangeSchema), nowMs: Schema.NullOr(Schema.Number), diff --git a/apps/web/src/page/dashboards/widget/page-update.ts b/apps/web/src/page/dashboards/widget/page-update.ts index 315f8d764f..209ecbb675 100644 --- a/apps/web/src/page/dashboards/widget/page-update.ts +++ b/apps/web/src/page/dashboards/widget/page-update.ts @@ -21,6 +21,7 @@ import { whereFieldsInputsOf, whereFieldsOf } from "./where-fields" import { reseedForType } from "./raw-sql" import { withDefaultMetric } from "./metric-options" import { runSqlPreview, sqlStep } from "./sql-step" +import { promqlStep, runPromqlPreview, savedPromql } from "./promql-step" import { Message } from "./message" import type { Model } from "./model" import { @@ -36,7 +37,9 @@ import { import { backHref, canApply, + editedSourceOf, editedWidget, + isPromqlSource, isSqlSource, editState, leave, @@ -105,7 +108,12 @@ const tabsStep = (model: Model, context: PageContext, message: Tabs.Message): Re { ...model, sourceTabs: next.model, - sourceMode: next.model.selected === "rawSql" ? "rawSql" : "builder", + sourceMode: + next.model.selected === "rawSql" + ? "rawSql" + : next.model.selected === "promql" + ? "promql" + : "builder", }, context, ) @@ -155,7 +163,7 @@ const apply = (model: Model, context: PageContext, listQueryId: string | null): const widget = widgetOf(model) if (model.isSaving || widget === null || model.state === null) return { model } if (!canApply(model)) return { model } - const rawSql = isSqlSource(model) ? (model.rawSql?.draft ?? null) : null + const source = editedSourceOf(model, "draft") if (listQueryId === null && isEngineList(model, model.state)) return { model, commands: generate("applyList", "") } return { @@ -164,7 +172,7 @@ const apply = (model: Model, context: PageContext, listQueryId: string | null): SaveWidget({ orgId: context.orgId, dashboardId: model.dashboardId, - widget: editedWidget(widget, withListQueryId(model.state, listQueryId), rawSql), + widget: editedWidget(widget, withListQueryId(model.state, listQueryId), source), }), ], } @@ -282,7 +290,14 @@ export const update = (model: Model, message: Message, context: PageContext): Re ClickedRemoveFormula: ({ formulaId }) => editState(model, context, (state) => removeFormula(state, formulaId)), ClickedRunPreview: () => - isSqlSource(model) ? runSqlPreview(model, context) : runPreview(model, context), + isPromqlSource(model) + ? runPromqlPreview(model, context) + : isSqlSource(model) + ? runSqlPreview(model, context) + : runPreview(model, context), + ChangedPromql: (m) => promqlStep(model, m), + ChangedPromqlLegend: (m) => promqlStep(model, m), + ChangedPromqlMinStep: (m) => promqlStep(model, m), ChangedSql: (m) => sqlStep(model, m), ChangedSqlBucket: (m) => sqlStep(model, m), ClickedSqlToken: (m) => sqlStep(model, m), @@ -389,6 +404,7 @@ export const update = (model: Model, message: Message, context: PageContext): Re initial: model.state, initialSourceMode: model.sourceMode, rawSql: savedSql(model), + promql: savedPromql(model), }, backHref(model), ) @@ -408,6 +424,7 @@ export const update = (model: Model, message: Message, context: PageContext): Re initial: model.state, sourceMode: model.initialSourceMode, rawSql: savedSql(model), + promql: savedPromql(model), }, model.pendingLeaveUrl ?? backHref(model), ), diff --git a/apps/web/src/page/dashboards/widget/promql-step.ts b/apps/web/src/page/dashboards/widget/promql-step.ts new file mode 100644 index 0000000000..de2806429c --- /dev/null +++ b/apps/web/src/page/dashboards/widget/promql-step.ts @@ -0,0 +1,46 @@ +import type { PageContext } from "../../contract" +import type { Message } from "./message" +import type { Model } from "./model" +import { isRunnablePromql, type PromqlDraft, type PromqlState } from "./promql" +import { planPreview, type Return } from "./update" + +export const PROMQL_TEXTAREA_ID = "widget-editor-promql" + +type PromqlMessage = Extract< + Message, + { readonly _tag: "ChangedPromql" | "ChangedPromqlLegend" | "ChangedPromqlMinStep" } +> + +const withDraft = (model: Model, change: (draft: PromqlDraft) => PromqlDraft): Model => + model.promql === null + ? model + : { ...model, promql: { ...model.promql, draft: change(model.promql.draft) } } + +/** The min step input: empty is auto, anything else at least one second. */ +const minStepOf = (value: string): number | null => { + const parsed = Number(value) + return value === "" || !Number.isFinite(parsed) ? null : Math.max(1, parsed) +} + +export const promqlStep = (model: Model, message: PromqlMessage): Return => { + switch (message._tag) { + case "ChangedPromql": + return { model: withDraft(model, (draft) => ({ ...draft, query: message.value })) } + case "ChangedPromqlLegend": + return { model: withDraft(model, (draft) => ({ ...draft, legendFormat: message.value })) } + case "ChangedPromqlMinStep": + return { + model: withDraft(model, (draft) => ({ ...draft, minStepSeconds: minStepOf(message.value) })), + } + } +} + +/** The draft taken as the opened one, so a discarded or saved draft no longer reads as dirty. */ +export const savedPromql = (model: Model): PromqlState | null => + model.promql === null ? null : { ...model.promql, initial: model.promql.draft } + +/** Run preview in PromQL: the draft is staged and the preview re-planned, unless the query is empty. */ +export const runPromqlPreview = (model: Model, context: PageContext): Return => + model.promql === null || !isRunnablePromql(model.promql) + ? { model } + : planPreview({ ...model, promql: { ...model.promql, staged: model.promql.draft } }, context) diff --git a/apps/web/src/page/dashboards/widget/promql.scene.test.ts b/apps/web/src/page/dashboards/widget/promql.scene.test.ts new file mode 100644 index 0000000000..89124b4615 --- /dev/null +++ b/apps/web/src/page/dashboards/widget/promql.scene.test.ts @@ -0,0 +1,210 @@ +import { OrgId } from "@maple/domain" +import { DashboardDocument, DashboardWidgetSchema } from "@maple/domain/http" +import { ResolveThemeColors } from "@maple/views/charts/theme-colors" +import * as Tabs from "@maple/views/ui/tabs" +import { Option, Result, Schema, Array as Arr } from "effect" +import { + Command as SceneCommand, + expect as expectView, + given, + Mount, + scene, + text, + withViewInputs, +} from "foldkit/scene" +import { describe, expect, test } from "vitest" +import type { PageContext } from "../../contract" +import { FetchWidget, MeasurePreview, SaveWidget } from "./command" +import { Message } from "./message" +import type { Model } from "./model" +import { update } from "./page-update" +import { init, isDirty, previewWidgetOf } from "./update" +import { view as pageView } from "./view" + +// The editor over a PromQL line chart: the tab it opens on, the preview it asks for, the +// parser's message under the query, and what Apply writes. + +const orgId = Schema.decodeSync(OrgId)("org_acme") +const context: PageContext = { orgId, pinnedNamespace: null, timeZone: "UTC" } +const pageUpdate = (model: Model, message: Message) => update(model, message, context) +const view = withViewInputs(pageView, { context })() + +const QUERY = 'sum by (job) (rate(http_requests_total{env=~"$env"}[$__rate_interval]))' + +const requestRate = { + id: "rate", + visualization: "chart", + dataSource: { kind: "promql", query: QUERY, legendFormat: "{{job}}", displayType: "line" }, + display: { title: "Request rate", chartId: "query-builder-line" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, +} + +const document = Schema.decodeUnknownSync(DashboardDocument)({ + id: "dash_promql", + name: "Prometheus", + timeRange: { type: "relative", value: "1h" }, + widgets: [requestRate], + variables: [ + { + name: "env", + type: "custom", + options: [{ value: "prod" }, { value: "staging" }], + defaultValue: "prod", + }, + ], + createdAt: "2026-09-19T12:00:00.000Z", + updatedAt: "2026-09-28T12:00:00.000Z", + schemaVersion: 3, +}) + +type Step = { readonly model: Model; readonly commands: ReadonlyArray<{ name: string; args?: unknown }> } + +const runAll = (model: Model, messages: ReadonlyArray): Step => { + const start: Step = { model, commands: [] } + return Arr.reduce(messages, start, (step, message) => { + const next = pageUpdate(step.model, message) + return { model: next.model, commands: [...step.commands, ...(next.commands ?? [])] } + }) +} + +const opened = () => + runAll(init({ dashboardId: "dash_promql", widgetId: "rate", search: {} }, context).model, [ + Message.CompletedReadClock({ nowMs: Date.parse("2026-10-01T12:00:00Z") }), + Message.UpdatedDashboard({ orgId, maybeDocument: Option.some(document) }), + ]) + +const FetchArgs = Schema.Struct({ + key: Schema.String, + endpoint: Schema.String, + params: Schema.Record(Schema.String, Schema.Unknown), +}) +const fetchesOf = (step: Step) => + Arr.flatMap(step.commands, ({ name, args }) => + name === FetchWidget.name ? Option.toArray(Schema.decodeUnknownOption(FetchArgs)(args)) : [], + ) + +const mounted = (model: Model) => + [ + given(model), + Mount.resolve(ResolveThemeColors, Message.ResolvedThemeColors({ colors: {} })), + Mount.resolve(MeasurePreview, Message.MeasuredPreview({ widthPx: 800 })), + Mount.resolve( + Tabs.MeasureTabIndicator, + Tabs.Message.MeasuredIndicator({ + rect: { left: 0, right: 225, top: 4, bottom: 5, width: 112, height: 32 }, + }), + ), + ] as const + +const decodeSave = Schema.decodeUnknownOption(Schema.Struct({ widget: DashboardWidgetSchema })) + +describe("widget editor over a PromQL widget", () => { + test("opens on the PromQL tab and previews the query with the variable filled", () => { + const step = opened() + expect(step.model.sourceMode).toBe("promql") + expect(isDirty(step.model)).toBe(false) + const [fetch] = fetchesOf(step) + expect(fetch?.endpoint).toBe("promql_chart") + expect(fetch?.params).toMatchObject({ + promql: 'sum by (job) (rate(http_requests_total{env=~"prod"}[$__rate_interval]))', + legendFormat: "{{job}}", + displayType: "line", + }) + }) + + test("renders the query, legend and min step fields", () => { + scene( + { update: pageUpdate, view }, + ...mounted(opened().model), + expectView(text("PromQL query")).toExist(), + expectView(text("Legend")).toExist(), + expectView(text("Min step (s)")).toExist(), + expectView(text("Run preview")).toExist(), + ) + }) + + test("shows the parser's message under the query when the preview refuses it", () => { + const step = opened() + const key = fetchesOf(step)[0]?.key ?? expect.unreachable("the preview fetched") + const refused = Message.CompletedFetchWidget({ + key, + result: Result.fail({ + title: null, + message: "Invalid PromQL: unexpected end of input", + kind: "decode", + }), + }) + // A failed preview is asked again on the next plan, and refused again. + scene( + { update: pageUpdate, view }, + ...mounted(pageUpdate(step.model, refused).model), + SceneCommand.resolve(FetchWidget, refused), + expectView(text("Invalid PromQL: unexpected end of input")).toExist(), + ) + }) + + test("an edit waits for Run preview, and Apply writes the promql source", () => { + const edited = runAll(opened().model, [ + Message.ChangedPromql({ value: "up" }), + Message.ChangedPromqlLegend({ value: "{{instance}}" }), + Message.ChangedPromqlMinStep({ value: "60" }), + ]) + expect(fetchesOf(edited)).toEqual([]) + expect(isDirty(edited.model)).toBe(true) + const previewed = runAll(edited.model, [Message.ClickedRunPreview()]) + expect(fetchesOf(previewed)[0]?.params).toMatchObject({ promql: "up", minStepSeconds: 60 }) + const saved = pageUpdate(previewed.model, Message.ClickedApply()).commands ?? [] + const save = Arr.findFirst(saved, ({ name }) => name === SaveWidget.name) + const widget = Option.getOrNull(Option.flatMap(save, ({ args }) => decodeSave(args)))?.widget + expect(widget?.dataSource).toEqual({ + kind: "promql", + query: "up", + legendFormat: "{{instance}}", + minStepSeconds: 60, + displayType: "line", + }) + }) + + test("a table's Row limit is saved on Apply and read back when the widget reopens", () => { + const tableWidget = { + id: "jobs", + visualization: "table", + dataSource: { kind: "promql", query: "up", displayType: "table", transform: { limit: 50 } }, + display: { title: "Jobs" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, + } + const openWith = (widget: unknown) => + runAll(init({ dashboardId: "dash_promql", widgetId: "jobs", search: {} }, context).model, [ + Message.CompletedReadClock({ nowMs: Date.parse("2026-10-01T12:00:00Z") }), + Message.UpdatedDashboard({ + orgId, + maybeDocument: Option.some( + Schema.decodeUnknownSync(DashboardDocument)({ ...document, widgets: [widget] }), + ), + }), + ]) + const opened = openWith(tableWidget) + expect(opened.model.state?.tableLimit).toBe("50") + const edited = runAll(opened.model, [Message.ChangedTableLimit({ value: "10" })]) + const saved = pageUpdate(edited.model, Message.ClickedApply()).commands ?? [] + const save = Arr.findFirst(saved, ({ name }) => name === SaveWidget.name) + const widget = Option.getOrNull(Option.flatMap(save, ({ args }) => decodeSave(args)))?.widget + expect(widget?.dataSource).toMatchObject({ kind: "promql", transform: { limit: 10 } }) + expect(openWith(widget).model.state?.tableLimit).toBe("10") + }) + + test("an empty query blocks Run preview and Apply", () => { + const empty = pageUpdate(opened().model, Message.ChangedPromql({ value: " " })).model + expect(pageUpdate(empty, Message.ClickedRunPreview()).commands ?? []).toEqual([]) + expect(pageUpdate(empty, Message.ClickedApply()).commands ?? []).toEqual([]) + }) + + test("the Builder tab previews a query set again", () => { + const builder = pageUpdate( + opened().model, + Message.GotSourceTabsMessage({ message: Tabs.Message.ClickedTab({ index: 0 }) }), + ).model + expect(previewWidgetOf(builder)?.dataSource).not.toMatchObject({ kind: "promql" }) + expect(isDirty(builder)).toBe(true) + }) +}) diff --git a/apps/web/src/page/dashboards/widget/promql.test.ts b/apps/web/src/page/dashboards/widget/promql.test.ts new file mode 100644 index 0000000000..459142b2db --- /dev/null +++ b/apps/web/src/page/dashboards/widget/promql.test.ts @@ -0,0 +1,45 @@ +import { DashboardWidgetSchema } from "@maple/domain/http" +import { dataSourceTransform } from "@maple/widgets/dashboard" +import { Schema } from "effect" +import { describe, expect, it } from "vitest" +import type { EditorState } from "./editor-state" +import { promqlDataSourceOf, promqlDraftOf } from "./promql" + +const table = Schema.decodeSync(DashboardWidgetSchema)({ + id: "jobs", + visualization: "table", + dataSource: { kind: "promql", query: "up", displayType: "table", transform: { limit: 50 } }, + display: { title: "Jobs" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, +}) +const draft = { query: "up", legendFormat: "", minStepSeconds: null } +const state: Pick = { + visualization: "table", + chartId: "", + statAggregate: "first", +} + +describe("promqlDataSourceOf", () => { + it("writes the table's Row limit, and clearing it removes the stored one", () => { + const limitOf = (tableLimit: string) => + dataSourceTransform(promqlDataSourceOf(table, draft, { ...state, tableLimit }))?.limit + expect(limitOf("10")).toBe(10) + expect(limitOf("")).toBeUndefined() + }) + + it("drops a stored row limit when the panel is not a table", () => { + const line = promqlDataSourceOf(table, draft, { ...state, visualization: "chart", tableLimit: "" }) + expect(dataSourceTransform(line)?.limit).toBeUndefined() + }) + + it("keeps an empty stored query empty, so Apply refuses it instead of saving the template", () => { + const empty = Schema.decodeSync(DashboardWidgetSchema)({ + id: "empty", + visualization: "chart", + dataSource: { kind: "promql", query: "", legendFormat: "{{job}}" }, + display: { title: "Empty" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, + }) + expect(promqlDraftOf(empty)).toEqual({ query: "", legendFormat: "{{job}}", minStepSeconds: null }) + }) +}) diff --git a/apps/web/src/page/dashboards/widget/promql.ts b/apps/web/src/page/dashboards/widget/promql.ts new file mode 100644 index 0000000000..3de152b4eb --- /dev/null +++ b/apps/web/src/page/dashboards/widget/promql.ts @@ -0,0 +1,79 @@ +import { rawSqlDisplayTypeFor, widgetTypeByVisualization } from "@maple/domain/http" +import { dataSourcePromql, dataSourceTransform, makePromqlDataSource } from "@maple/widgets/dashboard" +import { Record as Rec, Schema, String as Str } from "effect" +import type { EditorState } from "./editor-state" +import { parseRowLimit, type Widget } from "./lowering" + +// The PromQL draft, the staged copy the preview runs, and the `promql` data source Apply writes. + +export const PromqlDraft = Schema.Struct({ + query: Schema.String, + legendFormat: Schema.String, + minStepSeconds: Schema.NullOr(Schema.Number), +}) +export type PromqlDraft = typeof PromqlDraft.Type + +export const PromqlState = Schema.Struct({ + draft: PromqlDraft, + /** Run preview stages the draft: typing does not refire the query. */ + staged: PromqlDraft, + initial: PromqlDraft, +}) +export type PromqlState = typeof PromqlState.Type + +/** A query to start from: the request rate per service over the window's step. */ +export const PROMQL_TEMPLATE = + "sum by (job) (rate(http_server_request_duration_seconds_count[$__rate_interval]))" + +/** The widget's PromQL (an empty stored query stays empty, so Apply refuses it), or the template for a non-PromQL widget. */ +export const promqlDraftOf = (widget: Widget): PromqlDraft => { + const promql = dataSourcePromql(widget.dataSource) + return promql !== null + ? { + query: promql.query, + legendFormat: promql.legendFormat ?? "", + minStepSeconds: promql.minStepSeconds ?? null, + } + : { query: PROMQL_TEMPLATE, legendFormat: "", minStepSeconds: null } +} + +export const initPromql = (widget: Widget): PromqlState => { + const draft = promqlDraftOf(widget) + return { draft, staged: draft, initial: draft } +} + +/** What blocks Run preview and Apply: an empty query. The parser's verdict comes from the preview. */ +export const isRunnablePromql = (promql: PromqlState): boolean => Str.trim(promql.draft.query) !== "" + +/** A stat or gauge reduces `value`, newest point first, with the picked aggregate. */ +export const promqlDataSourceOf = ( + widget: Widget, + draft: PromqlDraft, + state: Pick, +): Widget["dataSource"] => { + const stored = + dataSourcePromql(widget.dataSource) === null ? undefined : dataSourceTransform(widget.dataSource) + const { reduceToValue: _previous, ...kept } = stored ?? {} + const isScalar = widgetTypeByVisualization(state.visualization)?.isScalar === true + // A table writes the Row limit picked in the editor; any other panel drops it, since a chart would + // silently show only that many rows and has no control to clear it. + const isTable = rawSqlDisplayTypeFor(state.visualization, state.chartId) === "table" + const { limit: _limit, ...unlimited } = kept + const rowLimit = isTable ? parseRowLimit(state.tableLimit) : undefined + const limited = rowLimit === undefined ? unlimited : { ...unlimited, limit: rowLimit } + const transform = isScalar + ? { ...limited, reduceToValue: { field: "value", aggregate: state.statAggregate } } + : limited + const legendFormat = Str.trim(draft.legendFormat) + return makePromqlDataSource({ + query: draft.query, + displayType: rawSqlDisplayTypeFor(state.visualization, state.chartId), + ...(legendFormat === "" ? undefined : { legendFormat: draft.legendFormat }), + ...(draft.minStepSeconds === null ? undefined : { minStepSeconds: draft.minStepSeconds }), + ...(Rec.keys(transform).length === 0 ? undefined : { transform }), + }) +} + +/** The parser's message, when the preview failed on the query itself. */ +export const promqlParseErrorOf = (message: string | null): string | null => + message !== null && Str.startsWith("Invalid PromQL: ")(message) ? message : null diff --git a/apps/web/src/page/dashboards/widget/route-equivalents.ts b/apps/web/src/page/dashboards/widget/route-equivalents.ts index 94ea3746e9..72d2607e5d 100644 --- a/apps/web/src/page/dashboards/widget/route-equivalents.ts +++ b/apps/web/src/page/dashboards/widget/route-equivalents.ts @@ -148,6 +148,8 @@ const ROUTE_STAND_INS = { custom_query_builder_list: fixed, // A `kind: "route"` SQL widget is not a preset; it reads as a builder query, as before presets mapped. raw_sql_chart: legacyChart, + // PromQL is a `kind: "promql"` source, never a stored route. + promql_chart: fixed, product_events_funnel: fixed, product_events_paths: fixed, markdown_static: fixed, diff --git a/apps/web/src/page/dashboards/widget/update.ts b/apps/web/src/page/dashboards/widget/update.ts index 154b711fe8..8872cb2e9a 100644 --- a/apps/web/src/page/dashboards/widget/update.ts +++ b/apps/web/src/page/dashboards/widget/update.ts @@ -35,9 +35,10 @@ import { type Widget, } from "./lowering" import { initRawSql, isRunnableSql, type RawSqlDraft, rawSqlDataSourceOf } from "./raw-sql" +import { initPromql, isRunnablePromql, type PromqlDraft, promqlDataSourceOf } from "./promql" import { askMetricOptions } from "./metric-options" import { eventNamesKeyOf, requestSuggestions } from "./product-step" -import { dataSourceRawSql } from "@maple/widgets/dashboard" +import { dataSourcePromql, dataSourceRawSql } from "@maple/widgets/dashboard" import { Message } from "./message" import type { Model } from "./model" import { codeUnitAt } from "@maple/strings" @@ -50,7 +51,7 @@ export type Return = PageReturn type Search = typeof DashboardWidgetSearch.Type type Route = Readonly<{ dashboardId: string; widgetId: string; search: Search }> -export const SOURCE_MODES = ["builder", "rawSql"] +export const SOURCE_MODES = ["builder", "rawSql", "promql"] export const init = (route: Route, _context: PageContext): Return => ({ model: { @@ -65,6 +66,7 @@ export const init = (route: Route, _context: PageContext): Return => ({ sourceMode: "builder", initialSourceMode: "builder", rawSql: null, + promql: null, timeRange: null, nowMs: null, previewWidth: null, @@ -156,16 +158,16 @@ export const previewWidgetOf = (model: Model): Widget | null => { // A fixed query always previews its stored route. keepsStoredSource: state.queryFixed || state.keepsStoredSource, } - const isSql = isSqlSource(model) && model.rawSql !== null + const source = editedSourceOf(model, "staged") return { ...widget, timeRange: state.timeRange ?? undefined, visualization: state.visualization, dataSource: - isSql && model.rawSql !== null - ? rawSqlDataSourceOf(widget, model.rawSql.staged, state) - : builderDataSourceOf(widget, preview), - display: isSql ? buildSqlDisplay(widget, state) : buildDisplay(widget, preview), + source === null + ? builderDataSourceOf(widget, preview) + : sourceDataSourceOf(widget, source, state), + display: source === null ? buildDisplay(widget, preview) : buildSqlDisplay(widget, state), } } @@ -278,6 +280,7 @@ const ask = (planned: Planned, gate: Model["gate"]): Planned => { /** Apply's gate: a valid query set, or SQL the warehouse check accepts. */ export const canApply = (model: Model): boolean => { if (model.state === null) return false + if (isPromqlSource(model) && model.promql !== null) return isRunnablePromql(model.promql) const rawSql = isSqlSource(model) ? model.rawSql : null return rawSql === null ? validationErrorOf(model.state) === null : isRunnableSql(rawSql) } @@ -321,6 +324,7 @@ export const receiveDocument = ( initial: model.initial ?? seeded, staged: model.staged ?? seeded, rawSql: model.rawSql ?? initRawSql(widget), + promql: model.promql ?? initPromql(widget), }, context, ) @@ -337,11 +341,20 @@ export const showsSourceToggle = (state: EditorState): boolean => { export const isSqlSource = (model: Model): boolean => model.sourceMode === "rawSql" && model.state !== null && showsSourceToggle(model.state) +/** The PromQL tab is picked and the panel type has a rows rendering. */ +export const isPromqlSource = (model: Model): boolean => + model.sourceMode === "promql" && model.state !== null && showsSourceToggle(model.state) + const openedSource = ( model: Model, widget: Widget, ): Pick => { - const mode = dataSourceRawSql(widget.dataSource) === null ? "builder" : "rawSql" + const mode = + dataSourcePromql(widget.dataSource) !== null + ? "promql" + : dataSourceRawSql(widget.dataSource) === null + ? "builder" + : "rawSql" return { sourceMode: mode, initialSourceMode: mode, @@ -363,7 +376,8 @@ export const editState = ( export const isDirty = (model: Model): boolean => model.sourceMode !== model.initialSourceMode || encodeJson(model.state) !== encodeJson(model.initial) || - (model.sourceMode === "rawSql" && jsonKeyOf(model.rawSql?.draft) !== jsonKeyOf(model.rawSql?.initial)) + (model.sourceMode === "rawSql" && jsonKeyOf(model.rawSql?.draft) !== jsonKeyOf(model.rawSql?.initial)) || + (model.sourceMode === "promql" && jsonKeyOf(model.promql?.draft) !== jsonKeyOf(model.promql?.initial)) export const navigate = (model: Model, url: string): Return => ({ model, @@ -389,14 +403,31 @@ export const askToLeave = (model: Model, url: string): Return => { } } -/** The widget Apply writes; with `rawSql`, the Raw SQL source built for the type picked in the editor. */ -export const editedWidget = (widget: Widget, state: EditorState, rawSql: RawSqlDraft | null): Widget => { +/** A Raw SQL or PromQL draft the editor writes instead of the builder's query set. */ +export type EditedSource = + | Readonly<{ kind: "rawSql"; draft: RawSqlDraft }> + | Readonly<{ kind: "promql"; draft: PromqlDraft }> + +const sourceDataSourceOf = (widget: Widget, source: EditedSource, state: EditorState): Widget["dataSource"] => + source.kind === "rawSql" + ? rawSqlDataSourceOf(widget, source.draft, state) + : promqlDataSourceOf(widget, source.draft, state) + +/** The picked tab's draft (or its staged copy), or null on the query builder. */ +export const editedSourceOf = (model: Model, copy: "draft" | "staged"): EditedSource | null => { + if (isPromqlSource(model) && model.promql !== null) return { kind: "promql", draft: model.promql[copy] } + if (isSqlSource(model) && model.rawSql !== null) return { kind: "rawSql", draft: model.rawSql[copy] } + return null +} + +/** The widget Apply writes; with a `source`, the Raw SQL or PromQL source built for the picked type. */ +export const editedWidget = (widget: Widget, state: EditorState, source: EditedSource | null): Widget => { const edited: Widget = { ...widget, visualization: state.visualization, dataSource: - rawSql === null ? builderDataSourceOf(widget, state) : rawSqlDataSourceOf(widget, rawSql, state), - display: rawSql === null ? buildDisplay(widget, state) : buildSqlDisplay(widget, state), + source === null ? builderDataSourceOf(widget, state) : sourceDataSourceOf(widget, source, state), + display: source === null ? buildDisplay(widget, state) : buildSqlDisplay(widget, state), } if (state.timeRange !== null) return { ...edited, timeRange: state.timeRange } // No override: the key goes, so the widget follows the dashboard again. diff --git a/apps/web/src/page/dashboards/widget/view-promql.ts b/apps/web/src/page/dashboards/widget/view-promql.ts new file mode 100644 index 0000000000..3cee699263 --- /dev/null +++ b/apps/web/src/page/dashboards/widget/view-promql.ts @@ -0,0 +1,122 @@ +import type { Html, HtmlBuilder } from "foldkit/html" +import { button } from "@maple/views/ui/button" +import { field, fieldDescription, fieldErrorText, fieldLabel, type FieldState } from "@maple/views/ui/field" +import { inlineCode } from "@maple/views/ui/inline-code" +import { input } from "@maple/views/ui/input" +import { hstack, vstack } from "@maple/views/ui/stack" +import { textarea } from "@maple/views/ui/textarea" +import { typography } from "@maple/views/ui/typography" +import { dataStateOf } from "../kit/data-state" +import { Message } from "./message" +import type { Model } from "./model" +import { isRunnablePromql, promqlParseErrorOf, type PromqlState } from "./promql" +import { PROMQL_TEXTAREA_ID } from "./promql-step" +import { previewWidgetOf, widgetOf } from "./update" + +type H = HtmlBuilder + +const IDLE: FieldState = { + isInvalid: false, + isDirty: false, + isFilled: false, + isFocused: false, + isTouched: false, +} + +const idsOf = (base: string) => ({ control: base, label: `${base}-label`, error: `${base}-error` }) +const QUERY_IDS = { ...idsOf(PROMQL_TEXTAREA_ID), description: `${PROMQL_TEXTAREA_ID}-description` } +const LEGEND_IDS = idsOf("widget-editor-promql-legend") +const STEP_IDS = idsOf("widget-editor-promql-step") + +/** The preview's failure, when the server refused the query itself. */ +const parseErrorOf = (model: Model): string | null => { + const widget = previewWidgetOf(model) + if (widget === null) return null + const state = dataStateOf(model.requests, widget, model.gate) + return state._tag === "Error" ? promqlParseErrorOf(state.message) : null +} + +const queryField = (h: H, promql: PromqlState, error: string | null): Html => + field(h, { state: { ...IDLE, isInvalid: error !== null } }, [ + fieldLabel(h, { ids: QUERY_IDS, state: IDLE }, "PromQL query"), + textarea(h, { + id: QUERY_IDS.control, + controlClassName: "min-h-32 font-mono text-xs leading-5", + defaultValue: promql.draft.query, + attributes: [ + h.Spellcheck(false), + h.Placeholder("sum by (job) (rate(http_requests_total[$__rate_interval]))"), + h.OnInput((value) => Message.ChangedPromql({ value })), + ], + }), + error === null + ? fieldDescription(h, { ids: QUERY_IDS, state: IDLE }, [ + "Dashboard variables work as ", + inlineCode(h, {}, ["$name"]), + ", plus ", + inlineCode(h, {}, ["$__interval"]), + ", ", + inlineCode(h, {}, ["$__rate_interval"]), + " and ", + inlineCode(h, {}, ["$__range"]), + ".", + ]) + : fieldErrorText(h, {}, error), + ]) + +const legendField = (h: H, promql: PromqlState): Html => + field(h, { className: "grow", state: IDLE }, [ + fieldLabel(h, { ids: LEGEND_IDS, state: IDLE }, "Legend"), + input(h, { + id: LEGEND_IDS.control, + size: "sm", + className: "font-mono text-xs", + attributes: [ + h.Placeholder("{{job}}"), + h.Value(promql.draft.legendFormat), + h.OnInput((value) => Message.ChangedPromqlLegend({ value })), + ], + }), + ]) + +const stepField = (h: H, promql: PromqlState): Html => { + const step = promql.draft.minStepSeconds + return field(h, { className: "w-28 shrink-0", state: IDLE }, [ + fieldLabel(h, { ids: STEP_IDS, state: IDLE }, "Min step (s)"), + input(h, { + id: STEP_IDS.control, + type: "number", + size: "sm", + className: "text-xs", + attributes: [ + h.Min("1"), + h.Placeholder("15"), + h.Value(step === null ? "" : String(step)), + h.OnInput((value) => Message.ChangedPromqlMinStep({ value })), + ], + }), + ]) +} + +/** The PromQL tab's body: the query, its legend and step, and Run preview. */ +export const promqlEditor = (h: H, model: Model, promql: PromqlState): ReadonlyArray => [ + vstack(h, { gap: "4" }, [ + queryField(h, promql, parseErrorOf(model)), + hstack(h, { gap: "3", align: "start" }, [legendField(h, promql), stepField(h, promql)]), + hstack(h, { gap: "3" }, [ + button( + h, + { + size: "sm", + isDisabled: !isRunnablePromql(promql), + attributes: [h.OnClick(Message.ClickedRunPreview())], + }, + ["Run preview"], + ), + typography(h, { size: "2xs", tone: "muted", className: "ml-auto" }, [ + "Targets ", + inlineCode(h, {}, [model.state?.visualization ?? widgetOf(model)?.visualization ?? ""]), + ]), + ]), + ]), +] diff --git a/apps/web/src/page/dashboards/widget/view-query.ts b/apps/web/src/page/dashboards/widget/view-query.ts index bbd192a84f..22b389ae74 100644 --- a/apps/web/src/page/dashboards/widget/view-query.ts +++ b/apps/web/src/page/dashboards/widget/view-query.ts @@ -15,8 +15,9 @@ import type { EditorState } from "./editor-state" import { isNote, isProductEventsFunnel, queryCapabilitiesOf, validationErrorOf } from "./lowering" import { listPanel } from "./view-list" import { funnelPanel, pathsPanel } from "./view-panels" -import { autoIntervalLabel, isSqlSource, showsSourceToggle } from "./update" +import { autoIntervalLabel, isPromqlSource, isSqlSource, showsSourceToggle } from "./update" import { rawSqlEditor } from "./view-sql" +import { promqlEditor } from "./view-promql" import { Message } from "./message" import { metricKeysOf } from "../../kit/query-builder/where-values" import { baseValuesOf } from "./where-inputs" @@ -109,7 +110,7 @@ const sourceToggle = (h: H, model: Model): Html => slotId: "widget-editor-source", model: model.sourceTabs, view: TabsView.view, - viewInputs: { labels: ["Query builder", "Raw SQL"], panel: () => undefined }, + viewInputs: { labels: ["Query builder", "Raw SQL", "PromQL"], panel: () => undefined }, toParentMessage: (message) => Message.GotSourceTabsMessage({ message }), }), ]) @@ -161,22 +162,24 @@ export const queryEditor = (h: H, model: Model, timeZone: string): Html => { ...(showsSourceToggle(state) ? [sourceToggle(h, model)] : []), ...(isNoteEditor ? [markdownEditor(h, state.markdownContent)] - : isSqlSource(model) && model.rawSql !== null - ? rawSqlEditor(h, model, model.rawSql) - : [ - ...(error === null - ? [] - : [fieldErrorText(h, { className: "font-medium" }, error)]), - ...(panel === "list" - ? listPanel(h, model, state) - : panel === "paths" - ? pathsPanel(h, model, state) - : isProductEventsFunnel(state) - ? funnelPanel(h, model, state) - : state.queryFixed - ? [fixedQueryNote(h), runPreviewButton(h, false)] - : queryPanels(h, model, state, timeZone)), - ]), + : isPromqlSource(model) && model.promql !== null + ? promqlEditor(h, model, model.promql) + : isSqlSource(model) && model.rawSql !== null + ? rawSqlEditor(h, model, model.rawSql) + : [ + ...(error === null + ? [] + : [fieldErrorText(h, { className: "font-medium" }, error)]), + ...(panel === "list" + ? listPanel(h, model, state) + : panel === "paths" + ? pathsPanel(h, model, state) + : isProductEventsFunnel(state) + ? funnelPanel(h, model, state) + : state.queryFixed + ? [fixedQueryNote(h), runPreviewButton(h, false)] + : queryPanels(h, model, state, timeZone)), + ]), ], ) } diff --git a/apps/web/src/page/dashboards/widget/view-rail-types.ts b/apps/web/src/page/dashboards/widget/view-rail-types.ts index 4e0b9cd76a..92e41a979a 100644 --- a/apps/web/src/page/dashboards/widget/view-rail-types.ts +++ b/apps/web/src/page/dashboards/widget/view-rail-types.ts @@ -9,7 +9,7 @@ import { input } from "@maple/views/ui/input" import { toSeriesFieldOptions } from "./drafts" import { ROW_LIMIT_MAX, statValueFieldOf } from "./lowering" import { SQL_VALUE_FIELD, sqlValueFieldOf } from "./raw-sql" -import { isSqlSource, widgetOf } from "./update" +import { isPromqlSource, isSqlSource, widgetOf } from "./update" import type { EditorState } from "./editor-state" import { Message } from "./message" import { ProductEdit } from "./product-edit" @@ -53,7 +53,7 @@ const scalarReduction = (h: H, model: Model, state: EditorState): ReadonlyArray< // A fixed endpoint reduces its own field, which the stand-in queries cannot name. const valueField = isSqlSource(model) ? [sqlValueField(h, state)] - : state.keepsStoredSource + : state.keepsStoredSource || isPromqlSource(model) ? [] : [ pageSelect( diff --git a/packages/backend/src/services/dashboards/DashboardWidgetDataService.test.ts b/packages/backend/src/services/dashboards/DashboardWidgetDataService.test.ts index c9f075480c..a0d096f25c 100644 --- a/packages/backend/src/services/dashboards/DashboardWidgetDataService.test.ts +++ b/packages/backend/src/services/dashboards/DashboardWidgetDataService.test.ts @@ -4,6 +4,7 @@ import { MAX_LIST_RANGE_SECONDS } from "@maple/query-engine" import { Effect, Layer, ManagedRuntime, Schema, Array as Arr } from "effect" import { QueryEngineService } from "@maple/backend/services/warehouse/QueryEngineService" import { WarehouseQueryService } from "@maple/backend/services/warehouse/WarehouseQueryService" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" import { DashboardWidgetDataService, type WidgetDataRequest } from "./DashboardWidgetDataService" const asIsoDateTimeString = Schema.decodeUnknownSync(IsoDateTimeString) @@ -55,7 +56,14 @@ const makeHarness = ( const runtime = ManagedRuntime.make( Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make).pipe( - Layer.provide(Layer.mergeAll(queryEngine, warehouse)), + Layer.provide( + Layer.mergeAll( + queryEngine, + warehouse, + // The real engine: selector-free PromQL evaluates without the warehouse. + Layer.effect(PromqlQueryService, PromqlQueryService.make).pipe(Layer.provide(warehouse)), + ), + ), ), ) return { runtime, windows, rawSql, queries } @@ -522,3 +530,83 @@ describe("DashboardWidgetDataService.resolveBatch", () => { await runtime.dispose() }) }) + +const decodeRows = Schema.decodeUnknownSync( + Schema.Struct({ data: Schema.Array(Schema.Record(Schema.String, Schema.Unknown)) }), +) + +describe("DashboardWidgetDataService with a promql widget", () => { + const HOUR = { startTime: "2026-01-01 00:00:00", endTime: "2026-01-01 01:00:00" } + const promqlWidget = (id: string, source: Record, visualization = "chart") => ({ + ...widget(id, { kind: "promql", ...source }), + visualization, + }) + const resolveOne = ( + dataSource: Record, + variableValues: Record = {}, + ) => { + const { runtime, windows } = makeHarness(die) + const run = runtime.runPromise( + DashboardWidgetDataService.use((service) => + service.resolve( + ORG, + document([promqlWidget("w-promql", dataSource)]), + { widgetId: "w-promql", source: "primary" }, + HOUR, + variableValues, + ), + ).pipe(Effect.result), + ) + return { run, runtime, windows } + } + + it("fills variables and built-ins and names series by the legend format", async () => { + const { run, runtime } = resolveOne( + { + query: 'label_replace(vector($__interval_ms), "env", "$env", "", "")', + legendFormat: "{{env}}", + displayType: "line", + }, + { env: { value: "prod", isAll: false, options: ["prod"] } }, + ) + const outcome = await run + if (outcome._tag !== "Success") return expect.unreachable("the promql widget resolved") + const rows = decodeRows(outcome.success.data).data + // One hour at about 200 points is a 30s step: 121 steps from the hour's start. + expect(rows).toHaveLength(121) + expect(rows[0]).toEqual({ bucket: "2026-01-01T00:00:00.000Z", prod: 30_000 }) + await runtime.dispose() + }) + + it("shows the parser's message for a query that does not parse", async () => { + const { run, runtime } = resolveOne({ query: "sum(rate(x[5m])" }) + const outcome = await run + if (outcome._tag !== "Failure") return expect.unreachable("a bad query fails") + expect(outcome.failure._tag).toBe("@maple/http/errors/ShareWidgetExecutionError") + expect(outcome.failure.message).toMatch(/^Invalid PromQL: /) + await runtime.dispose() + }) + + it("is gated on the metrics scope only", async () => { + const { runtime } = makeHarness(die) + const batch = (canRead: (family: "traces" | "logs" | "metrics") => boolean) => + runtime.runPromise( + DashboardWidgetDataService.use((service) => + service.resolveBatch(ORG, document([promqlWidget("w", { query: "vector(1)" }, "stat")]), { + requests: [{ widgetId: "w", source: "primary" }], + window: HOUR, + variableValues: {}, + canRead, + }), + ), + ) + const metricsOnly = await batch((family) => family === "metrics") + expect(metricsOnly.results[0]).toMatchObject({ widgetId: "w", ok: true }) + const tracesOnly = await batch((family) => family === "traces") + expect(tracesOnly.results[0]).toMatchObject({ + ok: false, + message: 'This widget requires the "metrics:read" scope.', + }) + await runtime.dispose() + }) +}) diff --git a/packages/backend/src/services/dashboards/DashboardWidgetDataService.ts b/packages/backend/src/services/dashboards/DashboardWidgetDataService.ts index 15038b6743..f568ebe168 100644 --- a/packages/backend/src/services/dashboards/DashboardWidgetDataService.ts +++ b/packages/backend/src/services/dashboards/DashboardWidgetDataService.ts @@ -72,6 +72,7 @@ import { widgetReadPath, } from "./widget-read-families" import { systemTenant } from "@maple/backend/services/auth/system-tenant" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" // Shares and the API's widget data read both land here, so the wording names neither. const UNSUPPORTED_WIDGET_MESSAGE = "This widget type can't be read outside the dashboard yet." @@ -211,6 +212,16 @@ const PlannedRawSqlParams = Schema.Struct({ }) const decodePlannedRawSql = Schema.decodeUnknownEffect(PlannedRawSqlParams) +const PlannedPromqlParams = Schema.Struct({ + promql: Schema.String, + legendFormat: Schema.optionalKey(Schema.String), + minStepSeconds: Schema.optionalKey(Schema.Number), + displayType: Schema.optionalKey(Schema.String), + maxDataPoints: Schema.optionalKey(Schema.Number), +}) +const decodePlannedPromql = Schema.decodeUnknownEffect(PlannedPromqlParams) +const isShareWidgetExecutionError = Schema.is(ShareWidgetExecutionError) + /** The list cap applied to a window that exceeds it: last `MAX_LIST_RANGE_SECONDS` up to its end. */ const narrowToListCap = (window: ResolvedWindow): ResolvedWindow => ({ startTime: formatWarehouseDateTime( @@ -290,6 +301,7 @@ export class DashboardWidgetDataService extends Context.Service< make: Effect.gen(function* () { const queryEngine = yield* QueryEngineService const warehouse = yield* WarehouseQueryService + const promql = yield* PromqlQueryService const resolve = Effect.fn("DashboardWidgetDataService.resolve")(function* ( orgId: OrgId, @@ -484,6 +496,55 @@ export class DashboardWidgetDataService extends Context.Service< return outcome({ data: rows }) } + if (path._tag === "Promql") { + // The author's PromQL, variables already filled by the planner. A query that does + // not parse or cannot run says why, so the tile shows the parser's message. + const rows = yield* Effect.gen(function* () { + const params = yield* decodePlannedPromql(executed.params) + const result = yield* promql.widget(tenant, { + query: params.promql, + startTime: executed.window.startTime, + endTime: executed.window.endTime, + ...(params.legendFormat === undefined + ? undefined + : { legendFormat: params.legendFormat }), + ...(params.minStepSeconds === undefined + ? undefined + : { minStepSeconds: params.minStepSeconds }), + ...(params.maxDataPoints === undefined + ? undefined + : { maxDataPoints: params.maxDataPoints }), + ...(params.displayType === undefined + ? undefined + : { displayType: params.displayType }), + }) + return result.rows + }).pipe( + Effect.catchTags({ + "@maple/backend/promql/PromqlBadQueryError": (error) => + Effect.fail( + new ShareWidgetExecutionError({ + message: `Invalid PromQL: ${error.message}`, + widgetId: request.widgetId, + }), + ), + "@maple/backend/promql/PromqlExecutionError": (error) => + Effect.fail( + new ShareWidgetExecutionError({ + message: error.message, + widgetId: request.widgetId, + }), + ), + }), + Effect.catchIf( + (error) => !isShareWidgetExecutionError(error), + executionFailed(request.widgetId, "promql"), + ), + Effect.catchDefect(executionFailed(request.widgetId, "promql")), + ) + return outcome({ data: rows }) + } + const context: RouteEndpointContext = { tenant, queryEngine, @@ -630,7 +691,9 @@ export class DashboardWidgetDataService extends Context.Service< }), }) { static readonly layer = Layer.effect(this, this.make).pipe( - Layer.provide(Layer.mergeAll(WarehouseQueryService.layer, QueryEngineService.layer)), + Layer.provide( + Layer.mergeAll(WarehouseQueryService.layer, QueryEngineService.layer, PromqlQueryService.layer), + ), ) } diff --git a/packages/backend/src/services/dashboards/widget-data-parity.test.ts b/packages/backend/src/services/dashboards/widget-data-parity.test.ts index 3b309eca46..f5e7d11b8d 100644 --- a/packages/backend/src/services/dashboards/widget-data-parity.test.ts +++ b/packages/backend/src/services/dashboards/widget-data-parity.test.ts @@ -14,12 +14,7 @@ * screenshot. */ import { describe, expect, it } from "@effect/vitest" -import { - DashboardDocument, - DashboardVariableSchema, - IsoDateTimeString, - OrgId, -} from "@maple/domain/http" +import { DashboardDocument, DashboardVariableSchema, IsoDateTimeString, OrgId } from "@maple/domain/http" import type { RawSqlValidationError } from "@maple/domain/http" import { MAX_LIST_RANGE_SECONDS, @@ -45,6 +40,7 @@ import { } from "./DashboardWidgetDataService" import { makeServerQuerySetExecutor } from "./server-query-set-executor" import { compiledQueryOf, type CompiledQueryInput } from "@maple/query-engine/execution" +import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQueryService" const asIsoDateTimeString = Schema.decodeUnknownSync(IsoDateTimeString) const asOrgId = Schema.decodeUnknownSync(OrgId) @@ -150,7 +146,13 @@ const makeHarness = () => { } as any) const runtime = ManagedRuntime.make( Layer.effect(DashboardWidgetDataService, DashboardWidgetDataService.make).pipe( - Layer.provide(Layer.mergeAll(queryEngine, warehouse)), + Layer.provide( + Layer.mergeAll( + queryEngine, + warehouse, + Layer.effect(PromqlQueryService, PromqlQueryService.make).pipe(Layer.provide(warehouse)), + ), + ), ), ) return { runtime, captured, queryEngineLayer: queryEngine, warehouseLayer: warehouse } diff --git a/packages/backend/src/services/dashboards/widget-read-families.ts b/packages/backend/src/services/dashboards/widget-read-families.ts index 1ecc0625c3..896d8ce443 100644 --- a/packages/backend/src/services/dashboards/widget-read-families.ts +++ b/packages/backend/src/services/dashboards/widget-read-families.ts @@ -8,6 +8,7 @@ import { TELEMETRY_READ_FAMILIES } from "@maple/domain/http/v2" import { dataSourceQuerySet, MARKDOWN_STATIC_ENDPOINT, + PROMQL_ENDPOINT, QUERY_RESULT_ENDPOINTS, RAW_SQL_ENDPOINT, toWidgetRequest, @@ -35,6 +36,7 @@ export type WidgetReadPath = | { readonly _tag: "Static" } | { readonly _tag: "QuerySet"; readonly request: WidgetRequest; readonly querySet: WidgetQuerySet } | { readonly _tag: "RawSql"; readonly request: WidgetRequest } + | { readonly _tag: "Promql"; readonly request: WidgetRequest } | { readonly _tag: "Route"; readonly request: WidgetRequest; readonly plan: RouteEndpointPlan } | { readonly _tag: "Unservable"; readonly request: WidgetRequest } @@ -46,6 +48,7 @@ export const widgetReadPath = (dataSource: WidgetDataSource | undefined): Widget const request = dataSource === undefined ? null : toWidgetRequest(dataSource) if (request === null || request.endpoint === MARKDOWN_STATIC_ENDPOINT) return { _tag: "Static" } if (request.endpoint === RAW_SQL_ENDPOINT) return { _tag: "RawSql", request } + if (request.endpoint === PROMQL_ENDPOINT) return { _tag: "Promql", request } const querySet = dataSourceQuerySet(dataSource) if (querySet !== null && request.endpoint === QUERY_RESULT_ENDPOINTS[querySet.resultShape]) { return { _tag: "QuerySet", request, querySet } @@ -62,6 +65,9 @@ export const readPathFamilies = (path: WidgetReadPath): ReadonlyArray sourceReadFamilies(query.dataSource)), diff --git a/packages/backend/src/services/promql/PromqlQueryService.test.ts b/packages/backend/src/services/promql/PromqlQueryService.test.ts index 43e66c76f3..5336054e4d 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.test.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.test.ts @@ -27,6 +27,36 @@ const failureOf = (input: { query: string; startMs: number; endMs: number; stepM }).pipe(Effect.provide(TestLayer)) describe("PromqlQueryService", () => { + it.effect("refuses a widget window that ends before it starts", () => + Effect.gen(function* () { + const service = yield* PromqlQueryService + const error = yield* Effect.flip( + service.widget(tenant, { + query: "vector(1)", + startTime: "2026-01-02 00:00:00", + endTime: "2026-01-01 00:00:00", + }), + ) + expect(error._tag).toBe("@maple/backend/promql/PromqlBadQueryError") + }).pipe(Effect.provide(TestLayer)), + ) + + it.effect("runs a widget query on a step picked from the window", () => + Effect.gen(function* () { + const service = yield* PromqlQueryService + const result = yield* service.widget(tenant, { + query: "vector($__range_s)", + startTime: "2026-01-01 00:00:00", + endTime: "2026-01-02 00:00:00", + maxDataPoints: 100, + displayType: "stat", + }) + // A day at 100 points rounds up to a 15 minute step; a stat reads newest first. + expect(result.stepSeconds).toBe(900) + expect(result.resultType).toBe("matrix") + expect(result.rows[0]).toEqual({ bucket: "2026-01-02T00:00:00.000Z", value: 86_400 }) + }).pipe(Effect.provide(TestLayer)), + ) it.effect("answers a query without selectors without reading the warehouse", () => Effect.gen(function* () { const service = yield* PromqlQueryService diff --git a/packages/backend/src/services/promql/PromqlQueryService.ts b/packages/backend/src/services/promql/PromqlQueryService.ts index c24943e1db..0f3e4ef578 100644 --- a/packages/backend/src/services/promql/PromqlQueryService.ts +++ b/packages/backend/src/services/promql/PromqlQueryService.ts @@ -24,7 +24,15 @@ import { type SelectorRequest, type VectorSelector, } from "@maple/promql" -import { CH, formatWarehouseDateTime } from "@maple/query-engine" +import { + CH, + formatWarehouseDateTime, + interpolatePromqlBuiltins, + parseWarehouseDateTime, + promqlRowsForDisplay, + promqlStepSeconds, + type PromqlRow, +} from "@maple/query-engine" import { buildPushdownQuery, buildSelectorQueries, @@ -92,6 +100,24 @@ export interface PromqlQuery extends QueryParams { readonly query: string } +/** A dashboard widget's PromQL over a warehouse window; the service picks the step. */ +export interface PromqlWidgetInput { + readonly query: string + readonly startTime: string + readonly endTime: string + readonly legendFormat?: string + readonly minStepSeconds?: number + readonly maxDataPoints?: number + readonly displayType?: string +} + +export interface PromqlWidgetResult { + readonly rows: ReadonlyArray + readonly resultType: QueryResult["resultType"] + readonly seriesCount: number + readonly stepSeconds: number +} + const validate = (query: PromqlQuery): Effect.Effect => Effect.gen(function* () { const { startMs, endMs, stepMs } = query @@ -292,7 +318,7 @@ const make = Effect.gen(function* () { ), ) - const query = Effect.fn("PromqlQueryService.query")(function* ( + const query_ = Effect.fn("PromqlQueryService.query")(function* ( tenant: TenantContext, input: PromqlQuery, ) { @@ -548,7 +574,49 @@ const make = Effect.gen(function* () { ) }) - return { query, series, labelNames, labelValues, metadata } + const widget = Effect.fn("PromqlQueryService.widget")(function* ( + tenant: TenantContext, + input: PromqlWidgetInput, + ) { + const startMs = parseWarehouseDateTime(input.startTime) + const endMs = parseWarehouseDateTime(input.endTime) + // Checked before alignment, which would turn a reversed window into a valid instant. + if (!(endMs >= startMs)) { + return yield* new PromqlBadQueryError({ message: "end timestamp must not be before start time" }) + } + const stepSeconds = promqlStepSeconds({ + startMs, + endMs, + ...(input.maxDataPoints === undefined ? undefined : { maxDataPoints: input.maxDataPoints }), + ...(input.minStepSeconds === undefined ? undefined : { minStepSeconds: input.minStepSeconds }), + }) + const stepMs = stepSeconds * 1000 + // Steps land on multiples of the step, so neighbouring refreshes share their points. + const alignedStart = Math.floor(startMs / stepMs) * stepMs + const alignedEnd = Math.max(alignedStart, Math.floor(endMs / stepMs) * stepMs) + const query = interpolatePromqlBuiltins(input.query, { startMs, endMs, stepMs }) + // Range mode even for a one-step window: a chart always wants a matrix. + const result = yield* query_(tenant, { + query, + startMs: alignedStart, + endMs: alignedEnd, + stepMs, + instant: false, + }) + const rows = promqlRowsForDisplay(result, { + ...(input.displayType === undefined ? undefined : { displayType: input.displayType }), + ...(input.legendFormat === undefined ? undefined : { legendFormat: input.legendFormat }), + }) + return { + rows, + resultType: result.resultType, + seriesCount: + result.resultType === "matrix" || result.resultType === "vector" ? result.result.length : 1, + stepSeconds, + } satisfies PromqlWidgetResult + }) + + return { query: query_, series, labelNames, labelValues, metadata, widget } }) export class PromqlQueryService extends Context.Service()( diff --git a/packages/domain/src/http/query-engine.ts b/packages/domain/src/http/query-engine.ts index 6efb518575..3ba1c2e4eb 100644 --- a/packages/domain/src/http/query-engine.ts +++ b/packages/domain/src/http/query-engine.ts @@ -7,6 +7,7 @@ import { ADVISORY_SEVERITIES } from "../runtime-advisories" import { ATTACK_STAGES } from "../security-telemetry" import { SERVICE_RUNTIME_KIND_IDS } from "../service-runtimes" import { MAX_RAW_SQL_LENGTH } from "../raw-sql" +import { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "../promql" import { RawSqlDisplayType } from "@maple/widgets" import { CommitSha, @@ -4084,6 +4085,30 @@ export class RawSqlExecuteResponse extends Schema.Class(" }), }) {} +/** + * A PromQL widget query over a window. The server picks the step from the window, + * `maxDataPoints` and `minStepSeconds`, fills the time built-ins, and shapes the rows + * for `displayType` with `legendFormat` naming the series. + */ +export class PromqlExecuteRequest extends Schema.Class("PromqlExecuteRequest")({ + query: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_PROMQL_QUERY_LENGTH)), + startTime: TinybirdDateTime, + endTime: TinybirdDateTime, + legendFormat: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAX_PROMQL_LEGEND_LENGTH))), + minStepSeconds: Schema.optionalKey(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + maxDataPoints: Schema.optionalKey(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + displayType: Schema.optionalKey(RawSqlDisplayType), +}) {} + +export class PromqlExecuteResponse extends Schema.Class("PromqlExecuteResponse")({ + data: Schema.Array(WireRow), + meta: Schema.Struct({ + resultType: Schema.Literals(["matrix", "vector", "scalar", "string"]), + seriesCount: Schema.Number, + stepSeconds: Schema.Number, + }), +}) {} + export class RawSqlValidationError extends Schema.TaggedError()( "@maple/http/errors/RawSqlValidationError", { @@ -5125,6 +5150,13 @@ export class QueryEngineApiGroup extends HttpApiGroup.make("queryEngine") error: queryEngineEndpointErrors, }), ) + .add( + HttpApiEndpoint.post("executePromql", "/execute-promql", { + payload: PromqlExecuteRequest, + success: PromqlExecuteResponse, + error: validatedQueryEndpointErrors, + }), + ) .add( HttpApiEndpoint.post("executeRawSql", "/execute-raw-sql", { payload: RawSqlExecuteRequest, diff --git a/packages/domain/src/http/v2/dashboard-data.ts b/packages/domain/src/http/v2/dashboard-data.ts index 9846d6697e..271df2a6be 100644 --- a/packages/domain/src/http/v2/dashboard-data.ts +++ b/packages/domain/src/http/v2/dashboard-data.ts @@ -24,6 +24,7 @@ import { QueryComparisonSchema, } from "@maple/query-model" import { RawSqlText } from "../../raw-sql" +import { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "../../promql" import { Timestamp } from "./timestamp" import { replaceWith } from "@maple/strings" @@ -207,6 +208,22 @@ const V2RawSqlDataSource = Schema.Struct({ transform: optional(V2WidgetTransform), }).pipe(Schema.encodeKeys({ displayType: "display_type", granularitySeconds: "granularity_seconds" })) +/** A PromQL query over the metric tables; `legend_format` names series with `{{label}}`. */ +const V2PromqlDataSource = Schema.Struct({ + kind: Schema.Literal("promql"), + query: Schema.String.check(Schema.isMaxLength(MAX_PROMQL_QUERY_LENGTH)), + legendFormat: optional(Schema.String.check(Schema.isMaxLength(MAX_PROMQL_LEGEND_LENGTH))), + minStepSeconds: optional(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + displayType: optional(Schema.String), + transform: optional(V2WidgetTransform), +}).pipe( + Schema.encodeKeys({ + legendFormat: "legend_format", + minStepSeconds: "min_step_seconds", + displayType: "display_type", + }), +) + // Raw SQL has one door: the `raw_sql` arm. The route arm could carry it too — // `dataSourceRawSql` still reads `params.sql` under the pre-v3 `raw_sql_chart` // endpoint — which meant a second, unvalidated way to store a query. Refused @@ -242,6 +259,7 @@ const V2StaticDataSource = Schema.Struct({ const widgetDataSourceSchema = Schema.Union([ V2QueryDataSource, V2RawSqlDataSource, + V2PromqlDataSource, V2RouteDataSource, V2StaticDataSource, ]).annotate({ identifier: "DashboardWidgetDataSource", title: "Dashboard widget data source" }) diff --git a/packages/domain/src/http/v2/dashboard-widget-parity.test.ts b/packages/domain/src/http/v2/dashboard-widget-parity.test.ts index 56ff96ed9c..069d881704 100644 --- a/packages/domain/src/http/v2/dashboard-widget-parity.test.ts +++ b/packages/domain/src/http/v2/dashboard-widget-parity.test.ts @@ -246,6 +246,7 @@ describe("the v2 data source covers every stored kind", () => { // The arm validates its SQL now, so the fixture has to be a query the // engine would accept — this asserts arm coverage, not SQL leniency. raw_sql: { kind: "raw_sql", sql: "SELECT count() FROM logs WHERE $__orgFilter" }, + promql: { kind: "promql", query: "sum(rate(http_requests_total[5m]))", legend_format: "{{job}}" }, route: { kind: "route", endpoint: "list_traces" }, static: { kind: "static" }, }[kind] diff --git a/packages/domain/src/promql.ts b/packages/domain/src/promql.ts new file mode 100644 index 0000000000..599f6e9034 --- /dev/null +++ b/packages/domain/src/promql.ts @@ -0,0 +1 @@ +export { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "@maple/primitives" diff --git a/packages/primitives/src/index.ts b/packages/primitives/src/index.ts index 7e42776a8e..873bafc4d0 100644 --- a/packages/primitives/src/index.ts +++ b/packages/primitives/src/index.ts @@ -705,3 +705,9 @@ export const ChatConversationKey = Schema.String.check( Schema.annotate({ identifier: "@maple/ChatConversationKey", title: "Chat Conversation Key" }), ) export type ChatConversationKey = Schema.Schema.Type + +/** The longest PromQL query a widget, the share path or the PromQL routes take. */ +export const MAX_PROMQL_QUERY_LENGTH = 10_000 + +/** The longest `legendFormat` a PromQL widget takes. */ +export const MAX_PROMQL_LEGEND_LENGTH = 500 diff --git a/packages/query-engine/src/dashboard-variables/interpolate.ts b/packages/query-engine/src/dashboard-variables/interpolate.ts index 50675b0fa2..677d59d82d 100644 --- a/packages/query-engine/src/dashboard-variables/interpolate.ts +++ b/packages/query-engine/src/dashboard-variables/interpolate.ts @@ -21,6 +21,7 @@ import { escapeClickHouseString } from "@maple-dev/effect-orm/sql" import { parseWhereClause, splitWhereClause } from "@maple/domain/where-clause" import { Schema, Array as Arr, Record as Rec, String as Str, Predicate } from "effect" import { replaceWith } from "@maple/strings" +import { collectPromqlVariableRefs, interpolatePromqlVariables } from "../promql-widget/variables" const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)) @@ -209,6 +210,7 @@ export const collectWhereClauses = (value: unknown, key?: string): string[] => { } function interpolateString(input: string, key: string | undefined, values: VariableValues): string { + if (key === "promql") return interpolatePromqlVariables(input, values) if (!Str.includes("$")(input)) return input if (key === "sql") { return replaceRefs(input, (name) => { @@ -280,6 +282,7 @@ export function hasUnresolvedVariableRefs( values: VariableValues, ): boolean { if (!params || definedNames.length === 0) return false - const refs = collectVariableRefs(encodeJson(params)) + const encoded = encodeJson(params) + const refs = [...collectVariableRefs(encoded), ...collectPromqlVariableRefs(encoded)] return Arr.some(refs, (name) => definedNames.includes(name) && values[name] === undefined) } diff --git a/packages/query-engine/src/index.ts b/packages/query-engine/src/index.ts index 66d7cc0114..e02d99355c 100644 --- a/packages/query-engine/src/index.ts +++ b/packages/query-engine/src/index.ts @@ -7,6 +7,7 @@ export * from "./dashboard-variables/time-macros" export * from "./dashboard-variables/options" export * from "./widget-request" export * from "./raw-sql-chart-rows" +export * from "./promql-widget" export * from "./route-rows" export * from "./traces-shared" export * from "./span-events" diff --git a/packages/query-engine/src/promql-widget/index.ts b/packages/query-engine/src/promql-widget/index.ts new file mode 100644 index 0000000000..b0ab88d34c --- /dev/null +++ b/packages/query-engine/src/promql-widget/index.ts @@ -0,0 +1,2 @@ +export * from "./variables" +export * from "./rows" diff --git a/packages/query-engine/src/promql-widget/rows.test.ts b/packages/query-engine/src/promql-widget/rows.test.ts new file mode 100644 index 0000000000..89d0bfa224 --- /dev/null +++ b/packages/query-engine/src/promql-widget/rows.test.ts @@ -0,0 +1,140 @@ +import type { QueryResult } from "@maple/promql" +import { Array as Arr, Record as Rec } from "effect" +import { describe, expect, it } from "vitest" +import { formatPromqlLegend, promqlRowsForDisplay, promqlStepSeconds } from "./rows" + +const t0 = Date.UTC(2026, 0, 1) +const iso = (offsetS: number) => new Date(t0 + offsetS * 1000).toISOString() + +const webSeries = { + labels: { __name__: "up", job: "web", instance: "b" }, + points: [ + { t: t0, v: 1 }, + { t: t0 + 60_000, v: 0 }, + ], +} + +const matrix: QueryResult = { + resultType: "matrix", + result: [ + webSeries, + { + labels: { __name__: "up", job: "api", instance: "a" }, + points: [ + { t: t0, v: 1 }, + { t: t0 + 60_000, v: Number.NaN }, + ], + }, + ], +} + +describe("formatPromqlLegend", () => { + const labels = { __name__: "up", job: "api", instance: "a" } + + it("prints the label set when there is no format", () => { + expect(formatPromqlLegend(labels)).toBe('up{instance="a", job="api"}') + expect(formatPromqlLegend({ job: "api" }, " ")).toBe('{job="api"}') + }) + + it("fills {{label}} and leaves a missing label empty", () => { + expect(formatPromqlLegend(labels, "{{job}} on {{ instance }} {{zone}}")).toBe("api on a ") + }) +}) + +describe("promqlRowsForDisplay", () => { + it("draws a line chart as one wide row per step, a column per series", () => { + expect(promqlRowsForDisplay(matrix, { displayType: "line", legendFormat: "{{job}}" })).toEqual([ + { bucket: iso(0), api: 1, web: 1 }, + { bucket: iso(60), web: 0 }, + ]) + }) + + it("reads an absent display type as a line chart and numbers repeated names", () => { + const rows = promqlRowsForDisplay(matrix, { legendFormat: "{{__name__}}" }) + expect(rows[0]).toEqual({ bucket: iso(0), up: 1, "up (2)": 1 }) + }) + + it("never lets a legend name take the time column", () => { + const rows = promqlRowsForDisplay(matrix, { legendFormat: "bucket" }) + expect(rows[0]).toEqual({ bucket: iso(0), "bucket (2)": 1, "bucket (3)": 1 }) + }) + + it("gives a stat the first series, newest point first", () => { + const rows = promqlRowsForDisplay(matrix, { displayType: "stat" }) + expect(rows).toEqual([{ bucket: iso(0), value: 1 }]) + const web = promqlRowsForDisplay( + { resultType: "matrix", result: [webSeries] }, + { displayType: "stat" }, + ) + expect(web).toEqual([ + { bucket: iso(60), value: 0 }, + { bucket: iso(0), value: 1 }, + ]) + }) + + it("keeps a series label called name or value beside the row's own columns", () => { + const sshd = { + resultType: "vector" as const, + result: [{ labels: { __name__: "unit", name: "sshd", value: "x" }, value: 1, t: 0 }], + } + expect(promqlRowsForDisplay(sshd, { displayType: "table", legendFormat: "{{name}}" })).toEqual([ + { __name__: "unit", label_name: "sshd", label_value: "x", name: "sshd", value: 1 }, + ]) + }) + + it("moves a name label past an existing label_name instead of overwriting it", () => { + const both = { + resultType: "vector" as const, + result: [{ labels: { name: "sshd", label_name: "original" }, value: 1, t: 0 }], + } + expect(promqlRowsForDisplay(both, { displayType: "table", legendFormat: "x" })).toEqual([ + { label_name: "original", label_label_name: "sshd", name: "x", value: 1 }, + ]) + }) + + it("keeps a series whose legend is __proto__ as a column", () => { + const rows = promqlRowsForDisplay(matrix, { displayType: "line", legendFormat: "__proto__" }) + expect(rows.length).toBeGreaterThan(0) + expect(Arr.some(rows, (row) => Rec.has(row, "__proto__"))).toBe(true) + expect(Arr.every(rows, (row) => Object.getPrototypeOf(row) === Object.prototype)).toBe(true) + }) + + it("gives a table one row per series with its labels and last value", () => { + expect(promqlRowsForDisplay(matrix, { displayType: "table", legendFormat: "{{job}}" })).toEqual([ + { __name__: "up", job: "web", instance: "b", name: "web", value: 0 }, + ]) + }) + + it("reads vectors and scalars", () => { + const vector: QueryResult = { + resultType: "vector", + result: [{ labels: { job: "api" }, value: 3, t: t0 }], + } + expect(promqlRowsForDisplay(vector, { displayType: "stat" })).toEqual([{ bucket: iso(0), value: 3 }]) + expect(promqlRowsForDisplay(vector, { displayType: "pie" })).toEqual([ + { job: "api", name: '{job="api"}', value: 3 }, + ]) + const scalar: QueryResult = { resultType: "scalar", result: { t: t0, v: 2 } } + expect(promqlRowsForDisplay(scalar, { displayType: "bar" })).toEqual([{ bucket: iso(0), scalar: 2 }]) + }) +}) + +describe("promqlStepSeconds", () => { + const hour = { startMs: 0, endMs: 3_600_000 } + + it("aims at about 200 points on a round step", () => { + expect(promqlStepSeconds(hour)).toBe(30) + expect(promqlStepSeconds({ startMs: 0, endMs: 7 * 86_400_000 })).toBe(3600) + }) + + it("follows the tile width within 100 to 300 points", () => { + expect(promqlStepSeconds({ ...hour, maxDataPoints: 1000 })).toBe(15) + expect(promqlStepSeconds({ startMs: 0, endMs: 86_400_000, maxDataPoints: 20 })).toBe(900) + }) + + it("never goes under the min step, 15s by default", () => { + expect(promqlStepSeconds({ startMs: 0, endMs: 600_000 })).toBe(15) + expect(promqlStepSeconds({ startMs: 0, endMs: 600_000, minStepSeconds: 5 })).toBe(5) + expect(promqlStepSeconds({ ...hour, minStepSeconds: 300 })).toBe(300) + }) +}) diff --git a/packages/query-engine/src/promql-widget/rows.ts b/packages/query-engine/src/promql-widget/rows.ts new file mode 100644 index 0000000000..2d728bfbe6 --- /dev/null +++ b/packages/query-engine/src/promql-widget/rows.ts @@ -0,0 +1,180 @@ +// A PromQL result as the widget renderers read rows. Pure. +// +// Line, area and bar get the wide `{ bucket, [series]: value }` rows the query +// builder's timeseries produces; a stat or gauge gets `{ bucket, value }` for its +// reducer; every other panel gets one row per series: `name`, the labels, `value`. +import type { Labels, QueryResult } from "@maple/promql" +import { Array as Arr, Order, Record as Rec, String as Str } from "effect" +import { replaceWith } from "@maple/strings" + +export type PromqlRow = Record + +/** The engine's result, for hosts that do not depend on `@maple/promql` directly. */ +export type PromqlQueryResult = QueryResult + +/** Steps a widget aims for: Grafana-like resolution without a 10k-point payload. */ +export const PROMQL_TARGET_POINTS = 200 +const MIN_POINTS = 100 +const MAX_POINTS = 300 + +/** Default floor: one scrape interval, as Grafana's Prometheus source does. */ +export const PROMQL_DEFAULT_MIN_STEP_SECONDS = 15 + +const NICE_STEPS_SECONDS = [ + 1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400, +] as const + +/** + * The range-query step for a window: the smallest round step that keeps the series near + * `maxDataPoints` (clamped to 100..300, default 200), never under `minStepSeconds`. + */ +export function promqlStepSeconds(input: { + readonly startMs: number + readonly endMs: number + readonly maxDataPoints?: number + readonly minStepSeconds?: number +}): number { + const target = Math.min(MAX_POINTS, Math.max(MIN_POINTS, input.maxDataPoints ?? PROMQL_TARGET_POINTS)) + const rangeSeconds = Math.max(0, input.endMs - input.startMs) / 1000 + const raw = rangeSeconds / target + const nice = Arr.findFirst(NICE_STEPS_SECONDS, (step) => step >= raw) + const step = nice._tag === "Some" ? nice.value : Math.ceil(raw / 86400) * 86400 + const floor = input.minStepSeconds ?? PROMQL_DEFAULT_MIN_STEP_SECONDS + return Math.max(step, floor > 0 ? floor : 1) +} + +/** A label set as Prometheus prints it: `name{a="b", c="d"}`, `__name__` as the prefix. */ +export function formatPromqlLabels(labels: Labels): string { + const name = labels.__name__ ?? "" + const pairs = Arr.map( + Arr.sort( + Arr.filter(Rec.keys(labels), (key) => key !== "__name__"), + Order.String, + ), + (key) => `${key}="${labels[key] ?? ""}"`, + ) + if (pairs.length === 0) return name === "" ? "{}" : name + return `${name}{${Arr.join(pairs, ", ")}}` +} + +/** + * A series' display name: `legendFormat` with `{{label}}` filled from the labels (an absent + * label is empty, as in Grafana), or the printed label set when there is no format. + */ +export function formatPromqlLegend(labels: Labels, legendFormat?: string): string { + if (legendFormat === undefined || Str.trim(legendFormat) === "") return formatPromqlLabels(labels) + return replaceWith( + legendFormat, + /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g, + (_match, key: string | undefined) => (key === undefined ? "" : (labels[key] ?? "")), + ) +} + +interface NamedSeries { + readonly name: string + readonly labels: Labels + readonly points: ReadonlyArray<{ readonly t: number; readonly v: number }> +} + +/** Every result type as series, sorted by label set; repeated names get ` (2)`, ` (3)`. */ +const namedSeries = (result: QueryResult, legendFormat?: string): ReadonlyArray => { + const raw: ReadonlyArray<{ labels: Labels; points: NamedSeries["points"] }> = + result.resultType === "matrix" + ? Arr.map(result.result, (series) => ({ labels: series.labels, points: series.points })) + : result.resultType === "vector" + ? Arr.map(result.result, (sample) => ({ + labels: sample.labels, + points: [{ t: sample.t, v: sample.value }], + })) + : result.resultType === "scalar" + ? [{ labels: {}, points: [result.result] }] + : [] + const sorted = Arr.sort( + raw, + Order.mapInput(Order.String, (series: { labels: Labels }) => formatPromqlLabels(series.labels)), + ) + // `bucket` is the row's time column; every name, literal or suffixed, is unique. + const taken = new Set(["bucket"]) + return Arr.map(sorted, (series) => { + const base = + result.resultType === "scalar" ? "scalar" : formatPromqlLegend(series.labels, legendFormat) + let name = base + for (let n = 2; taken.has(name); n++) name = `${base} (${n})` + taken.add(name) + return { name, labels: series.labels, points: series.points } + }) +} + +const isoOf = (t: number): string => new Date(t).toISOString() + +const finite = (v: number): number | null => (Number.isFinite(v) ? v : null) + +const timeseriesRows = (series: ReadonlyArray): ReadonlyArray => { + const byTime = new Map() + Arr.forEach(series, ({ name, points }) => + Arr.forEach(points, ({ t, v }) => { + const value = finite(v) + const row = byTime.get(t) ?? { bucket: isoOf(t) } + // An own data property, so a series named `__proto__` is a column, not the prototype. + if (value !== null) + Object.defineProperty(row, name, { + value, + enumerable: true, + writable: true, + configurable: true, + }) + byTime.set(t, row) + }), + ) + return Arr.map(Arr.sort([...byTime.keys()], Order.Number), (t) => byTime.get(t) ?? { bucket: isoOf(t) }) +} + +const lastValue = (series: NamedSeries): number | null => { + const last = Arr.last(series.points) + return last._tag === "Some" ? finite(last.value.v) : null +} + +const STAT_DISPLAY_TYPES = new Set(["stat", "gauge"]) +const TIMESERIES_DISPLAY_TYPES = new Set(["line", "area", "bar"]) + +/** + * A PromQL result as rows for a panel. `displayType` is the raw-SQL display type the panel maps + * to (absent reads as a line chart). A stat reads the first series only, newest point first. + */ +export function promqlRowsForDisplay( + result: QueryResult, + options: { readonly displayType?: string; readonly legendFormat?: string } = {}, +): ReadonlyArray { + const displayType = options.displayType ?? "line" + if (result.resultType === "string") return [{ name: "string", value: result.result.v }] + const series = namedSeries(result, options.legendFormat) + if (TIMESERIES_DISPLAY_TYPES.has(displayType)) return timeseriesRows(series) + if (STAT_DISPLAY_TYPES.has(displayType)) { + // Newest first, so the default `first` reducer reads the last value, as Grafana's stat does. + const first = Arr.head(series) + if (first._tag === "None") return [] + return Arr.reverse( + Arr.flatMap(first.value.points, ({ t, v }) => { + const value = finite(v) + return value === null ? [] : [{ bucket: isoOf(t), value }] + }), + ) + } + return Arr.flatMap(series, (one) => { + const value = lastValue(one) + // `name` and `value` are the row's own columns; a label of either name moves to the first + // `label_` name no other label holds, so no label value is lost. + const keys = new Set(Rec.keys(one.labels)) + const moved = (key: string): string => { + let candidate = `label_${key}` + while (keys.has(candidate)) candidate = `label_${candidate}` + keys.add(candidate) + return candidate + } + const entries = Arr.map(Rec.toEntries(one.labels), ([key, label]): readonly [string, string] => [ + key === "name" || key === "value" ? moved(key) : key, + label, + ]) + return value === null ? [] : [{ ...Rec.fromEntries(entries), name: one.name, value }] + }) +} diff --git a/packages/query-engine/src/promql-widget/variables.test.ts b/packages/query-engine/src/promql-widget/variables.test.ts new file mode 100644 index 0000000000..8a1a53fa90 --- /dev/null +++ b/packages/query-engine/src/promql-widget/variables.test.ts @@ -0,0 +1,177 @@ +import { describe, expect, it } from "vitest" +import type { VariableValues } from "../dashboard-variables/interpolate" +import { planWidgetRequest } from "../widget-request" +import { collectPromqlVariableRefs, interpolatePromqlBuiltins, interpolatePromqlVariables } from "./variables" + +const one = (value: string) => ({ value, isAll: false, options: [value] }) +const all = (options: string[]) => ({ value: "$__all", isAll: true, options }) + +const values: VariableValues = { + service: one("checkout"), + env: all(["prod", "staging"]), + host: one("db-1.internal"), +} + +describe("interpolatePromqlVariables", () => { + it.each([ + ['up{job="$service"}', 'up{job="checkout"}'], + ['up{job="${service}"}', 'up{job="checkout"}'], + ['up{job="[[service]]"}', 'up{job="checkout"}'], + ])("fills %s", (query, expected) => { + expect(interpolatePromqlVariables(query, values)).toBe(expected) + }) + + it("regex-escapes a single value only under :regex", () => { + expect(interpolatePromqlVariables('up{instance=~"${host:regex}"}', values)).toBe( + 'up{instance=~"db-1\\\\.internal"}', + ) + expect(interpolatePromqlVariables('up{instance="$host"}', values)).toBe( + 'up{instance="db-1.internal"}', + ) + }) + + it("writes an All selection as a regex alternation", () => { + expect(interpolatePromqlVariables('up{env=~"$env"}', values)).toBe('up{env=~"(prod|staging)"}') + expect(interpolatePromqlVariables('up{env=~"[[env]]"}', values)).toBe('up{env=~"(prod|staging)"}') + }) + + it("escapes regex metacharacters and quotes inside each option", () => { + const tricky: VariableValues = { path: all(["/a.b", 'x"y']) } + expect(interpolatePromqlVariables('hits{path=~"$path"}', tricky)).toBe( + 'hits{path=~"(/a\\\\.b|x\\"y)"}', + ) + }) + + it("keeps a value inside its string literal", () => { + const hostile: VariableValues = { service: one('a"} or vector(1) #') } + expect(interpolatePromqlVariables('up{job="$service"}', hostile)).toBe( + 'up{job="a\\"} or vector(1) #"}', + ) + }) + + it("matches everything for an All with no options, and leaves unknown names literal", () => { + expect(interpolatePromqlVariables('up{env=~"$env"}', { env: all([]) })).toBe('up{env=~".*"}') + expect(interpolatePromqlVariables('up{job="$missing"}', values)).toBe('up{job="$missing"}') + }) + + it("leaves built-ins for the executor", () => { + expect(interpolatePromqlVariables("rate(x[$__rate_interval])", values)).toBe( + "rate(x[$__rate_interval])", + ) + }) + + it("collects every reference syntax", () => { + expect(collectPromqlVariableRefs('a{x="$one", y="${two:regex}", z="[[three]]"} $__interval')).toEqual( + ["one", "two", "three"], + ) + }) +}) + +describe("interpolatePromqlBuiltins", () => { + const hour = { startMs: 0, endMs: 3_600_000 } + + it("leaves a built-in inside a string literal, where a dashboard value put it", () => { + expect( + interpolatePromqlBuiltins('rate(x{a="$__interval"}[$__interval])', { + startMs: 0, + endMs: 3_600_000, + stepMs: 30_000, + }), + ).toBe('rate(x{a="$__interval"}[30s])') + }) + + it("fills interval, range and their forms", () => { + const query = "x[$__interval] y[${__range}] $__range_s $__range_ms $__interval_ms" + expect(interpolatePromqlBuiltins(query, { ...hour, stepMs: 30_000 })).toBe( + "x[30s] y[3600s] 3600 3600000 30000", + ) + }) + + it("follows Grafana's rate interval rule", () => { + // max(4 * 15s, step + 15s): a short step floors at 60s, a long one adds a scrape. + expect(interpolatePromqlBuiltins("[$__rate_interval]", { ...hour, stepMs: 15_000 })).toBe("[60s]") + expect(interpolatePromqlBuiltins("[$__rate_interval]", { ...hour, stepMs: 120_000 })).toBe("[135s]") + }) + + it("leaves an unknown built-in alone", () => { + expect(interpolatePromqlBuiltins("$__intervalx $__foo", { ...hour, stepMs: 15_000 })).toBe( + "$__intervalx $__foo", + ) + }) +}) + +describe("a promql widget request through the planner", () => { + it("formats variables as PromQL and carries the tile width", () => { + const plan = planWidgetRequest({ + request: { + endpoint: "promql_chart", + params: { promql: 'up{env=~"$env"}', legendFormat: "{{job}}" }, + }, + dashboardWindow: { startTime: "2026-01-01 00:00:00", endTime: "2026-01-01 01:00:00" }, + variableValues: values, + maxDataPoints: 240, + }) + expect(plan.kind === "request" && plan.params).toMatchObject({ + promql: 'up{env=~"(prod|staging)"}', + legendFormat: "{{job}}", + maxDataPoints: 240, + }) + }) +}) + +describe("variables cannot change a query's structure", () => { + const hostile = (value: string): VariableValues => ({ v: one(value) }) + + it("escapes for the quote a value sits in", () => { + expect(interpolatePromqlVariables("up{a='$v'}", hostile("x'} or vector(1) or up{a='"))).toBe( + "up{a='x\\'} or vector(1) or up{a=\\''}", + ) + expect(interpolatePromqlVariables('up{a="$v"}', hostile('x"} or vector(1)'))).toBe( + 'up{a="x\\"} or vector(1)"}', + ) + }) + + it("refuses a backtick inside a raw string and an operator outside any string", () => { + expect(interpolatePromqlVariables("up{a=`$v`}", hostile("x`} or vector(1) or up{a=`"))).toBe( + "up{a=`$v`}", + ) + expect( + interpolatePromqlVariables("sum by ($v) (up)", hostile("job) (up) or vector(1) or sum by (job")), + ).toBe("sum by ($v) (up)") + expect(interpolatePromqlVariables("rate(up[$v])", hostile("5m"))).toBe("rate(up[5m])") + }) + + it("never puts an All alternation outside a string", () => { + expect(interpolatePromqlVariables("sum by ($v) (up)", { v: all(["a", "b"]) })).toBe( + "sum by ($v) (up)", + ) + expect(interpolatePromqlVariables("up{a=~'$v'}", { v: all(["a", "b'c"]) })).toBe("up{a=~'(a|b\\'c)'}") + }) + + it("reads a quote inside a # comment as comment text, not a string", () => { + const query = '# John\'s panel\nup{job="$v"}' + expect(interpolatePromqlVariables(query, { v: one('a"} or vector(1) #') })).toBe( + '# John\'s panel\nup{job="a\\"} or vector(1) #"}', + ) + }) + + it("escapes a newline in a quoted value, single or All", () => { + expect(interpolatePromqlVariables('up{a="$v"}', { v: one("x\ny") })).toBe('up{a="x\\ny"}') + expect(interpolatePromqlVariables("up{a=~'$v'}", { v: all(["x\ny", "z"]) })).toBe( + "up{a=~'(x\\ny|z)'}", + ) + }) + + it("leaves a name like an Object member literal", () => { + expect(interpolatePromqlVariables('up{job="$constructor"}', {})).toBe('up{job="$constructor"}') + }) + + it("places only whole tokens outside strings", () => { + expect(interpolatePromqlVariables("up * $v", { v: one("1-2") })).toBe("up * $v") + expect(interpolatePromqlVariables("up * $v", { v: one("1.5e3") })).toBe("up * 1.5e3") + expect(interpolatePromqlVariables("rate(x[$v])", { v: one("1m30s") })).toBe("rate(x[1m30s])") + expect(interpolatePromqlVariables("sum by ($v) (up)", { v: one("host_name") })).toBe( + "sum by (host_name) (up)", + ) + }) +}) diff --git a/packages/query-engine/src/promql-widget/variables.ts b/packages/query-engine/src/promql-widget/variables.ts new file mode 100644 index 0000000000..74b6ba0c4b --- /dev/null +++ b/packages/query-engine/src/promql-widget/variables.ts @@ -0,0 +1,201 @@ +// Grafana-style template variables in a PromQL widget query. Pure. +// +// Dashboard variables (`$var`, `${var}`, `${var:regex}`, `[[var]]`) are filled by the +// widget planner; the built-ins (`$__interval`, `$__rate_interval`, `$__range`, ...) need +// the step, so the executor fills them once it has picked one. +import { Array as Arr, Option, Record as Rec, String as Str } from "effect" +import { replaceWith } from "@maple/strings" +import type { VariableValues } from "../dashboard-variables/interpolate" + +// `${name:format}` and `${name}` before bare `$name`, so a branch consumes its braces. +const PROMQL_VAR_REF = + /\$\{([A-Za-z][A-Za-z0-9_]*)(?::([A-Za-z]+))?\}|\[\[([A-Za-z][A-Za-z0-9_]*)\]\]|\$([A-Za-z][A-Za-z0-9_]*)/g + +const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g + +/** A value escaped for a RE2 regex: what `=~` and `!~` matchers take. */ +export const promqlRegexEscape = (value: string): string => + replaceWith(value, REGEX_SPECIALS, (match) => `\\${match}`) + +/** Where in a query a variable sits: PromQL code, or inside a string with that quote. */ +type QuoteContext = "code" | '"' | "'" | "`" + +/** A value escaped for the inside of a double- or single-quoted PromQL string (no raw newline). */ +export const promqlStringEscape = (value: string, quote: '"' | "'" = '"'): string => + replaceWith(value, quote === '"' ? /[\\"\n]/g : /[\\'\n]/g, (match) => + match === "\n" ? "\\n" : `\\${match}`, + ) + +/** + * Outside a string a value may only be one whole token: a name, an unsigned number or a duration. + * Anything that could tokenize as two (`1-2`, `a b`) is refused. + */ +const SAFE_TOKEN = + /^(?:[A-Za-z_:][A-Za-z0-9_:]*|(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|(?:\d+(?:ms|s|m|h|d|w|y))+)$/ + +/** + * A value as it may appear in `context`, or undefined when it cannot appear there without + * changing the query's structure (a quote in a raw string, an operator in code). + */ +const placed = (value: string, context: QuoteContext): string | undefined => { + switch (context) { + case '"': + case "'": + return promqlStringEscape(value, context) + case "`": + return Str.includes("`")(value) ? undefined : value + case "code": + return SAFE_TOKEN.test(value) ? value : undefined + } +} + +/** The query split into code and string-literal runs, quotes kept with the code around them. */ +const quoteRuns = ( + query: string, +): ReadonlyArray<{ readonly text: string; readonly context: QuoteContext }> => { + const runs: Array<{ text: string; context: QuoteContext }> = [] + let context: QuoteContext = "code" + let current = "" + for (let i = 0; i < query.length; i++) { + const ch = query[i] ?? "" + if (context === "code" && ch === "#") { + // A comment runs to the end of the line; its quotes open no string. + while (i < query.length && query[i] !== "\n") { + current += query[i] ?? "" + i += 1 + } + i -= 1 + continue + } + if (context === "code") { + current += ch + if (ch === '"' || ch === "'" || ch === "`") { + runs.push({ text: current, context }) + current = "" + context = ch + } + continue + } + if (ch === "\\" && context !== "`") { + current += ch + (query[i + 1] ?? "") + i += 1 + continue + } + if (ch === context) { + runs.push({ text: current, context }) + current = ch + context = "code" + continue + } + current += ch + } + runs.push({ text: current, context }) + return runs +} + +/** Every variable name a PromQL query references, in any of the four syntaxes. */ +export const collectPromqlVariableRefs = (query: string): ReadonlyArray => + Arr.dedupe( + Arr.flatMap(Arr.fromIterable(Str.matchAll(PROMQL_VAR_REF)(query)), (match) => { + const name = match[1] ?? match[3] ?? match[4] + return name === undefined ? [] : [name] + }), + ) + +/** + * Dashboard variables substituted into a PromQL query. + * + * A single value goes in as itself; an "All" selection becomes a regex alternation of every + * option, `(a|b)`, as Grafana writes a multi-value Prometheus variable. `:regex` escapes even a + * single value. A value is escaped for the string it sits in, and one that would change the + * query's structure (a quote in a raw string, an operator outside a string) is not substituted. + * An unknown or refused variable stays literal, so it matches nothing rather than everything. + */ +export function interpolatePromqlVariables(query: string, values: VariableValues): string { + if (!Str.includes("$")(query) && !Str.includes("[[")(query)) return query + return Arr.join( + Arr.map(quoteRuns(query), ({ text, context }) => + replaceWith( + text, + PROMQL_VAR_REF, + ( + match, + braced: string | undefined, + format: string | undefined, + bracketed: string | undefined, + bare: string | undefined, + ) => { + // An own key only, so `$constructor` stays literal instead of reading Object's. + const variable = Option.getOrUndefined(Rec.get(values, braced ?? bracketed ?? bare ?? "")) + if (variable === undefined) return match + if (variable.isAll) { + if (context === "code") return match + const options = Arr.map(variable.options, (option) => + placed(promqlRegexEscape(option), context), + ) + if (options.length === 0) return ".*" + if (Arr.some(options, (o) => o === undefined)) return match + const escaped = Arr.filter(options, (o): o is string => o !== undefined) + return escaped.length === 1 ? (escaped[0] ?? "") : `(${Arr.join(escaped, "|")})` + } + const value = format === "regex" ? promqlRegexEscape(variable.value) : variable.value + return placed(value, context) ?? match + }, + ), + ), + "", + ) +} + +/** Grafana's assumed scrape interval for `$__rate_interval` when the source names none. */ +export const PROMQL_SCRAPE_INTERVAL_MS = 15_000 + +/** A duration as PromQL writes it: whole seconds as `Ns`, anything finer as `Nms`. */ +export const formatPromqlDuration = (ms: number): string => + ms % 1000 === 0 ? `${ms / 1000}s` : `${Math.round(ms)}ms` + +export interface PromqlBuiltinContext { + readonly startMs: number + readonly endMs: number + readonly stepMs: number +} + +// Longer names first in the alternation, so `$__interval_ms` never reads as `$__interval`. +const BUILTIN_REF = + /\$\{__(rate_interval|interval_ms|interval|range_ms|range_s|range)\}|\$__(rate_interval|interval_ms|interval|range_ms|range_s|range)(?![A-Za-z0-9_])/g + +/** + * The time built-ins: `$__interval` (the step), `$__rate_interval` (Grafana's + * max(4 * scrape interval, interval + scrape interval)), `$__range`, plus their `_ms` / `_s` forms. + */ +export function interpolatePromqlBuiltins(query: string, context: PromqlBuiltinContext): string { + if (!Str.includes("$")(query)) return query + const rangeMs = Math.max(0, context.endMs - context.startMs) + const values = new Map([ + ["interval", formatPromqlDuration(context.stepMs)], + ["interval_ms", String(Math.round(context.stepMs))], + [ + "rate_interval", + formatPromqlDuration( + Math.max(4 * PROMQL_SCRAPE_INTERVAL_MS, context.stepMs + PROMQL_SCRAPE_INTERVAL_MS), + ), + ], + ["range", formatPromqlDuration(Math.round(rangeMs / 1000) * 1000)], + ["range_s", String(Math.round(rangeMs / 1000))], + ["range_ms", String(Math.round(rangeMs))], + ]) + // Built-ins sit in code (a range, a step); a string holds a dashboard value, which stays literal. + return Arr.join( + Arr.map(quoteRuns(query), ({ text, context }) => + context !== "code" + ? text + : replaceWith( + text, + BUILTIN_REF, + (match, braced: string | undefined, bare: string | undefined) => + values.get(braced ?? bare ?? "") ?? match, + ), + ), + "", + ) +} diff --git a/packages/query-engine/src/widget-request.ts b/packages/query-engine/src/widget-request.ts index 1546116c68..dda65d3005 100644 --- a/packages/query-engine/src/widget-request.ts +++ b/packages/query-engine/src/widget-request.ts @@ -83,8 +83,11 @@ export type WidgetRequestPlan = PlannedWidgetRequest | DisabledWidgetRequest /** The empty-range fallback every dashboard tile pins, on both hosts. */ export const WIDGET_FETCH_STRATEGY = { enableEmptyRangeFallback: false } as const -/** Endpoint whose params carry `maxDataPoints`. Mirrors `QUERY_RESULT_ENDPOINTS.timeseries`. */ -const TIMESERIES_ENDPOINT = "custom_query_builder_timeseries" +/** Endpoints whose params carry `maxDataPoints`: `QUERY_RESULT_ENDPOINTS.timeseries` and `PROMQL_ENDPOINT`. */ +const MAX_DATA_POINTS_ENDPOINTS: ReadonlySet = new Set([ + "custom_query_builder_timeseries", + "promql_chart", +]) /** Query-set endpoints: `params.queries` is an array of query-builder drafts. */ const QUERY_SET_ENDPOINTS = new Set([ @@ -141,7 +144,7 @@ export function planWidgetRequest(input: PlanWidgetRequestInput): WidgetRequestP } const { endpoint, params } = input.request - const maxDataPoints = endpoint === TIMESERIES_ENDPOINT ? input.maxDataPoints : undefined + const maxDataPoints = MAX_DATA_POINTS_ENDPOINTS.has(endpoint) ? input.maxDataPoints : undefined // Macros first, then variables — the same order the browser has always used, // so a `$__startTime` inside a variable's value is never re-expanded. diff --git a/packages/web-data/src/warehouse/promql-chart.ts b/packages/web-data/src/warehouse/promql-chart.ts new file mode 100644 index 0000000000..9c461e0c59 --- /dev/null +++ b/packages/web-data/src/warehouse/promql-chart.ts @@ -0,0 +1,53 @@ +import { Effect, Schema } from "effect" +import { PromqlExecuteRequest, RawSqlDisplayType } from "@maple/domain/http" +import { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "@maple/primitives" +import { MapleInternalHttp } from "./warehouse-services" +import { WarehouseDateTimeString, decodeInput, runWarehouseQuery } from "./effect-utils" + +// PromQL chart server function (widget data source `promql_chart`). The API picks the +// step, fills `$__interval` and friends, and shapes the rows for `displayType` the same +// way the share API does, so a board and its share link draw the same series. + +const GetPromqlChartInputSchema = Schema.Struct({ + // The request class's own bounds, so a bad input is a typed input error before it is built. + promql: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_PROMQL_QUERY_LENGTH)), + startTime: WarehouseDateTimeString, + endTime: WarehouseDateTimeString, + legendFormat: Schema.optional(Schema.String.check(Schema.isMaxLength(MAX_PROMQL_LEGEND_LENGTH))), + minStepSeconds: Schema.optional(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + maxDataPoints: Schema.optional(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + displayType: Schema.optional(RawSqlDisplayType), +}) + +export type GetPromqlChartInput = Schema.Schema.Type + +export const getPromqlChart = Effect.fn("QueryEngine.getPromqlChart")(function* ({ + data, +}: { + data: GetPromqlChartInput +}) { + const input = yield* decodeInput(GetPromqlChartInputSchema, data, "getPromqlChart") + + const result = yield* runWarehouseQuery("promqlChart", () => + Effect.gen(function* () { + const client = yield* MapleInternalHttp + return yield* client.queryEngine.executePromql({ + payload: new PromqlExecuteRequest({ + query: input.promql, + startTime: input.startTime, + endTime: input.endTime, + ...(input.legendFormat === undefined ? undefined : { legendFormat: input.legendFormat }), + ...(input.minStepSeconds === undefined + ? undefined + : { minStepSeconds: input.minStepSeconds }), + ...(input.maxDataPoints === undefined + ? undefined + : { maxDataPoints: input.maxDataPoints }), + ...(input.displayType === undefined ? undefined : { displayType: input.displayType }), + }), + }) + }), + ) + + return { data: result.data, meta: result.meta } +}) diff --git a/packages/web-data/src/warehouse/widget-data-sources.ts b/packages/web-data/src/warehouse/widget-data-sources.ts index 1128cd66fa..45647fd130 100644 --- a/packages/web-data/src/warehouse/widget-data-sources.ts +++ b/packages/web-data/src/warehouse/widget-data-sources.ts @@ -18,6 +18,7 @@ import { getQueryBuilderTimeseries } from "./query-builder-timeseries" import { getQueryBuilderBreakdown } from "./query-builder-breakdown" import { getQueryBuilderList } from "./query-builder-list" import { getRawSqlChart } from "./raw-sql-chart" +import { getPromqlChart } from "./promql-chart" import { getProductEventsFunnelWidget, getProductEventsPathsWidget } from "./product-events" /** @@ -68,6 +69,7 @@ export const widgetServerFunctions = { custom_query_builder_breakdown: getQueryBuilderBreakdown, custom_query_builder_list: getQueryBuilderList, raw_sql_chart: getRawSqlChart, + promql_chart: getPromqlChart, product_events_funnel: getProductEventsFunnelWidget, product_events_paths: getProductEventsPathsWidget, markdown_static: markdownStaticServerFn, diff --git a/packages/widgets/src/dashboard/access.ts b/packages/widgets/src/dashboard/access.ts index eea81958aa..8cd7c893b8 100644 --- a/packages/widgets/src/dashboard/access.ts +++ b/packages/widgets/src/dashboard/access.ts @@ -22,7 +22,7 @@ const isRecord = (value: unknown): value is Record => const isString = (value: unknown): value is string => typeof value === "string" // Re-exported for the `@maple/widgets/dashboard` barrel. -export { QUERY_RESULT_ENDPOINTS, RAW_SQL_ENDPOINT } from "./legacy-endpoints" +export { PROMQL_ENDPOINT, QUERY_RESULT_ENDPOINTS, RAW_SQL_ENDPOINT } from "./legacy-endpoints" /** * The endpoint name, for consumers that still dispatch on it. @@ -142,6 +142,24 @@ export const dataSourceRawSql = (dataSource: unknown): RawSqlDataSource | null = } } +export interface PromqlDataSource { + query: string + legendFormat?: string + minStepSeconds?: number + displayType?: string +} + +/** The PromQL payload of a v3 `promql` source; v2 never stored one. */ +export const dataSourcePromql = (dataSource: unknown): PromqlDataSource | null => { + if (!isRecord(dataSource) || dataSource.kind !== "promql") return null + return { + query: typeof dataSource.query === "string" ? dataSource.query : "", + legendFormat: typeof dataSource.legendFormat === "string" ? dataSource.legendFormat : undefined, + minStepSeconds: typeof dataSource.minStepSeconds === "number" ? dataSource.minStepSeconds : undefined, + displayType: typeof dataSource.displayType === "string" ? dataSource.displayType : undefined, + } +} + /** * The opaque params bag of a curated fixed route. * diff --git a/packages/widgets/src/dashboard/construct.ts b/packages/widgets/src/dashboard/construct.ts index e6687a9307..8c30e692f6 100644 --- a/packages/widgets/src/dashboard/construct.ts +++ b/packages/widgets/src/dashboard/construct.ts @@ -10,9 +10,10 @@ import type { QueryResultContract, QuerySet, } from "@maple/query-model" -import type { RawSqlDataSource } from "./access" +import type { PromqlDataSource, RawSqlDataSource } from "./access" import type { WidgetDataSourceTransformV2 } from "./shared/transform" import type { + PromqlWidgetDataSource, QueryWidgetDataSource, RawSqlWidgetDataSource, RouteWidgetDataSource, @@ -101,6 +102,20 @@ export const makeRawSqlDataSource = (input: RawSqlDataSourceInput): typeof RawSq ...(!(input.transform === undefined) ? { transform: input.transform } : undefined), }) +export interface PromqlDataSourceInput extends PromqlDataSource { + readonly transform?: WidgetDataSourceTransform +} + +/** A widget backed by a PromQL query over the metric tables. */ +export const makePromqlDataSource = (input: PromqlDataSourceInput): typeof PromqlWidgetDataSource.Type => ({ + kind: "promql", + query: input.query, + ...(!(input.legendFormat === undefined) ? { legendFormat: input.legendFormat } : undefined), + ...(!(input.minStepSeconds === undefined) ? { minStepSeconds: input.minStepSeconds } : undefined), + ...(!(input.displayType === undefined) ? { displayType: input.displayType } : undefined), + ...(!(input.transform === undefined) ? { transform: input.transform } : undefined), +}) + /** * A widget backed by one of the curated fixed routes (`service_overview`, …). * diff --git a/packages/widgets/src/dashboard/index.ts b/packages/widgets/src/dashboard/index.ts index afe08ded3e..06b3b1f12b 100644 --- a/packages/widgets/src/dashboard/index.ts +++ b/packages/widgets/src/dashboard/index.ts @@ -30,11 +30,14 @@ export { export { dataSourceEndpoint, dataSourceQuerySet, + dataSourcePromql, dataSourceRawSql, dataSourceRouteParams, dataSourceTransform, isQueryDataSource, QUERY_RESULT_ENDPOINTS, + PROMQL_ENDPOINT, + type PromqlDataSource, RAW_SQL_ENDPOINT, type RawSqlDataSource, type WidgetQuerySet, @@ -44,6 +47,7 @@ export { makeProductEventsFunnelDataSource, makeProductEventsPathsDataSource, makeQueryDataSource, + makePromqlDataSource, makeRawSqlDataSource, makeRouteDataSource, makeStaticDataSource, @@ -52,12 +56,14 @@ export { type ProductEventsFunnelDefinition, type ProductEventsPathsDefinition, type QueryDataSourceInput, + type PromqlDataSourceInput, type RawSqlDataSourceInput, } from "./construct" // v3 — what the unsuffixed aliases below now point at. The suffixed names stay // exported for the upgrade transform and its tests, which must name a version // explicitly. export { + PromqlWidgetDataSource, QueryWidgetDataSource, RawSqlWidgetDataSource, RouteWidgetDataSource, diff --git a/packages/widgets/src/dashboard/legacy-endpoints.ts b/packages/widgets/src/dashboard/legacy-endpoints.ts index a58cd1104f..7eb60c2b5c 100644 --- a/packages/widgets/src/dashboard/legacy-endpoints.ts +++ b/packages/widgets/src/dashboard/legacy-endpoints.ts @@ -37,6 +37,9 @@ export const QUERY_ENDPOINT_RESULT_KINDS = Rec.fromEntries( export const RAW_SQL_ENDPOINT = "raw_sql_chart" +/** The transport identity of a `promql` source: its server function on both hosts. Never stored. */ +export const PROMQL_ENDPOINT = "promql_chart" + /** * The one route that never had a query: a markdown note. * diff --git a/packages/widgets/src/dashboard/promql-source.test.ts b/packages/widgets/src/dashboard/promql-source.test.ts new file mode 100644 index 0000000000..2f4cc4ff6a --- /dev/null +++ b/packages/widgets/src/dashboard/promql-source.test.ts @@ -0,0 +1,103 @@ +import { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "@maple/primitives" +import { Result, Schema, String as Str } from "effect" +import { describe, expect, it } from "vitest" +import { dataSourcePromql, dataSourceQuerySet, dataSourceRawSql, dataSourceRouteParams } from "./access" +import { makePromqlDataSource } from "./construct" +import { redactForShare, variablesForWidget } from "./redact" +import { toWidgetRequest } from "./request" +import { WidgetDataSourceV3 } from "./v3/data-source" + +const decode = Schema.decodeUnknownSync(WidgetDataSourceV3) + +const full = { + query: 'sum by (job) (rate(http_requests_total{job=~"$service"}[$__rate_interval]))', + legendFormat: "{{job}}", + minStepSeconds: 30, + displayType: "line", +} + +describe("makePromqlDataSource", () => { + it("decodes as the v3 promql arm and reads back unchanged", () => { + const source = decode(makePromqlDataSource(full)) + expect(source.kind).toBe("promql") + expect(dataSourcePromql(source)).toEqual(full) + }) + + it("refuses a query or legend longer than the PromQL routes accept", () => { + const tooLong = (overrides: Record) => + Result.isFailure( + Schema.decodeResult(WidgetDataSourceV3)({ kind: "promql", ...full, ...overrides }), + ) + expect(tooLong({ query: Str.repeat(MAX_PROMQL_QUERY_LENGTH + 1)("u") })).toBe(true) + expect(tooLong({ legendFormat: Str.repeat(MAX_PROMQL_LEGEND_LENGTH + 1)("l") })).toBe(true) + expect(tooLong({})).toBe(false) + const step = (minStepSeconds: number) => + Result.isFailure( + Schema.decodeResult(WidgetDataSourceV3)({ kind: "promql", ...full, minStepSeconds }), + ) + expect([step(0), step(-5), step(30)]).toEqual([true, true, false]) + }) + + it("writes no keys for unset options", () => { + expect(makePromqlDataSource({ query: "up" })).toEqual({ kind: "promql", query: "up" }) + }) + + it("is not a query set, raw SQL or route", () => { + const source = makePromqlDataSource({ query: "up" }) + expect(dataSourceQuerySet(source)).toBeNull() + expect(dataSourceRawSql(source)).toBeNull() + expect(dataSourceRouteParams(source)).toBeUndefined() + }) + + it("refuses a promql source with no query", () => { + expect(() => decode({ kind: "promql" })).toThrow() + }) +}) + +describe("a promql source lowered for the fetch layer", () => { + it("names the promql endpoint and puts the query under `promql`", () => { + expect(toWidgetRequest(makePromqlDataSource(full))).toEqual({ + endpoint: "promql_chart", + params: { + promql: full.query, + legendFormat: "{{job}}", + minStepSeconds: 30, + displayType: "line", + }, + }) + }) +}) + +describe("a shared promql widget", () => { + it("keeps the kind and drops the query", () => { + const shared = redactForShare({ + id: "d", + name: "Board", + timeRange: { type: "relative", value: "1h" }, + widgets: [ + { + id: "w", + visualization: "chart", + display: { title: "Rate" }, + layout: { x: 0, y: 0, w: 6, h: 4 }, + dataSource: makePromqlDataSource(full), + }, + ], + }) + expect(shared?.widgets[0]?.dataSource).toEqual({ kind: "promql" }) + }) +}) + +describe("variablesForWidget", () => { + it("keeps a variable a PromQL widget references only as [[name]]", () => { + const service = { name: "service", type: "textbox" as const, defaultValue: "checkout" } + const other = { name: "other", type: "textbox" as const } + const widget = { + id: "w1", + visualization: "chart", + layout: { x: 0, y: 0, w: 4, h: 4 }, + dataSource: makePromqlDataSource({ query: 'up{job="[[service]]"}' }), + } + expect(variablesForWidget([service, other], widget)).toEqual([service]) + }) +}) diff --git a/packages/widgets/src/dashboard/redact.ts b/packages/widgets/src/dashboard/redact.ts index dda200f005..92bebe9676 100644 --- a/packages/widgets/src/dashboard/redact.ts +++ b/packages/widgets/src/dashboard/redact.ts @@ -18,7 +18,13 @@ */ import { Option, Schema, Array as Arr, Record as Rec, String as Str } from "effect" -import { dataSourceEndpoint, dataSourceQuerySet, dataSourceRawSql, dataSourceTransform } from "./access" +import { + dataSourceEndpoint, + dataSourcePromql, + dataSourceQuerySet, + dataSourceRawSql, + dataSourceTransform, +} from "./access" import type { DashboardVariable } from "./shared/variables" const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)) @@ -34,7 +40,7 @@ const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)) * reveals a query. */ export interface RedactedDataSource { - readonly kind: "query" | "raw_sql" | "route" | "static" + readonly kind: "query" | "raw_sql" | "promql" | "route" | "static" readonly resultShape?: string readonly transform?: unknown } @@ -85,6 +91,9 @@ const redactDataSource = (dataSource: unknown): RedactedDataSource => { return { kind: "raw_sql", ...transformField } } + // Drops `query` and `legendFormat`: the query names the org's metrics and labels. + if (dataSourcePromql(dataSource) !== null) return { kind: "promql", ...transformField } + const querySet = dataSourceQuerySet(dataSource) if (querySet !== null) { // Drops `queries`, `formulas`, `comparison`, `columns`: every one of them @@ -185,7 +194,7 @@ const redactWidget = (widget: ShareWidgetInput): RedactedWidget => { /** * Variable names a widget actually references. * - * Scans the widget's stored form for `$name` / `${name}` rather than reading + * Scans the widget's stored form for every variable syntax rather than reading * any one field, because a variable can land in a where-clause, a route param, * a formula or a raw-SQL body, and a list that missed one of those would hide a * picker the chart needs. `$__`-prefixed built-ins can't match: variable names @@ -193,8 +202,10 @@ const redactWidget = (widget: ShareWidgetInput): RedactedWidget => { */ const referencedVariableNames = (widget: ShareWidgetInput): ReadonlySet => { const names = new Set() - for (const match of Str.matchAll(/\$\{?([A-Za-z][A-Za-z0-9_]*)\}?/g)(encodeJson(widget ?? null))) { - const name = match[1] + // `$name`, `${name}`, `${name:format}` and PromQL's `[[name]]`. + const refs = /\$\{?([A-Za-z][A-Za-z0-9_]*)|\[\[([A-Za-z][A-Za-z0-9_]*)\]\]/g + for (const match of Str.matchAll(refs)(encodeJson(widget ?? null))) { + const name = match[1] ?? match[2] if (name !== undefined) names.add(name) } return names diff --git a/packages/widgets/src/dashboard/request.ts b/packages/widgets/src/dashboard/request.ts index cf3e81b8a0..71496a361b 100644 --- a/packages/widgets/src/dashboard/request.ts +++ b/packages/widgets/src/dashboard/request.ts @@ -1,8 +1,10 @@ import { dataSourceEndpoint, + dataSourcePromql, dataSourceQuerySet, dataSourceRawSql, dataSourceRouteParams, + PROMQL_ENDPOINT, QUERY_RESULT_ENDPOINTS, RAW_SQL_ENDPOINT, } from "./access" @@ -54,6 +56,22 @@ export function toWidgetRequest(dataSource: unknown): WidgetRequest | null { } } + // The query sits under `promql`, the key the planner's variable pass formats as PromQL. + const promql = dataSourcePromql(dataSource) + if (promql !== null) { + return { + endpoint: PROMQL_ENDPOINT, + params: { + promql: promql.query, + ...(promql.legendFormat === undefined ? undefined : { legendFormat: promql.legendFormat }), + ...(promql.minStepSeconds === undefined + ? undefined + : { minStepSeconds: promql.minStepSeconds }), + ...(promql.displayType === undefined ? undefined : { displayType: promql.displayType }), + }, + } + } + const querySet = dataSourceQuerySet(dataSource) if (querySet !== null) { return { diff --git a/packages/widgets/src/dashboard/v3/data-source.ts b/packages/widgets/src/dashboard/v3/data-source.ts index 7531387ab0..6600485e29 100644 --- a/packages/widgets/src/dashboard/v3/data-source.ts +++ b/packages/widgets/src/dashboard/v3/data-source.ts @@ -1,3 +1,4 @@ +import { MAX_PROMQL_LEGEND_LENGTH, MAX_PROMQL_QUERY_LENGTH } from "@maple/primitives" import { QUERY_RESULT_KINDS, QuerySetSchema } from "@maple/query-model" import { Schema } from "effect" import { UnknownRecord, WidgetDataSourceTransformV2 } from "../shared/transform" @@ -83,6 +84,24 @@ export const RawSqlWidgetDataSource = Schema.Struct({ title: "Raw SQL widget data source", }) +/** + * A user-authored PromQL query over the metric tables. + * + * `displayType` is the panel family the rows are shaped for, as on `raw_sql`; + * `legendFormat` names series with `{{label}}`; `minStepSeconds` floors the step. + */ +export const PromqlWidgetDataSource = Schema.Struct({ + kind: Schema.Literal("promql"), + query: Schema.String.check(Schema.isMaxLength(MAX_PROMQL_QUERY_LENGTH)), + legendFormat: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAX_PROMQL_LEGEND_LENGTH))), + minStepSeconds: Schema.optionalKey(Schema.Number.check(Schema.isFinite(), Schema.isGreaterThan(0))), + displayType: Schema.optionalKey(Schema.String), + ...transformField, +}).annotate({ + identifier: "@maple/PromqlWidgetDataSource", + title: "PromQL widget data source", +}) + /** * One of the curated fixed routes (`service_overview`, `list_traces`, ...). * @@ -133,12 +152,13 @@ export const StaticWidgetDataSource = Schema.Struct({ * what the v2 HTTP API does with it. That is the structural successor to the * assignability assertions the union replaced. */ -export const WIDGET_DATA_SOURCE_KINDS = ["query", "raw_sql", "route", "static"] as const +export const WIDGET_DATA_SOURCE_KINDS = ["query", "raw_sql", "promql", "route", "static"] as const export type WidgetDataSourceKind = (typeof WIDGET_DATA_SOURCE_KINDS)[number] export const WidgetDataSourceV3 = Schema.Union([ QueryWidgetDataSource, RawSqlWidgetDataSource, + PromqlWidgetDataSource, RouteWidgetDataSource, StaticWidgetDataSource, ]).annotate({ diff --git a/skills/maple-dashboard-widgets/SKILL.md b/skills/maple-dashboard-widgets/SKILL.md index d59d8b3572..1a0c9161c5 100644 --- a/skills/maple-dashboard-widgets/SKILL.md +++ b/skills/maple-dashboard-widgets/SKILL.md @@ -81,7 +81,7 @@ authoring an assembled widget rather than calling `add_dashboard_widget`. A pane ## Data sources -A widget's `dataSource` is a discriminated union over `kind`: `query`, `raw_sql`, `route`, `static`. Every arm requires its `kind`. +A widget's `dataSource` is a discriminated union over `kind`: `query`, `raw_sql`, `promql`, `route`, `static`. Every arm requires its `kind`. > **If you have seen `{ "endpoint": …, "params": … }` anywhere, that is the retired v2 shape > and it will not decode.** A `query` source spreads `queries`/`formulas` at the TOP LEVEL, @@ -136,6 +136,25 @@ A widget's `dataSource` is a discriminated union over `kind`: `query`, `raw_sql` } ``` +### `kind: "promql"`: a PromQL query over the metrics + +Prometheus names: `http.server.request.duration` answers to +`http_server_request_duration_seconds_bucket`, a monotonic sum to `..._total`. Grafana +variables work (`$var`, `${var}`, `${var:regex}`, `[[var]]`, an All selection becomes +`(a|b)`), plus `$__interval`, `$__rate_interval`, `$__range` and `$__range_s`. +`legendFormat` names series with `{{label}}`; `minStepSeconds` floors the step; +`displayType` is the panel's raw-SQL display type (a stat reads the newest point of the +first series with the `first` reducer on field `value`; a table gets one row per series). + +```json +{ + "kind": "promql", + "query": "sum by (job) (rate(http_server_request_duration_seconds_count{job=~\"$service\"}[$__rate_interval]))", + "legendFormat": "{{job}}", + "displayType": "line" +} +``` + ### `kind: "static"`: a markdown note, no request ```json @@ -478,13 +497,14 @@ why `groupBy` without `addOns.groupBy: true` silently does nothing. |---|---| | `traces` | `count`, `avg_duration`, `p50_duration`, `p95_duration`, `p99_duration`, `error_rate` | | `logs` | `count` | -| `metrics` | `avg`, `sum`, `min`, `max`, `count`, `latest`, `rate`, `increase` | +| `metrics` | `avg`, `sum`, `min`, `max`, `count`, `latest`, `rate`, `increase`, `p50`, `p75`, `p90`, `p95`, `p99` | | `product_events` | `count`, `sessions`, `persons`, `users`, `visitors` | On traces only, setting `valueField: "attr."` switches the query to numeric-attribute mode, where the aggregation is one of `avg`, `sum`, `min`, `max`, `p50`, `p95`, `p99`. -This is the **only** place a bare `p50`/`p95`/`p99` is valid; latency percentiles are -spelled `p95_duration`. Metrics never accept percentiles. +Trace latency percentiles are spelled `p95_duration`; a bare `p50` to `p99` is valid only in this +numeric-attribute mode and as a `metrics` aggregation, where a histogram estimates the quantile +from its merged buckets and a gauge or sum takes it over each series' samples. ### Group-by tokens