diff --git a/apps/ai/src/mcp/__evals__/dashboard-tools.test.ts b/apps/ai/src/mcp/__evals__/dashboard-tools.test.ts index 3c7e86253d..1ee9a99943 100644 --- a/apps/ai/src/mcp/__evals__/dashboard-tools.test.ts +++ b/apps/ai/src/mcp/__evals__/dashboard-tools.test.ts @@ -16,6 +16,7 @@ import { makeEvalRuntime, runToolDirect, markdown, type EvalRuntime } from "./ev import { installFakeWarehouse, restoreWarehouse } from "./fake-warehouse" import type { McpToolResult } from "../tools/types" import { DASHBOARD_TEMPLATES } from "@maple/backend/dashboard-templates" +import { sharedExportDashboard } from "@maple/backend/services/dashboards/grafana-dashboard-import.fixtures" let rt: EvalRuntime @@ -66,6 +67,34 @@ describe("dashboard tools", () => { expect(text).not.toContain("__maple_ui") }) + it("imports a Grafana dashboard with its warnings and panel counts", async () => { + const result = await call("create_dashboard", { + name: "Imported API", + import_json: JSON.stringify({ dashboard: sharedExportDashboard, meta: {} }), + validate: "false", + }) + expect(result.isError).toBeUndefined() + const output = Schema.decodeUnknownSync(CreateDashboardOutput)(result.structuredContent) + expect(output.source).toBe("grafana_import") + expect(output.dashboard.name).toBe("Imported API") + expect(output.importStats).toEqual({ panels: 5, converted: 2, placeholders: 3 }) + expect(output.importWarnings).toContain( + 'Panel "Error logs" queries Loki, which Maple cannot run; it was imported as a placeholder.', + ) + const text = markdown(result) + expect(text).toContain("2 of 5 (3 kept as notes)") + expect(text).toContain("Import warnings") + }) + + it("refuses import_json that is neither Grafana nor Perses", async () => { + const result = await call("create_dashboard", { + name: "Nope", + import_json: JSON.stringify({ name: "Maple", widgets: [] }), + }) + expect(result.isError).toBe(true) + expect(markdown(result)).toContain("import_json is neither a Grafana dashboard") + }) + it("lists it with a next call that opens it", async () => { const result = await call("list_dashboards", { search: "eval" }) const output = Schema.decodeUnknownSync(ListDashboardsOutput)(result.structuredContent) diff --git a/apps/ai/src/mcp/tool-descriptors.generated.ts b/apps/ai/src/mcp/tool-descriptors.generated.ts index 9a04c5e9a6..773535c580 100644 --- a/apps/ai/src/mcp/tool-descriptors.generated.ts +++ b/apps/ai/src/mcp/tool-descriptors.generated.ts @@ -60,7 +60,7 @@ export const MCP_TOOL_DESCRIPTORS: ReadonlyArray = [ {"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/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":"create_dashboard","title":"Create Dashboard","description":"Create a dashboard one of four ways: a `template`, simplified `widgets` specs, full `dashboard_json`, or `import_json` (a Grafana or Perses dashboard to convert). 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."},"import_json":{"type":"string","description":"A Grafana dashboard (bare, the { dashboard, meta } API envelope, or an export for sharing) or a Perses Dashboard resource, as JSON text. Grafana rows become sections, Prometheus targets PromQL widgets, and panels Maple cannot run notes; the result lists every warning. name, description and time_range override the imported ones when given.","contentMediaType":"application/json"},"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","grafana_import","perses_import"]},"template":{"type":"string"},"importWarnings":{"type":"array","items":{"type":"string"}},"importStats":{"type":"object","properties":{"panels":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"converted":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"placeholders":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["panels","converted","placeholders"],"additionalProperties":true},"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}}, {"name":"describe_warehouse_tables","title":"Describe Warehouse Tables","description":"Table and column catalog for raw warehouse SQL (run_sql, raw_sql widgets, raw_query alert rules). With no arguments it lists every table; with `tables` it gives those tables' columns, sorting key and notes on enum casing, units and the columns rollups lack. Read it before writing SQL rather than guessing names.","inputSchema":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"string"},"description":"Tables whose columns and notes to return (at most 5)"}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"tables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"columnCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"timeColumn":{"type":"string"}},"required":["name","columnCount"],"additionalProperties":true}},"described":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"jsonPath":{"type":"string"}},"required":["name","type"],"additionalProperties":true}},"sortingKey":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}}},"required":["name","columns"],"additionalProperties":true}}},"additionalProperties":true},"annotations":{"title":"Describe Warehouse Tables","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}, diff --git a/apps/ai/src/mcp/tools/create-dashboard.ts b/apps/ai/src/mcp/tools/create-dashboard.ts index 194d429322..9b04210356 100644 --- a/apps/ai/src/mcp/tools/create-dashboard.ts +++ b/apps/ai/src/mcp/tools/create-dashboard.ts @@ -12,6 +12,11 @@ import { findNextPosition, } from "@maple/domain/http" import { DASHBOARD_TEMPLATES, getTemplate } from "@maple/backend/dashboard-templates" +import { + convertGrafanaDashboardToPortable, + isGrafanaDashboardJson, +} from "@maple/backend/services/dashboards/grafana-dashboard-import" +import { convertPersesDashboardToPortable } from "@maple/backend/services/dashboards/perses-dashboard-import" import { QUERY_BUILDER_DATA_SOURCES, QUERY_BUILDER_METRIC_TYPES } from "@maple/query-model" import { collectBlockingBuilderWarnings, @@ -320,6 +325,27 @@ const invalid = (message: string, parameter?: string, example?: string) => ...(example === undefined ? undefined : { example }), }) +/** A Grafana or Perses dashboard as a Maple document, with what the conversion changed. */ +const convertImport = Effect.fn("McpTool.createDashboard.convertImport")( + function* (input: Readonly>) { + if (isGrafanaDashboardJson(input)) { + const converted = yield* convertGrafanaDashboardToPortable(input) + return { ...converted, source: "grafana_import" as const } + } + if (input.kind === "Dashboard") { + const converted = yield* convertPersesDashboardToPortable(input) + return { ...converted, stats: undefined, source: "perses_import" as const } + } + return yield* invalid( + "import_json is neither a Grafana dashboard (panels or rows, or { dashboard, meta }) nor a Perses Dashboard resource.", + "import_json", + ) + }, + Effect.catchTag("@maple/http/errors/DashboardValidationError", (error) => + Effect.fail(toMcpDashboardError(TOOL)(error)), + ), +) + const SIMPLE_WIDGETS_EXAMPLE = 'widgets=\'[{"title":"HTTP Duration","visualization":"chart","source":"metrics","metric":"avg","metric_name":"http.server.duration","metric_type":"histogram"}]\'' @@ -341,7 +367,7 @@ export function registerCreateDashboardTool(server: McpToolRegistrar) { // modes to use, not a schema reference. The per-parameter descriptions carry // the shapes, and `describe_dashboard_schema` carries the full vocabulary. description: - "Create a dashboard one of three ways: a `template`, simplified `widgets` specs, or full `dashboard_json`. " + + "Create a dashboard one of four ways: a `template`, simplified `widgets` specs, full `dashboard_json`, or `import_json` (a Grafana or Perses dashboard to convert). " + '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." + @@ -373,6 +399,10 @@ export function registerCreateDashboardTool(server: McpToolRegistrar) { '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.", ), + import_json: optionalJsonText( + Schema.Record(Schema.String, Schema.Unknown), + "A Grafana dashboard (bare, the { dashboard, meta } API envelope, or an export for sharing) or a Perses Dashboard resource, as JSON text. Grafana rows become sections, Prometheus targets PromQL widgets, and panels Maple cannot run notes; the result lists every warning. name, description and time_range override the imported ones when given.", + ), dashboard_json: optionalJsonText( PortableDashboardDocument, "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.", @@ -389,13 +419,31 @@ export function registerCreateDashboardTool(server: McpToolRegistrar) { } const templateName = - params.template ?? - (params.widgets ? undefined : params.dashboard_json ? "custom" : "service-health") + params.import_json === undefined + ? (params.template ?? + (params.widgets ? undefined : params.dashboard_json ? "custom" : "service-health")) + : undefined let portable: PortableDashboardDocument let source: typeof CreateDashboardOutput.Type.source - - if (templateName === "custom") { + let imported: + | { warnings: ReadonlyArray; stats: typeof CreateDashboardOutput.Type.importStats } + | undefined + + if (params.import_json !== undefined) { + const converted = yield* convertImport(params.import_json) + const name = Str.trim(params.name) + portable = new PortableDashboardDocument({ + ...converted.dashboard, + ...(name === "" ? undefined : { name }), + ...(params.description ? { description: params.description } : undefined), + ...(params.time_range + ? { timeRange: { type: "relative" as const, value: params.time_range } } + : undefined), + }) + source = converted.source + imported = { warnings: converted.warnings, stats: converted.stats } + } else if (templateName === "custom") { if (!params.dashboard_json) { return yield* invalid( "Provide dashboard_json for custom template, or use a different approach:\n\n" + @@ -541,6 +589,12 @@ export function registerCreateDashboardTool(server: McpToolRegistrar) { ...(validation.ran ? { validation } : undefined), source, ...(source === "template" && templateName ? { template: templateName } : undefined), + ...(imported === undefined + ? undefined + : { + importWarnings: [...imported.warnings], + ...(imported.stats === undefined ? undefined : { importStats: imported.stats }), + }), // Advisory across every creation path, including `dashboard_json`. renderWarnings: collectDocumentRenderWarnings(dashboard.widgets), } @@ -561,8 +615,30 @@ export function registerCreateDashboardTool(server: McpToolRegistrar) { ["Widgets", output.dashboard.widgetCount], ["Created", Str.slice(0, 19)(output.dashboard.createdAt)], ["Template", output.template], - ["Source", output.source === "widgets" ? "simplified widget specs" : undefined], + [ + "Source", + output.source === "widgets" + ? "simplified widget specs" + : output.source === "grafana_import" + ? "Grafana import" + : output.source === "perses_import" + ? "Perses import" + : undefined, + ], ]), + ...(output.importStats === undefined + ? [] + : [ + doc.fields([ + [ + "Panels converted", + `${output.importStats.converted} of ${output.importStats.panels} (${output.importStats.placeholders} kept as notes)`, + ], + ]), + ]), + ...(output.importWarnings !== undefined && output.importWarnings.length > 0 + ? [doc.heading("Import warnings"), doc.list(output.importWarnings)] + : []), ...(output.renderWarnings.length > 0 ? [doc.heading("Render warnings (saved anyway)"), doc.list(output.renderWarnings)] : []), diff --git a/apps/api/src/routes/v2/dashboards.http.test.ts b/apps/api/src/routes/v2/dashboards.http.test.ts index 249798fe10..7d59920cff 100644 --- a/apps/api/src/routes/v2/dashboards.http.test.ts +++ b/apps/api/src/routes/v2/dashboards.http.test.ts @@ -43,6 +43,7 @@ import { PromqlQueryService } from "@maple/backend/services/promql/PromqlQuerySe import { HttpV2DashboardsLive } from "./dashboards.http" import { HttpV2SharePublicLive } from "./share.http" import { OrganizationService } from "@maple/backend/services/org/OrganizationService" +import { nodeExporterDashboard } from "@maple/backend/services/dashboards/grafana-dashboard-import.fixtures" import { ShareRateLimiter } from "@maple/backend/services/auth/ShareRateLimiter" const createdDbs: TestDb[] = [] @@ -319,6 +320,40 @@ describe("v2 dashboards over HTTP", () => { await harness.dispose() }) + it("imports a Grafana dashboard with its sections, PromQL widgets, warnings and stats", async () => { + const harness = makeHarness() + const key = await harness.bootstrapKey(["dashboards:write"]) + + const imported = await harness.request("POST", "/v2/dashboards/import/grafana", key.secret, { + dashboard: { dashboard: nodeExporterDashboard, meta: {} }, + }) + expect(imported.status).toBe(200) + expect(imported.body.object).toBe("dashboard_import") + expect(imported.body.stats).toEqual({ panels: 7, converted: 7, placeholders: 0 }) + expect(imported.body.warnings).toContain( + 'Interval variable "resolution" was not imported; its references now use $__interval.', + ) + expect(imported.body.dashboard.txid).toMatch(/^\d+$/) + + const stored = await harness.request( + "GET", + `/v2/dashboards/${imported.body.dashboard.id}`, + key.secret, + ) + expect(stored.body.name).toBe("Node overview") + expect(stored.body.sections).toHaveLength(2) + const cpu = stored.body.widgets.find( + (widget: { display: { title: string } }) => widget.display.title === "CPU basic", + ) + expect(cpu.data_source).toMatchObject({ kind: "promql", legend_format: "{{mode}}" }) + + const refused = await harness.request("POST", "/v2/dashboards/import/grafana", key.secret, { + dashboard: { kind: "Dashboard", spec: {} }, + }) + expect(refused.status).toBe(400) + await harness.dispose() + }) + it("refuses a PATCH based on a stale expected_version, and keeps last-write-wins without one", async () => { const harness = makeHarness() const key = await harness.bootstrapKey(["dashboards:write"]) diff --git a/apps/api/src/routes/v2/dashboards.http.ts b/apps/api/src/routes/v2/dashboards.http.ts index cd7fae260e..adedda2d55 100644 --- a/apps/api/src/routes/v2/dashboards.http.ts +++ b/apps/api/src/routes/v2/dashboards.http.ts @@ -51,6 +51,7 @@ import { import { SharedDashboardService } from "@maple/backend/services/dashboards/SharedDashboardService" import { DashboardWidgetDataService } from "@maple/backend/services/dashboards/DashboardWidgetDataService" import { convertPersesDashboardToPortable } from "@maple/backend/services/dashboards/perses-dashboard-import" +import { convertGrafanaDashboardToPortable } from "@maple/backend/services/dashboards/grafana-dashboard-import" const canReadTelemetry = (scopes: ReadonlyArray | undefined) => missingReadScopes(scopes, TELEMETRY_READ_FAMILIES).length === 0 @@ -309,6 +310,21 @@ export const HttpV2DashboardsLive = HttpApiBuilder.group(MapleApiV2, "dashboards const shares = yield* SharedDashboardService const widgetData = yield* DashboardWidgetDataService + // An imported board is created like any other, with its source on the audit row. + const createImported = Effect.fn("HttpV2Dashboards.createImported")(function* ( + portable: PortableDashboardDocument, + source: "perses_import" | "grafana_import", + ) { + const tenant = yield* CurrentTenant.Context + yield* requireRawSqlScopes(tenant.scopes, [], portable.widgets) + const stored = yield* persistence.create(tenant.orgId, tenant.userId, portable) + yield* recordHttpAudit("dashboard.created", { + resourceId: stored.document.id, + metadata: { name: stored.document.name, source }, + }) + return toV2DashboardMutation(stored) + }) + // Share management. // // A share is scoped to a whole dashboard (`widgetId` null) or to one widget. @@ -613,27 +629,27 @@ export const HttpV2DashboardsLive = HttpApiBuilder.group(MapleApiV2, "dashboards }), ) .handle("importPerses", ({ payload }) => - Effect.gen(function* () { - const converted = yield* convertPersesDashboardToPortable(payload.dashboard) - const tenant = yield* CurrentTenant.Context - yield* requireRawSqlScopes(tenant.scopes, [], converted.dashboard.widgets) - const stored = yield* persistence.create( - tenant.orgId, - tenant.userId, - converted.dashboard, - ) - const dashboard = stored.document - yield* recordHttpAudit("dashboard.created", { - resourceId: dashboard.id, - metadata: { name: dashboard.name, source: "perses_import" }, - }) - - return { - object: "dashboard_import" as const, - dashboard: toV2DashboardMutation(stored), - warnings: [...converted.warnings], - } - }), + Effect.flatMap(convertPersesDashboardToPortable(payload.dashboard), (converted) => + createImported(converted.dashboard, "perses_import").pipe( + Effect.map((dashboard) => ({ + object: "dashboard_import" as const, + dashboard, + warnings: [...converted.warnings], + })), + ), + ), + ) + .handle("importGrafana", ({ payload }) => + Effect.flatMap(convertGrafanaDashboardToPortable(payload.dashboard), (converted) => + createImported(converted.dashboard, "grafana_import").pipe( + Effect.map((dashboard) => ({ + object: "dashboard_import" as const, + dashboard, + warnings: [...converted.warnings], + stats: converted.stats, + })), + ), + ), ) .handle("listVersions", ({ params, query }) => Effect.gen(function* () { diff --git a/apps/web/src/lab/entries/settings-dialogs.ts b/apps/web/src/lab/entries/settings-dialogs.ts index c05f57e520..977b3d5e84 100644 --- a/apps/web/src/lab/entries/settings-dialogs.ts +++ b/apps/web/src/lab/entries/settings-dialogs.ts @@ -6,7 +6,7 @@ import { AsyncData, Submodel } from "foldkit" import type { Html, HtmlBuilder } from "foldkit/html" import { defineMessageUnion } from "foldkit/message" import type { PageContext } from "../../page/contract" -import { deleteDialog } from "../../page/dashboards/list/view-dialogs" +import { deleteDialog, importReportDialog } from "../../page/dashboards/list/view-dialogs" import * as DashboardList from "../../page/dashboards/list/update" import * as DashboardListModel from "../../page/dashboards/list/model" import type { Message as DashboardListMessage } from "../../page/dashboards/list/message" @@ -40,6 +40,7 @@ const ITEMS = [ "disconnect-pending", "dashboard-delete", "dashboard-delete-pending", + "dashboard-import-report", "key-create", "key-created", "destination", @@ -113,6 +114,29 @@ const dashboards = (isDeleting: boolean): DashboardListModel.Model => { } } +/** A Grafana import with a placeholder, a dropped query and a renamed variable. */ +const dashboardImportReport = (): DashboardListModel.Model => { + const model = DashboardList.init({ search: {} }, context).model + return { + ...model, + importReport: { + id: "dash_lab", + name: "Node overview", + panels: 9, + converted: 7, + warnings: [ + 'Panel "CPU basic" has 2 queries; Maple imported A only. Not imported: B: count(node_cpu_seconds_total)', + 'Panel "Error logs" queries Loki, which Maple cannot run; it was imported as a placeholder.', + 'Logs panel "Recent logs" was imported as a placeholder.', + 'Variable "host-name" was renamed to "host_name"; queries that use it were rewritten.', + 'Interval variable "resolution" was not imported; its references now use $__interval.', + 'Panel "Traffic" uses the Grafana unit "bps", which Maple has no match for; it shows plain numbers.', + ], + }, + importReportDialog: opened(model.importReportDialog), + } +} + const createdKey = Schema.decodeSync(V2ApiKeyWithSecret)({ id: "key_aXwpxqBkqtYwtBtmsGbR41", object: "api_key", @@ -227,6 +251,9 @@ const disconnectView = Submodel.defineView((model, h) => deleteDialog(h, model), ) +const importReportView = Submodel.defineView((model, h) => + importReportDialog(h, model), +) const sourceView = Submodel.defineView((model, h) => settingsTab(h, model, source, "UTC"), ) @@ -249,6 +276,13 @@ const render = (h: HtmlBuilder, item: string): Html => { view: dashboardView, toParentMessage: ignore, }) + case "dashboard-import-report": + return h.submodel({ + slotId: "lab-dashboard-import-report", + model: dashboardImportReport(), + view: importReportView, + toParentMessage: ignore, + }) case "key-create": case "key-created": return h.submodel({ diff --git a/apps/web/src/page/dashboards/kit/portable.test.ts b/apps/web/src/page/dashboards/kit/portable.test.ts new file mode 100644 index 0000000000..1b7852fa56 --- /dev/null +++ b/apps/web/src/page/dashboards/kit/portable.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, test } from "vitest" +import { isGrafanaDashboardJson, isPersesDashboardJson } from "./portable" + +const grafana = { title: "Node", schemaVersion: 39, panels: [{ type: "stat" }] } + +describe("which importer a dashboard file goes to", () => { + test("Grafana: a board with panels or old rows and a schemaVersion, or the API envelope", () => { + expect(isGrafanaDashboardJson(grafana)).toBe(true) + expect(isGrafanaDashboardJson({ title: "Old", schemaVersion: 14, rows: [] })).toBe(true) + expect(isGrafanaDashboardJson({ dashboard: { panels: [] }, meta: { slug: "node" } })).toBe(true) + }) + + test("not Grafana: Maple JSON, Perses, or panels without a schema version", () => { + const maple = { name: "Maple", timeRange: { type: "relative", value: "6h" }, widgets: [] } + const perses = { kind: "Dashboard", spec: { panels: {} } } + expect(isGrafanaDashboardJson(maple)).toBe(false) + expect(isGrafanaDashboardJson(perses)).toBe(false) + expect(isGrafanaDashboardJson({ panels: [] })).toBe(false) + expect(isGrafanaDashboardJson([grafana])).toBe(false) + expect(isPersesDashboardJson(grafana)).toBe(false) + }) +}) diff --git a/apps/web/src/page/dashboards/kit/portable.ts b/apps/web/src/page/dashboards/kit/portable.ts index 6bb554904e..3c0f022c6c 100644 --- a/apps/web/src/page/dashboards/kit/portable.ts +++ b/apps/web/src/page/dashboards/kit/portable.ts @@ -87,6 +87,22 @@ export const isPersesDashboardJson = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Arr.isArray(value) + +const hasGrafanaPanels = (value: Record) => + Arr.isArray(value.panels) || Arr.isArray(value.rows) + +/** + * A Grafana dashboard: `panels` or the old `rows` with a `schemaVersion`, or the API's + * `{ dashboard, meta }` envelope around one. Maple JSON has `widgets`, Perses `kind`. + */ +export const isGrafanaDashboardJson = (value: unknown): value is Record => { + if (!isPlainObject(value)) return false + if (isPlainObject(value.dashboard)) return hasGrafanaPanels(value.dashboard) + return hasGrafanaPanels(value) && value.schemaVersion !== undefined +} + const sanitizeFilenameSegment = (value: string): string => { const sanitized = Str.trim(Str.replace(/[^a-zA-Z0-9-_ ]/g, "")(value)) return sanitized.length > 0 ? sanitized : "dashboard" diff --git a/apps/web/src/page/dashboards/list/command.ts b/apps/web/src/page/dashboards/list/command.ts index 5a3c4faadd..e093bce1e7 100644 --- a/apps/web/src/page/dashboards/list/command.ts +++ b/apps/web/src/page/dashboards/list/command.ts @@ -13,6 +13,7 @@ import { import { createPayload, downloadPortable, + isGrafanaDashboardJson, isPersesDashboardJson, type PortableDashboard, parsePortable, @@ -114,7 +115,7 @@ const createFromPortable = (orgId: string, portable: PortableDashboard) => // Blank, imported or duplicated: every create is one `dashboard_created`. yield* trackProduct("dashboard_created", { widgets: portable.widgets.length }) yield* awaitTxid(orgId, created.txid) - return { id: created.id, name: created.name, isPerses: false, warnings: [] } + return { id: created.id, name: created.name, importedFrom: null, warnings: [], stats: null } }) const toResult = (effect: Effect.Effect) => @@ -202,7 +203,7 @@ export const ExportDashboard = Command.define("ExportDashboard", { ), }) -/** A Perses dashboard goes to `importPerses`, anything else must be portable. */ +/** A Perses or Grafana dashboard goes to its import endpoint, anything else must be portable. */ export const ImportDashboard = Command.define("ImportDashboard", { args: { orgId: Schema.String, file: FoldkitFile }, messages: [Message.CompletedImportDashboard], @@ -228,8 +229,23 @@ export const ImportDashboard = Command.define("ImportDashboard", { return { id: imported.dashboard.id, name: imported.dashboard.name, - isPerses: true, + importedFrom: "perses" as const, warnings: imported.warnings, + stats: null, + } + } + if (isGrafanaDashboardJson(parsed)) { + const client = yield* MapleApiV2Client + const imported = yield* client.dashboards.importGrafana({ + payload: { dashboard: parsed }, + }) + yield* awaitTxid(orgId, imported.dashboard.txid) + return { + id: imported.dashboard.id, + name: imported.dashboard.name, + importedFrom: "grafana" as const, + warnings: imported.warnings, + stats: imported.stats, } } const portable = yield* parsePortable(parsed) diff --git a/apps/web/src/page/dashboards/list/list-sync.scene.test.ts b/apps/web/src/page/dashboards/list/list-sync.scene.test.ts index 509d669fef..14c910c7c8 100644 --- a/apps/web/src/page/dashboards/list/list-sync.scene.test.ts +++ b/apps/web/src/page/dashboards/list/list-sync.scene.test.ts @@ -2,6 +2,7 @@ import { OrgId } from "@maple/domain" import { Result, Schema, Array as Arr } from "effect" import { expect as expectView, given, Mount, role, scene, text, withViewInputs } from "foldkit/scene" import { describe, expect, test } from "vitest" +import * as Dialog from "@maple/views/ui/dialog" import * as Menu from "@maple/views/ui/menu" import { PageOutMessage, type PageContext } from "../../contract" import { CreateDashboard, FetchDashboardsFallback } from "./command" @@ -155,7 +156,13 @@ describe("dashboards list write feedback", () => { const imported = pageUpdate( listed(), Message.CompletedImportDashboard({ - result: Result.succeed({ id: "dash_new", name: "Perses", isPerses: true, warnings }), + result: Result.succeed({ + id: "dash_new", + name: "Perses", + importedFrom: "perses", + warnings, + stats: null, + }), }), ) const out = imported.outMessage @@ -166,6 +173,67 @@ describe("dashboards list write feedback", () => { }) }) + test("a Grafana import with warnings stays on the list and reports them in a dialog", () => { + const warnings = [ + 'Panel "Error logs" queries Loki, which Maple cannot run; it was imported as a placeholder.', + ] + const imported = pageUpdate( + listed(), + Message.CompletedImportDashboard({ + result: Result.succeed({ + id: "dash_grafana", + name: "Node overview", + importedFrom: "grafana", + warnings, + stats: { panels: 7, converted: 6 }, + }), + }), + ) + expect(imported.outMessage).toBeUndefined() + scene( + { update: pageUpdate, view }, + given(imported.model), + Mount.resolve(Dialog.MountDialog, Dialog.Message.CompletedMountDialog()), + expectView(role("alertdialog", { name: "Imported “Node overview”" })).toExist(), + expectView( + text( + "6 of 7 panels converted. 1 panel Maple cannot run yet became a note that keeps its original queries.", + ), + ).toExist(), + expectView(text(warnings[0] ?? "")).toExist(), + expectView(role("button", { name: "Open dashboard" })).toExist(), + ) + const opened = pageUpdate(imported.model, Message.ClickedOpenImportedDashboard()) + expect(opened.outMessage).toEqual( + PageOutMessage.RequestedNavigation({ url: "/dashboards/dash_grafana", isReplace: false }), + ) + // Closing the report forgets it: the warnings were read in the dialog. + const closed = pageUpdate( + imported.model, + Message.GotImportReportDialogMessage({ message: Dialog.Message.ClickedClose() }), + ) + expect(closed.model.importReport).toBeNull() + }) + + test("a clean Grafana import opens the dashboard with a toast naming Grafana", () => { + const imported = pageUpdate( + listed(), + Message.CompletedImportDashboard({ + result: Result.succeed({ + id: "dash_grafana", + name: "Node overview", + importedFrom: "grafana", + warnings: [], + stats: { panels: 3, converted: 3 }, + }), + }), + ) + const out = imported.outMessage + expect(out?._tag === "RequestedNavigation" && out.toast?.title).toBe( + 'Dashboard "Node overview" imported from Grafana', + ) + }) + test("a refused write toasts and leaves the list writable", () => { const creating = pageUpdate(listed(), Message.ClickedCreate()).model const refused = pageUpdate( diff --git a/apps/web/src/page/dashboards/list/message.ts b/apps/web/src/page/dashboards/list/message.ts index 76cc3738b3..7d8763797c 100644 --- a/apps/web/src/page/dashboards/list/message.ts +++ b/apps/web/src/page/dashboards/list/message.ts @@ -8,14 +8,21 @@ import * as Combobox from "@maple/views/ui/combobox" import { ListDashboard, Scope } from "./model" import { WriteSync } from "../kit/store" +/** How many source panels an import turned into working widgets. */ +export const ImportStats = Schema.Struct({ panels: Schema.Number, converted: Schema.Number }) +export type ImportStats = typeof ImportStats.Type + /** A created dashboard: its id to open and its name for the toast. */ const Created = Schema.Struct({ id: Schema.String, name: Schema.String, - isPerses: Schema.Boolean, - /** A Perses import's conversion warnings (unsupported or changed panels). */ + /** The tool an imported file came from; `null` for Maple JSON and duplicates. */ + importedFrom: Schema.NullOr(Schema.Literals(["perses", "grafana"])), + /** An import's conversion warnings (unsupported or changed panels). */ warnings: Schema.Array(Schema.String), + stats: Schema.NullOr(ImportStats), }) +export type CreatedDashboard = typeof Created.Type /** A failed write: its message, and whether the API refused this one write. */ export const WriteFailure = Schema.Struct({ message: Schema.String, isRejected: Schema.Boolean }) @@ -50,6 +57,8 @@ export const Message = defineMessageUnion({ CompletedOpenImportPicker: {}, ChoseImportFile: { files: Schema.Array(File) }, CompletedImportDashboard: { result: Schema.Result(Created, Schema.String) }, + GotImportReportDialogMessage: { message: Dialog.Message }, + ClickedOpenImportedDashboard: {}, ToggledFavorite: { id: Schema.String }, CompletedSavePreferences: {}, GotSortMenuMessage: { message: Menu.Message }, diff --git a/apps/web/src/page/dashboards/list/model.ts b/apps/web/src/page/dashboards/list/model.ts index 1ef63ebe31..997a561424 100644 --- a/apps/web/src/page/dashboards/list/model.ts +++ b/apps/web/src/page/dashboards/list/model.ts @@ -44,6 +44,16 @@ export type Fallback = typeof Fallback.Type export const Scope = Schema.Literals(["all", "favorites"]) export type Scope = typeof Scope.Type +/** What a Grafana import changed, shown before opening the new dashboard. */ +export const ImportReport = Schema.Struct({ + id: Schema.String, + name: Schema.String, + warnings: Schema.Array(Schema.String), + panels: Schema.Number, + converted: Schema.Number, +}) +export type ImportReport = typeof ImportReport.Type + export const Model = Schema.Struct({ search: DashboardsSearch, /** `null` until the collection is ready. */ @@ -73,6 +83,9 @@ export const Model = Schema.Struct({ /** A failed write turns the list read-only with this reason. */ persistenceError: Schema.NullOr(Schema.String), isCreating: Schema.Boolean, + /** The last import's report; its dialog lists the warnings. */ + importReport: Schema.NullOr(ImportReport), + importReportDialog: Dialog.Model, /** The live list never answered within `COLLECTION_LOAD_TIMEOUT_MS`: the HTTP snapshot's state. */ fallback: Fallback, /** The keyboard-focused row, by id: the live list reorders under it. None until J or K is pressed. */ diff --git a/apps/web/src/page/dashboards/list/update.ts b/apps/web/src/page/dashboards/list/update.ts index 93ba57755a..ac830cff7c 100644 --- a/apps/web/src/page/dashboards/list/update.ts +++ b/apps/web/src/page/dashboards/list/update.ts @@ -28,7 +28,7 @@ import { displayName, queryOf, sectionsOf, tagsOf } from "./derive" import { focusedIndexOf, listKeyAction, scrollFocusedRowCommand } from "../../kit/list-keys" import * as Combobox from "@maple/views/ui/combobox" import { INITIAL_LOCALE } from "@maple/views/lib/locale" -import { Message, type WriteFailure } from "./message" +import { type CreatedDashboard, Message, type WriteFailure } from "./message" import type { ListDashboard, Model } from "./model" export type Return = PageReturn @@ -36,6 +36,7 @@ type Search = typeof DashboardsSearch.Type type Route = Readonly<{ search: Search }> export const SORT_MENU_ID = "dashboards-sort-menu" +const IMPORT_REPORT_DIALOG_ID = "dashboard-import-report-dialog" export const TAG_FILTER_ID = "dashboards-tag-filter" export const rowMenuIdOf = (id: string): string => `dashboard-row-menu-${id}` @@ -61,6 +62,8 @@ export const init = (route: Route, _context: PageContext): Return => ({ tagFilter: Combobox.init(TAG_FILTER_ID, "multiple", { selected: tagsOf(route.search) }), persistenceError: null, isCreating: false, + importReport: null, + importReportDialog: Dialog.init(IMPORT_REPORT_DIALOG_ID, "alert-dialog"), fallback: { _tag: "Idle" }, focusedId: null, }, @@ -190,6 +193,7 @@ const closeDialog = (dialog: Dialog.Model, wrap: (message: Dialog.Message) => Me } const wrapDelete = (message: Dialog.Message) => Message.GotDeleteDialogMessage({ message }) +const wrapImportReport = (message: Dialog.Message) => Message.GotImportReportDialogMessage({ message }) const wrapTags = (message: TagEditor.Message) => Message.GotTagEditorMessage({ message }) /** A row menu item picked: export, duplicate, edit tags, delete. */ @@ -273,6 +277,38 @@ const warningsToast = (warnings: ReadonlyArray): WarningToast => ({ description: `${Arr.join(warnings.slice(0, 3), "\n")}${warnings.length > 3 ? `\n+${warnings.length - 3} more` : ""}`, }) +const IMPORT_SOURCE_LABEL = { perses: "Perses", grafana: "Grafana" } as const + +/** + * A Grafana import that changed something stays on the list with a report of what changed; + * any other import opens the new dashboard, its warnings in a follow-up toast. + */ +const importSucceeded = (model: Model, created: CreatedDashboard): Return => { + const stats = created.stats + if (stats !== null && (created.warnings.length > 0 || stats.converted < stats.panels)) { + const opened = openDialog(model.importReportDialog, wrapImportReport) + return { + model: { + ...model, + importReport: { id: created.id, name: created.name, warnings: created.warnings, ...stats }, + importReportDialog: opened.dialog, + }, + commands: opened.commands, + } + } + const navigation = navigateWithToast( + model, + dashboardHref(created.id), + created.importedFrom === null + ? `Dashboard "${created.name}" imported` + : `Dashboard "${created.name}" imported from ${IMPORT_SOURCE_LABEL[created.importedFrom]}`, + ) + const out = navigation.outMessage + return created.warnings.length === 0 || out?._tag !== "RequestedNavigation" + ? navigation + : { ...navigation, outMessage: { ...out, followUpToast: warningsToast(created.warnings) } } +} + /** * A refused write (a taken name, a stale edit) only toasts. A store failure turns the list read-only; * the banner says so, so no toast repeats it. A list still waiting on live sync reads the HTTP snapshot @@ -371,23 +407,31 @@ export const update = (model: Model, message: Message, context: PageContext): Re CompletedImportDashboard: ({ result }) => Result.match(result, { onFailure: (error) => toastFailure(model, error), - onSuccess: (created) => { - const navigation = navigateWithToast( - model, - dashboardHref(created.id), - created.isPerses - ? `Dashboard "${created.name}" imported from Perses` - : `Dashboard "${created.name}" imported`, - ) - const out = navigation.outMessage - return created.warnings.length === 0 || out?._tag !== "RequestedNavigation" - ? navigation - : { - ...navigation, - outMessage: { ...out, followUpToast: warningsToast(created.warnings) }, - } - }, + onSuccess: (created) => importSucceeded(model, created), }), + GotImportReportDialogMessage: ({ message: inner }) => + dialogStep( + model, + model.importReportDialog, + inner, + // The report was read in the dialog; once it closes, nothing keeps it. + (importReportDialog) => + importReportDialog.isOpen + ? { importReportDialog } + : { importReportDialog, importReport: null }, + wrapImportReport, + ), + ClickedOpenImportedDashboard: () => { + if (model.importReport === null) return { model } + const closed = closeDialog(model.importReportDialog, wrapImportReport) + return { + ...navigateTo( + { ...model, importReportDialog: closed.dialog }, + dashboardHref(model.importReport.id), + ), + commands: closed.commands, + } + }, ToggledFavorite: ({ id }) => { const favorites = model.favorites.includes(id) ? Arr.filter(model.favorites, (favorite) => favorite !== id) diff --git a/apps/web/src/page/dashboards/list/view-dialogs.test.ts b/apps/web/src/page/dashboards/list/view-dialogs.test.ts new file mode 100644 index 0000000000..52334d30dd --- /dev/null +++ b/apps/web/src/page/dashboards/list/view-dialogs.test.ts @@ -0,0 +1,16 @@ +import { describe, expect, it } from "vitest" +import { importReportSummary } from "./view-dialogs" + +describe("importReportSummary", () => { + it("says a panel-less dashboard has nothing to convert, not 0 of 0", () => { + expect(importReportSummary({ panels: 0, converted: 0 })).toBe( + "The dashboard has no panels to convert.", + ) + }) + + it("counts converted panels and the notes the rest became", () => { + expect(importReportSummary({ panels: 5, converted: 4 })).toBe( + "4 of 5 panels converted. 1 panel Maple cannot run yet became a note that keeps its original queries.", + ) + }) +}) diff --git a/apps/web/src/page/dashboards/list/view-dialogs.ts b/apps/web/src/page/dashboards/list/view-dialogs.ts index d199d283fc..7f111f6442 100644 --- a/apps/web/src/page/dashboards/list/view-dialogs.ts +++ b/apps/web/src/page/dashboards/list/view-dialogs.ts @@ -1,5 +1,9 @@ import type { Html, HtmlBuilder } from "foldkit/html" +import { Array as Arr } from "effect" +import { countLabel } from "@maple/ui/lib/format" import { confirmDialog } from "@maple/views/ui/confirm-dialog" +import { dividedList } from "@maple/views/ui/rule" +import { typography } from "@maple/views/ui/typography" import { displayName } from "./derive" import { Message } from "./message" import type { Model } from "./model" @@ -19,3 +23,52 @@ export const deleteDialog = (h: H, model: Model): Html => isPending: model.isDeleting, onConfirm: Message.ClickedConfirmDelete(), }) + +/** The report's summary line; a dashboard with no panels says so instead of "0 of 0". */ +export const importReportSummary = (report: { + readonly panels: number + readonly converted: number +}): string => { + if (report.panels === 0) return "The dashboard has no panels to convert." + const notes = report.panels - report.converted + const noteText = + notes === 1 + ? " 1 panel Maple cannot run yet became a note that keeps its original queries." + : notes > 1 + ? ` ${countLabel(notes, "panel")} Maple cannot run yet became notes that keep the original queries.` + : "" + return `${report.converted} of ${countLabel(report.panels, "panel")} converted.${noteText}` +} + +/** After a Grafana import: how many panels converted, and every warning, before opening it. */ +export const importReportDialog = (h: H, model: Model): Html => { + const report = model.importReport + if (report === null) return h.empty + return confirmDialog(h, { + slotId: model.importReportDialog.id, + model: model.importReportDialog, + toParentMessage: (message) => Message.GotImportReportDialogMessage({ message }), + tone: "default", + hasIcon: false, + title: ["Imported “", displayName(report.name), "”"], + description: importReportSummary(report), + children: + report.warnings.length === 0 + ? [] + : [ + dividedList( + h, + { as: "ul", className: "max-h-72 overflow-y-auto" }, + Arr.map(report.warnings, (warning) => + h.li( + [h.Class("px-3 py-2")], + [typography(h, { size: "sm", tone: "muted" }, [warning])], + ), + ), + ), + ], + cancelLabel: "Close", + confirmLabel: "Open dashboard", + onConfirm: Message.ClickedOpenImportedDashboard(), + }) +} diff --git a/apps/web/src/page/dashboards/list/view-list.ts b/apps/web/src/page/dashboards/list/view-list.ts index d7d559b318..08a9d6ae72 100644 --- a/apps/web/src/page/dashboards/list/view-list.ts +++ b/apps/web/src/page/dashboards/list/view-list.ts @@ -30,7 +30,7 @@ import * as TagEditor from "../kit/tag-editor" import { Message } from "./message" import type { ListDashboard, Model, Scope } from "./model" import { isReadOnly, rowMenuIdOf } from "./update" -import { deleteDialog } from "./view-dialogs" +import { deleteDialog, importReportDialog } from "./view-dialogs" import { tagFilterView } from "./view-tag-filter" import { typography, typographyClass } from "@maple/views/ui/typography" import { hstack, vstack } from "@maple/views/ui/stack" @@ -554,6 +554,7 @@ export const listBody = ( toParentMessage: (message) => Message.GotTagEditorMessage({ message }), }), deleteDialog(h, model), + importReportDialog(h, model), ]) } diff --git a/packages/backend/src/services/dashboards/dashboard-import-shared.ts b/packages/backend/src/services/dashboards/dashboard-import-shared.ts new file mode 100644 index 0000000000..8ffbbb169c --- /dev/null +++ b/packages/backend/src/services/dashboards/dashboard-import-shared.ts @@ -0,0 +1,248 @@ +// Pure helpers the Perses and Grafana importers share: lenient readers over +// untrusted JSON, widget ids, placeholder notes and ClickHouse SQL scoping. +import { dashboardTimeBoundIssue } from "@maple/domain/raw-sql" +import { Array as Arr, String as Str } from "effect" +import { + type DashboardWidgetSchema, + type RawSqlDisplayType, + widgetTypeByVisualization, +} from "@maple/domain/http" +import { makeRawSqlDataSource, makeStaticDataSource } from "@maple/widgets/dashboard" + +export type UnknownRecord = Record +export type DashboardWidget = typeof DashboardWidgetSchema.Type + +export const isRecord = (value: unknown): value is UnknownRecord => + typeof value === "object" && value !== null && !Arr.isArray(value) + +export const asRecord = (value: unknown): UnknownRecord | null => (isRecord(value) ? value : null) + +export const asArray = (value: unknown): unknown[] => (Arr.isArray(value) ? value : []) + +export const asString = (value: unknown): string | undefined => + typeof value === "string" && Str.trim(value).length > 0 ? value : undefined + +export const asFiniteNumber = (value: unknown): number | undefined => + typeof value === "number" && Number.isFinite(value) ? value : undefined + +const sanitizeIdSegment = (value: string): string => { + const normalized = Str.replace(/^-+|-+$/g, "")(Str.replace(/[^a-z0-9_-]+/g, "-")(Str.toLowerCase(value))) + return normalized.length > 0 ? normalized : "panel" +} + +/** `-`, suffixed `-2`, `-3` until it is not in `existing`; records the id. */ +export function uniqueWidgetId(prefix: string, key: string, existing: Set): string { + const base = `${prefix}-${sanitizeIdSegment(key)}` + let candidate = base + let index = 2 + while (existing.has(candidate)) { + candidate = `${base}-${index++}` + } + existing.add(candidate) + return candidate +} + +function hasOrgScope(sql: string): boolean { + return Str.includes("$__orgFilter")(sql) || /\bOrgId\b/.test(sql) +} + +/** + * Where `keyword` first appears at the top level of `sql`: outside parentheses, quotes and comments. + * A clause inside a subquery or a string literal is not the outer query's. + */ +function topLevelIndex(sql: string, keyword: RegExp): number | undefined { + const sticky = new RegExp(`(? 0) { + if (sql[i] === "/" && sql[i + 1] === "*") { + comments += 1 + i += 2 + } else if (sql[i] === "*" && sql[i + 1] === "/") { + comments -= 1 + i += 2 + } else i += 1 + } + i -= 1 + } else if (ch === "(") depth += 1 + else if (ch === ")") depth -= 1 + else if (depth === 0) { + sticky.lastIndex = i + if (sticky.test(sql)) return i + } + } + return undefined +} + +// Every clause ClickHouse allows after WHERE; the org filter goes before the first of them. +const TRAILING_CLAUSE = /GROUP\s+BY|HAVING|WINDOW|QUALIFY|ORDER\s+BY|LIMIT|OFFSET|FORMAT|SETTINGS/ + +/** + * The outer query with `$__orgFilter` ANDed onto its WHERE (or a WHERE added), before its first + * trailing clause. The existing predicate is grouped, so a top-level OR cannot escape the filter, + * and a terminal semicolon is dropped so the filter stays inside the statement. + */ +function withOrgFilter(sql: string): string { + const statement = Str.replace(/;\s*$/, "")(Str.trimEnd(sql)) + const trailingAt = topLevelIndex(statement, TRAILING_CLAUSE) + const head = trailingAt === undefined ? statement : Str.trimEnd(Str.slice(0, trailingAt)(statement)) + const tail = trailingAt === undefined ? "" : ` ${Str.trimStart(Str.slice(trailingAt)(statement))}` + const whereAt = topLevelIndex(head, /WHERE/) + // A `--` comment runs to the end of its line, so text placed after one starts a new line. + const endsInComment = (text: string) => Str.includes("--")(text) + if (whereAt === undefined) { + return `${head}${endsInComment(head) ? "\n" : " "}WHERE $__orgFilter${tail}` + } + const predicateAt = whereAt + "WHERE".length + const predicate = Str.trim(Str.slice(predicateAt)(head)) + const close = endsInComment(predicate) ? "\n)" : ")" + return `${Str.slice(0, predicateAt)(head)} (${predicate}${close} AND $__orgFilter${tail}` +} + +export type NormalizedSql = { readonly sql: string } | { readonly placeholderReason: string } + +/** Org-scopes an imported ClickHouse query, or explains why it must stay a placeholder. */ +export function normalizeClickHouseSql(sql: string, warnings: string[], panelTitle: string): NormalizedSql { + if (!hasOrgScope(sql)) { + warnings.push( + `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query does not include $__orgFilter or an OrgId predicate.`, + ) + return { placeholderReason: "This ClickHouse query needs Maple org scoping before it can run." } + } + + const fromAt = topLevelIndex(sql, /FROM/) + // The outer query reads a subquery: its rows may have no OrgId column to filter, so the scope + // has to be written inside it by hand. + const readsSubquery = fromAt !== undefined && /^FROM\s*\(/i.test(Str.slice(fromAt)(sql)) + // A UNION, INTERSECT or EXCEPT joins statements that each need their own scope. `SELECT * EXCEPT (col)` + // is ClickHouse's column exclusion, not a set operation, so EXCEPT counts only before a SELECT. + const combinesQueries = + topLevelIndex(sql, /UNION|INTERSECT|EXCEPT\s+(?:ALL\s+|DISTINCT\s+)?\(?\s*SELECT/) !== undefined + if (!Str.includes("$__orgFilter")(sql) && combinesQueries) { + warnings.push( + `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query combines several SELECTs; add $__orgFilter to each.`, + ) + return { + placeholderReason: + "This ClickHouse query needs $__orgFilter in each of its SELECTs before it can run.", + } + } + if (!Str.includes("$__orgFilter")(sql) && readsSubquery) { + warnings.push( + `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query reads a subquery; add $__orgFilter inside it.`, + ) + return { + placeholderReason: + "This ClickHouse query needs $__orgFilter inside its subquery before it can run.", + } + } + + const normalized = Str.includes("$__orgFilter")(sql) ? sql : withOrgFilter(sql) + + if (!Str.includes("$__orgFilter")(sql)) { + warnings.push( + `Panel "${panelTitle}" had an explicit OrgId reference; Maple added $__orgFilter so the widget stays tenant-scoped.`, + ) + } + + // Saving refuses raw SQL that reads outside the dashboard range (DashboardPersistenceService). + if (dashboardTimeBoundIssue(normalized) !== null) { + warnings.push( + `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query does not use $__timeFilter(...) or $__startTime, so it would read all retained data on every refresh.`, + ) + return { + placeholderReason: + "This ClickHouse query needs a Maple time filter ($__timeFilter(...) or $__startTime) before it can run.", + } + } + + return { sql: normalized } +} + +/** A scalar panel (or a `stat` display type) reduces the rows to the first `value`. */ +export function scalarTransform(visualization: string, displayType: string) { + const isScalar = displayType === "stat" || widgetTypeByVisualization(visualization)?.isScalar === true + return isScalar ? { reduceToValue: { field: "value", aggregate: "first" as const } } : undefined +} + +export function rawSqlDataSource(args: { + visualization: string + sql: string + displayType: RawSqlDisplayType + /** A scalar's reducer from the source dashboard; the default reads the first row. */ + transform?: + | ReturnType + | { + readonly reduceToValue: { + readonly field: string + readonly aggregate: "first" | "avg" | "max" | "min" | "sum" | "count" + } + } +}): DashboardWidget["dataSource"] { + const transform = args.transform ?? scalarTransform(args.visualization, args.displayType) + return makeRawSqlDataSource({ + sql: args.sql, + displayType: args.displayType, + ...(transform ? { transform } : undefined), + }) +} + +/** A markdown note: a text panel, or a placeholder for one the importer cannot run. */ +export function markdownWidget(args: { + id: string + title: string + description?: string | undefined + content: string + layout: DashboardWidget["layout"] +}): DashboardWidget { + return { + id: args.id, + visualization: "markdown", + dataSource: makeStaticDataSource(), + display: { + title: args.title, + ...(args.description ? { description: args.description } : undefined), + markdown: { content: args.content }, + }, + layout: args.layout, + } +} + +/** A note naming what the source panel was and the queries it held, so nothing is lost silently. */ +export function placeholderWidget(args: { + source: "Perses" | "Grafana" + id: string + title: string + description?: string | undefined + layout: DashboardWidget["layout"] + reason: string + /** e.g. ["Panel plugin", "TimeSeriesChart"]. */ + panelKind?: readonly [label: string, kind: string] + querySummaries?: readonly string[] +}): DashboardWidget { + const lines = [ + `### ${args.source} import placeholder`, + args.reason, + ...(args.panelKind ? [`${args.panelKind[0]}: \`${args.panelKind[1]}\``] : []), + ...(args.querySummaries && args.querySummaries.length > 0 + ? ["", "Queries:", ...Arr.map(args.querySummaries, (summary) => `- ${summary}`)] + : []), + ] + return markdownWidget({ ...args, content: Arr.join(lines, "\n") }) +} diff --git a/packages/backend/src/services/dashboards/grafana-dashboard-import.fixtures.ts b/packages/backend/src/services/dashboards/grafana-dashboard-import.fixtures.ts new file mode 100644 index 0000000000..9597f34653 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-dashboard-import.fixtures.ts @@ -0,0 +1,278 @@ +// Hand-written Grafana dashboards for the importer tests, trimmed to what each case exercises. +import { Array as Arr } from "effect" + +const promDs = { type: "prometheus", uid: "$datasource" } + +const thresholds = (steps: ReadonlyArray) => ({ + mode: "absolute", + steps: Arr.map(steps, ([color, value]) => ({ color, value })), +}) + +/** A Node Exporter style board: a root note, an open row of stats and charts, a collapsed row. */ +export const nodeExporterDashboard = { + title: "Node overview", + description: "Host metrics from node_exporter", + tags: ["linux", "node"], + schemaVersion: 39, + time: { from: "now-24h", to: "now" }, + refresh: "1m", + templating: { + list: [ + { name: "datasource", type: "datasource", query: "prometheus" }, + { + name: "job", + type: "query", + datasource: promDs, + query: { query: "label_values(node_uname_info, job)", refId: "A" }, + current: { text: "node", value: "node" }, + }, + { + name: "node", + label: "Host", + type: "query", + datasource: promDs, + query: 'label_values(node_uname_info{job="$job"}, instance)', + includeAll: true, + current: { text: "All", value: "$__all" }, + }, + { name: "resolution", type: "interval", query: "1m,5m,1h" }, + { + name: "mountpoint", + type: "custom", + query: "/,/home,/var", + current: { text: "/", value: "/" }, + }, + ], + }, + panels: [ + { + id: 1, + type: "text", + title: "About", + gridPos: { x: 0, y: 0, w: 24, h: 3 }, + options: { mode: "markdown", content: "Fleet **health** at a glance." }, + }, + { + id: 2, + type: "row", + title: "Quick CPU / Mem / Disk", + collapsed: false, + gridPos: { x: 0, y: 3, w: 24, h: 1 }, + panels: [], + }, + { + id: 3, + type: "stat", + title: "CPU busy", + datasource: promDs, + gridPos: { x: 0, y: 4, w: 3, h: 4 }, + fieldConfig: { + defaults: { + unit: "percent", + decimals: 1, + thresholds: thresholds([ + ["green", null], + ["orange", 85], + ["red", 95], + ]), + }, + }, + targets: [ + { + refId: "A", + expr: '100 * (1 - avg(rate(node_cpu_seconds_total{mode="idle",instance="$node"}[$__rate_interval])))', + legendFormat: "__auto", + }, + ], + }, + { + id: 4, + type: "gauge", + title: "Root FS used", + datasource: promDs, + gridPos: { x: 3, y: 4, w: 3, h: 4 }, + fieldConfig: { + defaults: { + unit: "percentunit", + min: 0, + max: 1, + thresholds: thresholds([ + ["green", null], + ["dark-red", 0.9], + ]), + }, + }, + targets: [ + { + refId: "A", + expr: '1 - node_filesystem_avail_bytes{mountpoint="${mountpoint}"} / node_filesystem_size_bytes', + }, + ], + }, + { + id: 5, + type: "stat", + title: "Uptime", + datasource: promDs, + gridPos: { x: 6, y: 4, w: 2, h: 4 }, + fieldConfig: { defaults: { unit: "s" } }, + targets: [ + { refId: "A", expr: 'time() - node_boot_time_seconds{instance="$node"}', hide: true }, + { refId: "B", expr: "node_time_seconds - node_boot_time_seconds" }, + ], + }, + { + id: 6, + type: "timeseries", + title: "CPU basic", + datasource: promDs, + gridPos: { x: 8, y: 4, w: 16, h: 8 }, + interval: "30s", + fieldConfig: { + defaults: { + unit: "percentunit", + custom: { drawStyle: "line", stacking: { mode: "normal" } }, + }, + }, + options: { legend: { showLegend: true, placement: "bottom" } }, + targets: [ + { + refId: "A", + expr: 'sum by (mode) (rate(node_cpu_seconds_total{instance="$node",job="$job"}[$__rate_interval]))', + legendFormat: "{{mode}}", + }, + { refId: "B", expr: "count(node_cpu_seconds_total)", legendFormat: "cores" }, + ], + }, + { + id: 7, + type: "row", + title: "Network", + collapsed: true, + gridPos: { x: 0, y: 12, w: 24, h: 1 }, + panels: [ + { + id: 8, + type: "timeseries", + title: "Traffic", + datasource: promDs, + gridPos: { x: 0, y: 13, w: 12, h: 7 }, + fieldConfig: { defaults: { unit: "bps", custom: { drawStyle: "bars" } } }, + targets: [ + { + refId: "A", + expr: "rate(node_network_receive_bytes_total[$resolution])", + legendFormat: "{{device}}", + interval: "1m", + }, + ], + }, + { + id: 9, + type: "table", + title: "Interfaces", + datasource: promDs, + gridPos: { x: 12, y: 13, w: 12, h: 7 }, + targets: [{ refId: "A", expr: "node_network_up", format: "table", instant: true }], + }, + ], + }, + ], +} + +/** An "export for sharing" file: `__inputs` and `${DS_*}` placeholders instead of real datasources. */ +export const sharedExportDashboard = { + __inputs: [ + { name: "DS_PROMETHEUS", type: "datasource", pluginId: "prometheus" }, + { name: "DS_LOKI", type: "datasource", pluginId: "loki" }, + { name: "DS_CH", type: "datasource", pluginId: "grafana-clickhouse-datasource" }, + ], + title: "API service", + schemaVersion: 38, + time: { from: "now-30s", to: "now" }, + templating: { list: [{ name: "host-name", type: "textbox", query: "web-1" }] }, + panels: [ + { + type: "timeseries", + title: "Requests", + datasource: "${DS_PROMETHEUS}", + gridPos: { x: 0, y: 0, w: 12, h: 8 }, + fieldConfig: { defaults: { unit: "reqps" } }, + targets: [{ refId: "A", expr: 'sum(rate(http_requests_total{host="${host-name}"}[5m]))' }], + }, + { + type: "timeseries", + title: "Error logs", + datasource: { uid: "${DS_LOKI}" }, + gridPos: { x: 12, y: 0, w: 12, h: 8 }, + targets: [{ refId: "A", expr: 'count_over_time({app="api"} |= "error" [5m])' }], + }, + { + type: "logs", + title: "Recent logs", + datasource: { uid: "${DS_LOKI}" }, + gridPos: { x: 0, y: 8, w: 24, h: 6 }, + targets: [{ refId: "A", expr: '{app="api"}' }], + }, + { type: "nodeGraph", title: "Topology", gridPos: { x: 0, y: 14, w: 12, h: 6 } }, + { + type: "table", + title: "Slow spans", + datasource: { type: "grafana-clickhouse-datasource", uid: "${DS_CH}" }, + gridPos: { x: 12, y: 14, w: 12, h: 6 }, + targets: [ + { + refId: "A", + rawSql: "SELECT SpanName, count() AS value FROM traces WHERE OrgId = 'x' AND $__timeFilter(Timestamp) GROUP BY SpanName", + }, + ], + }, + ], +} + +/** The pre-5.0 schema: rows of panels sized by `span`, row heights in pixels. */ +export const legacyRowsDashboard = { + title: "Legacy board", + schemaVersion: 14, + rows: [ + { + title: "Overview", + showTitle: false, + height: "250px", + panels: [ + { + type: "singlestat", + title: "Up", + span: 4, + format: "none", + targets: [{ refId: "A", expr: "up" }], + }, + { + type: "graph", + title: "Load", + span: 8, + bars: false, + lines: true, + stack: true, + yaxes: [{ format: "short" }], + targets: [{ refId: "A", expr: "node_load1" }], + }, + ], + }, + { + title: "Details", + showTitle: true, + collapse: true, + height: 300, + panels: [ + { + type: "graph", + title: "Disk IO", + span: 12, + bars: true, + targets: [{ refId: "A", expr: "rate(node_disk_io_time_seconds_total[5m])" }], + }, + ], + }, + ], +} diff --git a/packages/backend/src/services/dashboards/grafana-dashboard-import.test.ts b/packages/backend/src/services/dashboards/grafana-dashboard-import.test.ts new file mode 100644 index 0000000000..423a474eb1 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-dashboard-import.test.ts @@ -0,0 +1,603 @@ +import { assert, describe, expect, it } from "@effect/vitest" +import { Effect, Option, Array as Arr, Record as Rec, String as Str } from "effect" +import { dataSourcePromql, dataSourceRawSql, dataSourceTransform } from "@maple/widgets/dashboard" +import { convertGrafanaDashboardToPortable, isGrafanaDashboardJson } from "./grafana-dashboard-import" +import { + legacyRowsDashboard, + nodeExporterDashboard, + sharedExportDashboard, +} from "./grafana-dashboard-import.fixtures" + +type Converted = Effect.Success> +type Widget = Converted["dashboard"]["widgets"][number] + +const widgetNamed = (converted: Converted, title: string): Widget => { + const widget = Arr.findFirst( + converted.dashboard.widgets, + (candidate) => candidate.display.title === title, + ) + assert.isTrue(Option.isSome(widget), `no widget titled ${title}`) + return Option.getOrThrow(widget) +} + +/** Every container's widgets stay inside 12 columns and never overlap. */ +const expectValidGrid = (converted: Converted) => { + const byContainer = Arr.groupBy(converted.dashboard.widgets, (widget) => widget.sectionId ?? "root") + for (const widgets of Rec.values(byContainer)) { + for (const [index, a] of widgets.entries()) { + expect(a.layout.x).toBeGreaterThanOrEqual(0) + expect(a.layout.x + a.layout.w).toBeLessThanOrEqual(12) + expect(a.layout.w).toBeGreaterThanOrEqual(a.layout.minW ?? 1) + for (const b of widgets.slice(index + 1)) { + const overlap = + a.layout.x < b.layout.x + b.layout.w && + b.layout.x < a.layout.x + a.layout.w && + a.layout.y < b.layout.y + b.layout.h && + b.layout.y < a.layout.y + a.layout.h + expect(overlap, `${a.display.title} overlaps ${b.display.title}`).toBe(false) + } + } + } +} + +describe("convertGrafanaDashboardToPortable on a Node Exporter style board", () => { + it.effect("keeps the dashboard's name, tags, range and refresh", () => + Effect.gen(function* () { + const { dashboard } = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect(dashboard.name).toBe("Node overview") + expect(dashboard.description).toBe("Host metrics from node_exporter") + expect(dashboard.tags).toEqual(["linux", "node", "grafana-import"]) + expect(dashboard.timeRange).toEqual({ type: "relative", value: "24h" }) + expect(dashboard.refreshIntervalSeconds).toBe(60) + }), + ) + + it.effect("turns rows into sections and keeps panels before the first row on the root canvas", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect( + Arr.map(converted.dashboard.sections ?? [], ({ title, collapsed }) => ({ title, collapsed })), + ).toEqual([ + { title: "Quick CPU / Mem / Disk", collapsed: undefined }, + { title: "Network", collapsed: true }, + ]) + const [quick, network] = converted.dashboard.sections ?? [] + const about = widgetNamed(converted, "About") + expect(about.sectionId).toBeUndefined() + expect(about.layout).toMatchObject({ x: 0, y: 0, w: 12, h: 3 }) + // Coordinates restart at the top of each section. + expect(widgetNamed(converted, "CPU busy")).toMatchObject({ + sectionId: quick?.id, + layout: { x: 0, y: 0, w: 2, h: 2 }, + }) + expect(widgetNamed(converted, "CPU basic")).toMatchObject({ + sectionId: quick?.id, + layout: { x: 4, y: 0, w: 8, h: 4 }, + }) + expect(widgetNamed(converted, "Traffic")).toMatchObject({ + sectionId: network?.id, + tabId: network?.tabs[0]?.id, + layout: { x: 0, y: 0 }, + }) + expect(widgetNamed(converted, "Interfaces").layout).toMatchObject({ x: 6, y: 0, w: 6 }) + expectValidGrid(converted) + }), + ) + + it.effect("pushes a tile grown to its minimum width below the neighbour it would cover", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + // Grafana w: 2 is one Maple column; a stat needs two, which the gauge and CPU basic hold. + expect(widgetNamed(converted, "Uptime").layout).toMatchObject({ x: 3, y: 4, w: 2 }) + expect(widgetNamed(converted, "CPU basic").layout).toMatchObject({ x: 4, y: 0 }) + expectValidGrid(converted) + }), + ) + + it.effect("stores PromQL verbatim with its legend, step and the panel's display type", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + const cpu = widgetNamed(converted, "CPU basic") + expect(cpu.visualization).toBe("chart") + expect(dataSourcePromql(cpu.dataSource)).toEqual({ + query: 'sum by (mode) (rate(node_cpu_seconds_total{instance="$node",job="$job"}[$__rate_interval]))', + legendFormat: "{{mode}}", + minStepSeconds: 30, + displayType: "line", + }) + expect(cpu.display).toMatchObject({ + chartId: "query-builder-line", + stacked: true, + unit: "percent", + }) + // `__auto` is Grafana's default legend, so it is left unset. + const busy = widgetNamed(converted, "CPU busy") + expect(dataSourcePromql(busy.dataSource)?.legendFormat).toBeUndefined() + expect(dataSourcePromql(busy.dataSource)?.displayType).toBe("stat") + expect(dataSourceTransform(busy.dataSource)?.reduceToValue).toEqual({ + field: "value", + aggregate: "first", + }) + }), + ) + + it.effect("skips hidden targets and names the queries it could not keep", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect(dataSourcePromql(widgetNamed(converted, "Uptime").dataSource)?.query).toBe( + "node_time_seconds - node_boot_time_seconds", + ) + expect(converted.warnings).toContain( + 'Panel "CPU basic" has 2 queries; Maple imported A only. Not imported: B: count(node_cpu_seconds_total)', + ) + }), + ) + + it.effect("maps units, thresholds, gauge bounds and bar charts", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect(widgetNamed(converted, "CPU busy").display).toMatchObject({ + unit: "percent_100", + thresholds: [ + { value: 85, color: "#FF9830" }, + { value: 95, color: "#F2495C" }, + ], + }) + expect(widgetNamed(converted, "Root FS used").display).toMatchObject({ + unit: "percent", + gauge: { min: 0, max: 1 }, + thresholds: [{ value: 0.9, color: "#F2495C" }], + }) + expect(widgetNamed(converted, "Uptime").display.unit).toBe("duration_s") + const traffic = widgetNamed(converted, "Traffic") + expect(traffic.display).toMatchObject({ chartId: "query-builder-bar", stacked: false }) + expect(traffic.display.unit).toBeUndefined() + expect(dataSourcePromql(traffic.dataSource)?.minStepSeconds).toBe(60) + expect(converted.warnings).toContain( + 'Panel "Traffic" uses the Grafana unit "bps", which Maple has no match for; it shows plain numbers.', + ) + expect(dataSourcePromql(widgetNamed(converted, "Interfaces").dataSource)?.displayType).toBe( + "table", + ) + }), + ) + + it.effect("converts variables and rewrites interval variable references", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect(converted.dashboard.variables).toEqual([ + { + name: "job", + type: "query", + // `job` is the service name, which OTel metrics carry only as `service.name`. + source: { kind: "facet", facet: "service" }, + defaultValue: "node", + }, + { + name: "node", + label: "Host", + includeAll: true, + type: "query", + source: { + kind: "metric", + metricType: "gauge", + metricNames: ["node_uname_info"], + scope: "metric", + attributeKey: "instance", + }, + }, + { + name: "mountpoint", + type: "custom", + options: [{ value: "/" }, { value: "/home" }, { value: "/var" }], + defaultValue: "/", + }, + ]) + expect(dataSourcePromql(widgetNamed(converted, "Traffic").dataSource)?.query).toBe( + "rate(node_network_receive_bytes_total[$__interval])", + ) + expect(converted.warnings).toEqual( + expect.arrayContaining([ + 'Interval variable "resolution" was not imported; its references now use $__interval.', + 'Variable "node" lists every instance of node_uname_info; the label filters in "node_uname_info{job="$job"}" were not imported.', + ]), + ) + }), + ) + + it.effect("counts panels, conversions and placeholders", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(nodeExporterDashboard) + expect(converted.stats).toEqual({ panels: 7, converted: 7, placeholders: 0 }) + expect(widgetNamed(converted, "About").display.markdown?.content).toBe( + "Fleet **health** at a glance.", + ) + }), + ) +}) + +describe("convertGrafanaDashboardToPortable on other inputs", () => { + it.effect( + "resolves `${DS_*}` inputs of an export for sharing and keeps unsupported panels as notes", + () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(sharedExportDashboard) + expect(dataSourcePromql(widgetNamed(converted, "Requests").dataSource)?.query).toBe( + 'sum(rate(http_requests_total{host="${host_name}"}[5m]))', + ) + expect(widgetNamed(converted, "Requests").display.unit).toBe("requests_per_sec") + const loki = widgetNamed(converted, "Error logs") + expect(loki.visualization).toBe("markdown") + expect(loki.display.markdown?.content).toContain( + 'A: count_over_time({app="api"} |= "error" [5m])', + ) + expect(widgetNamed(converted, "Recent logs").visualization).toBe("markdown") + expect(widgetNamed(converted, "Topology").display.markdown?.content).toContain( + "Panel type: `nodeGraph`", + ) + expect(converted.stats).toEqual({ panels: 5, converted: 2, placeholders: 3 }) + expect(converted.warnings).toEqual( + expect.arrayContaining([ + 'Variable "host-name" was renamed to "host_name"; queries that use it were rewritten.', + 'Panel "Error logs" queries Loki, which Maple cannot run; it was imported as a placeholder.', + 'Logs panel "Recent logs" was imported as a placeholder.', + 'Panel "Topology" uses the "nodeGraph" panel type, which Maple cannot draw; it was imported as a placeholder.', + 'The time range "now-30s" to "now" has no Maple equivalent; the dashboard shows the last 6h.', + ]), + ) + expectValidGrid(converted) + }), + ) + + it.effect("runs a ClickHouse target through the org-scoped raw SQL path", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(sharedExportDashboard) + const slow = widgetNamed(converted, "Slow spans") + expect(slow.visualization).toBe("table") + expect(dataSourceRawSql(slow.dataSource)?.sql).toBe( + "SELECT SpanName, count() AS value FROM traces WHERE (OrgId = 'x' AND $__timeFilter(Timestamp)) AND $__orgFilter GROUP BY SpanName", + ) + }), + ) + + it.effect("scopes a ClickHouse query at its top level and keeps a stat's calculation", () => + Effect.gen(function* () { + const ch = { type: "grafana-clickhouse-datasource", uid: "ch" } + const panel = ( + title: string, + type: string, + rawSql: string, + extra: Record = {}, + ) => ({ + type, + title, + datasource: ch, + gridPos: { x: 0, y: 0, w: 6, h: 4 }, + targets: [{ refId: "A", rawSql }], + ...extra, + }) + const converted = yield* convertGrafanaDashboardToPortable({ + title: "ClickHouse", + schemaVersion: 39, + panels: [ + panel( + "Nested", + "table", + "SELECT n FROM (SELECT count() AS n FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) LIMIT 5) WHERE n > 0", + ), + panel( + "Literal", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND Body LIKE '%limit%' AND $__timeFilter(Timestamp)", + ), + panel( + "Subquery", + "table", + "SELECT count() FROM (SELECT * FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp))", + ), + panel( + "Either", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'legacy' OR ServiceName = 'api' AND $__timeFilter(Timestamp);", + ), + panel( + "Commented", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) -- scoped", + ), + panel( + "Grouped", + "table", + "SELECT SpanName, count() AS value FROM traces WHERE OrgId = 'x' AND $__timeFilter(Timestamp) -- scoped\nGROUP BY SpanName", + ), + panel( + "Except column", + "table", + "SELECT * EXCEPT (Body) FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp)", + ), + panel( + "Having", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) HAVING count() > 0", + ), + panel( + "Block comment", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) /* LIMIT */", + ), + panel( + "Nested comment", + "table", + "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) /* outer /* inner */ LIMIT */", + ), + panel( + "Union", + "table", + "SELECT count() FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) UNION ALL SELECT count() FROM traces WHERE OrgId = 'x' AND $__timeFilter(Timestamp)", + ), + panel( + "Mean", + "stat", + "SELECT toStartOfMinute(Timestamp) AS t, count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp) GROUP BY t", + { options: { reduceOptions: { calcs: ["mean"] } } }, + ), + ], + }) + // A subquery's rows may carry no OrgId, so any subquery read without $__orgFilter is a placeholder. + expect(dataSourceRawSql(widgetNamed(converted, "Nested").dataSource)).toBeNull() + expect(dataSourceRawSql(widgetNamed(converted, "Literal").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'x' AND Body LIKE '%limit%' AND $__timeFilter(Timestamp)) AND $__orgFilter", + ) + expect(dataSourceRawSql(widgetNamed(converted, "Subquery").dataSource)).toBeNull() + // Each SELECT of a UNION needs its own scope, so the importer leaves it to the author. + expect(dataSourceRawSql(widgetNamed(converted, "Union").dataSource)).toBeNull() + expect(dataSourceRawSql(widgetNamed(converted, "Nested comment").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'x' AND $__timeFilter(Timestamp) /* outer /* inner */ LIMIT */) AND $__orgFilter", + ) + expect(dataSourceRawSql(widgetNamed(converted, "Having").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'x' AND $__timeFilter(Timestamp)) AND $__orgFilter HAVING count() > 0", + ) + expect(dataSourceRawSql(widgetNamed(converted, "Block comment").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'x' AND $__timeFilter(Timestamp) /* LIMIT */) AND $__orgFilter", + ) + expect(dataSourceRawSql(widgetNamed(converted, "Except column").dataSource)?.sql).toBe( + "SELECT * EXCEPT (Body) FROM logs WHERE (OrgId = 'x' AND $__timeFilter(Timestamp)) AND $__orgFilter", + ) + // The OR is grouped, so the org filter binds every branch; the semicolon no longer ends the statement early. + expect(dataSourceRawSql(widgetNamed(converted, "Either").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'legacy' OR ServiceName = 'api' AND $__timeFilter(Timestamp)) AND $__orgFilter", + ) + // A trailing line comment would swallow the closing parenthesis; it gets its own line. + expect(dataSourceRawSql(widgetNamed(converted, "Commented").dataSource)?.sql).toBe( + "SELECT count() AS value FROM logs WHERE (OrgId = 'x' AND $__timeFilter(Timestamp) -- scoped\n) AND $__orgFilter", + ) + expect(dataSourceRawSql(widgetNamed(converted, "Grouped").dataSource)?.sql).toBe( + "SELECT SpanName, count() AS value FROM traces WHERE (OrgId = 'x' AND $__timeFilter(Timestamp) -- scoped\n) AND $__orgFilter GROUP BY SpanName", + ) + expect(converted.warnings).toEqual( + expect.arrayContaining([ + expect.stringContaining("reads a subquery; add $__orgFilter inside it"), + ]), + ) + expect(widgetNamed(converted, "Mean").dataSource).toMatchObject({ + transform: { reduceToValue: { field: "value", aggregate: "avg" } }, + }) + }), + ) + + it.effect("maps today so far, and warns where Maple draws a panel differently", () => + Effect.gen(function* () { + const ch = { type: "grafana-clickhouse-datasource", uid: "ch" } + const converted = yield* convertGrafanaDashboardToPortable({ + title: "Differences", + schemaVersion: 39, + time: { from: "now/d", to: "now" }, + panels: [ + { + type: "timeseries", + title: "Share", + datasource: { type: "prometheus", uid: "prom" }, + gridPos: { x: 0, y: 0, w: 12, h: 6 }, + fieldConfig: { defaults: { custom: { stacking: { mode: "percent" } } } }, + targets: [{ refId: "A", expr: "sum by (job) (up)" }], + }, + { + type: "stat", + title: "Default", + datasource: ch, + gridPos: { x: 0, y: 6, w: 6, h: 4 }, + targets: [ + { + refId: "A", + rawSql: "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp)", + }, + ], + }, + { + type: "stat", + title: "Spread", + datasource: ch, + gridPos: { x: 6, y: 6, w: 6, h: 4 }, + options: { reduceOptions: { calcs: ["range"] } }, + targets: [ + { + refId: "A", + rawSql: "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp)", + }, + ], + }, + { + type: "stat", + title: "Latest", + datasource: ch, + gridPos: { x: 12, y: 0, w: 6, h: 4 }, + options: { reduceOptions: { calcs: ["lastNotNull"] } }, + targets: [ + { + refId: "A", + rawSql: "SELECT count() AS value FROM logs WHERE OrgId = 'x' AND $__timeFilter(Timestamp)", + }, + ], + }, + ], + }) + expect(converted.dashboard.timeRange).toEqual({ type: "relative", value: "today" }) + expect(converted.warnings).toEqual( + expect.arrayContaining([ + expect.stringContaining('Panel "Share" stacked its series as percentages'), + expect.stringContaining(`Panel "Latest" reads the query's first row`), + // No calc and an unsupported calc fall back to the first row too, and say so. + expect.stringContaining(`Panel "Default" reads the query's first row`), + expect.stringContaining( + `Panel "Spread" reduces with "range", which Maple does not have; it shows the value of the query's first row`, + ), + expect.stringContaining(`Panel "Spread" reads the query's first row`), + ]), + ) + }), + ) + + it.effect("unwraps the API's `{ dashboard, meta }` envelope", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable({ + dashboard: nodeExporterDashboard, + meta: { slug: "node-overview" }, + }) + expect(converted.dashboard.name).toBe("Node overview") + expect(converted.stats.panels).toBe(7) + }), + ) + + it.effect("lays out the old `rows` schema by span, with titled rows as sections", () => + Effect.gen(function* () { + const converted = yield* convertGrafanaDashboardToPortable(legacyRowsDashboard) + expect( + Arr.map(converted.dashboard.sections ?? [], ({ title, collapsed }) => ({ title, collapsed })), + ).toEqual([{ title: "Details", collapsed: true }]) + expect(widgetNamed(converted, "Up")).toMatchObject({ + visualization: "stat", + layout: { x: 0, y: 0, w: 4, h: 4 }, + }) + expect(widgetNamed(converted, "Load")).toMatchObject({ + layout: { x: 4, y: 0, w: 8, h: 4 }, + display: { stacked: true, unit: "short" }, + }) + expect(widgetNamed(converted, "Disk IO")).toMatchObject({ + sectionId: converted.dashboard.sections?.[0]?.id, + layout: { x: 0, y: 0, w: 12, h: 5 }, + display: { chartId: "query-builder-bar" }, + }) + expectValidGrid(converted) + }), + ) + + it.effect("refuses JSON that is not a Grafana dashboard", () => + Effect.gen(function* () { + const error = yield* Effect.flip( + convertGrafanaDashboardToPortable({ kind: "Dashboard", spec: {} }), + ) + expect(error._tag).toBe("@maple/http/errors/DashboardValidationError") + const empty = yield* Effect.flip( + convertGrafanaDashboardToPortable({ panels: [], schemaVersion: 39 }), + ) + expect(empty.details).toEqual(["The dashboard has no panels to import."]) + }), + ) +}) + +describe("isGrafanaDashboardJson", () => { + it("recognises a bare board, the API envelope and the old schema, not Perses or Maple JSON", () => { + expect(isGrafanaDashboardJson(nodeExporterDashboard)).toBe(true) + expect(isGrafanaDashboardJson({ dashboard: nodeExporterDashboard, meta: {} })).toBe(true) + expect(isGrafanaDashboardJson(legacyRowsDashboard)).toBe(true) + expect(isGrafanaDashboardJson({ kind: "Dashboard", spec: { panels: {} } })).toBe(false) + expect(isGrafanaDashboardJson({ name: "Maple", widgets: [], timeRange: {} })).toBe(false) + expect(isGrafanaDashboardJson({ panels: [] })).toBe(false) + }) +}) + +describe("review regressions", () => { + const prom = { type: "prometheus", uid: "p" } + const panel = (extra: Record) => ({ + id: 1, + title: "Panel", + gridPos: { x: 0, y: 0, w: 12, h: 8 }, + datasource: prom, + targets: [{ refId: "A", expr: "up", datasource: prom }], + ...extra, + }) + const board = (panels: ReadonlyArray, variables: ReadonlyArray = []) => ({ + title: "Board", + schemaVersion: 39, + panels, + templating: { list: variables }, + }) + + it.effect("keeps Grafana's stat calculation and warns on one Maple lacks", () => + Effect.gen(function* () { + const { dashboard, warnings } = yield* convertGrafanaDashboardToPortable( + board([ + panel({ type: "stat", options: { reduceOptions: { calcs: ["max"] } } }), + panel({ id: 2, type: "stat", options: { reduceOptions: { calcs: ["range"] } } }), + ]), + ) + const transforms = Arr.map( + dashboard.widgets, + (w) => dataSourceTransform(w.dataSource)?.reduceToValue?.aggregate, + ) + expect(transforms).toEqual(["max", "first"]) + expect(Arr.some(warnings, Str.includes('"range"'))).toBe(true) + }), + ) + + it.effect("imports a PromQL heatmap as a placeholder", () => + Effect.gen(function* () { + const { dashboard, warnings } = yield* convertGrafanaDashboardToPortable( + board([panel({ type: "heatmap" })]), + ) + expect(dataSourcePromql(dashboard.widgets[0]?.dataSource)).toBeNull() + expect(Arr.some(warnings, Str.includes("buckets over time"))).toBe(true) + }), + ) + + it.effect("never lets one rename capture another variable's references", () => + Effect.gen(function* () { + const query = 'up{a="${host-name}", b="$host_name"}' + const { dashboard } = yield* convertGrafanaDashboardToPortable( + board( + [panel({ type: "timeseries", targets: [{ refId: "A", expr: query, datasource: prom }] })], + [ + { name: "host-name", type: "textbox", query: "web-1" }, + { name: "host_name", type: "textbox", query: "web-2" }, + ], + ), + ) + const names = Arr.map(dashboard.variables ?? [], (v) => v.name) + expect(names).toEqual(["host_name_2", "host_name"]) + expect(dataSourcePromql(dashboard.widgets[0]?.dataSource)?.query).toBe( + 'up{a="${host_name_2}", b="$host_name"}', + ) + }), + ) +}) + +describe("assumed PromQL", () => { + it.effect("says once that queries without a datasource type were read as PromQL", () => + Effect.gen(function* () { + const bare = (id: number) => ({ + id, + type: "timeseries", + title: `P${id}`, + gridPos: { x: 0, y: id * 8, w: 12, h: 8 }, + datasource: { uid: "lo0" }, + targets: [{ refId: "A", expr: "up", datasource: { uid: "lo0" } }], + }) + const { warnings } = yield* convertGrafanaDashboardToPortable({ + title: "Bare", + schemaVersion: 39, + panels: [bare(1), bare(2)], + }) + expect(Arr.filter(warnings, Str.includes("were read as PromQL"))).toHaveLength(1) + }), + ) +}) diff --git a/packages/backend/src/services/dashboards/grafana-dashboard-import.ts b/packages/backend/src/services/dashboards/grafana-dashboard-import.ts new file mode 100644 index 0000000000..135a98db97 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-dashboard-import.ts @@ -0,0 +1,261 @@ +// Grafana dashboard JSON to a Maple portable dashboard, with warnings for what did not carry over. +import { + DashboardValidationError, + type DashboardRefreshIntervalSeconds, + PortableDashboardDocument, + defaultWidgetLayout, +} from "@maple/domain/http" +import { MAX_QUERY_RANGE_SECONDS, validateRelativeRange } from "@maple/query-engine" +import { Effect, Schema, Array as Arr, Order, String as Str } from "effect" +import { + type DashboardWidget, + type UnknownRecord, + asArray, + asRecord, + asString, + uniqueWidgetId, +} from "./dashboard-import-shared" +import { convertGridPos, readGridPos, resolveOverlaps } from "./grafana-import-layout" +import { convertGrafanaPanel, intervalSeconds, type PanelContext } from "./grafana-import-panels" +import { convertGrafanaVariables } from "./grafana-import-variables" +import { panelsFromLegacyRows } from "./grafana-import-legacy" + +export interface GrafanaImportStats { + readonly panels: number + readonly converted: number + readonly placeholders: number +} + +export interface GrafanaImportConversion { + readonly dashboard: PortableDashboardDocument + readonly warnings: readonly string[] + readonly stats: GrafanaImportStats +} + +const decodePortableDashboard = Schema.decodeUnknownSync(PortableDashboardDocument) + +/** The dashboard itself: bare, inside the API's `{ dashboard, meta }` envelope, or an export for sharing. */ +export function unwrapGrafanaDashboard(input: unknown): UnknownRecord | null { + const root = asRecord(input) + const inner = asRecord(root?.dashboard) + const dashboard = inner ?? root + if (dashboard === null) return null + const hasPanels = Arr.isArray(dashboard.panels) || Arr.isArray(dashboard.rows) + return hasPanels ? dashboard : null +} + +/** True for JSON that looks like a Grafana dashboard rather than a Maple or Perses one. */ +export const isGrafanaDashboardJson = (input: unknown): boolean => { + const root = asRecord(input) + if (root === null) return false + if (asRecord(root.dashboard) !== null) return unwrapGrafanaDashboard(input) !== null + return unwrapGrafanaDashboard(input) !== null && root.schemaVersion !== undefined +} + +/** `__inputs` of an export for sharing: `DS_PROMETHEUS` to `prometheus`. */ +function inputTypes(root: UnknownRecord, dashboard: UnknownRecord): ReadonlyMap { + const inputs = [...asArray(root.__inputs), ...asArray(dashboard.__inputs)] + return new Map( + Arr.flatMap(inputs, (input) => { + const record = asRecord(input) + const name = asString(record?.name) + const plugin = asString(record?.pluginId) + return name === undefined || plugin === undefined ? [] : [[name, plugin] as const] + }), + ) +} + +const DEFAULT_RANGE = "6h" + +/** `now-6h` to `now` as Maple's `6h`; Grafana's months are `M`, Maple's `mo`. */ +function timeRange(dashboard: UnknownRecord, warnings: string[]) { + const time = asRecord(dashboard.time) + const from = asString(time?.from) + const to = asString(time?.to) ?? "now" + // "Today" (to the end of the day) and "Today so far" (to now) both start at the day boundary. + if (from === "now/d" && (to === "now/d" || to === "now")) + return { type: "relative" as const, value: "today" } + const match = /^now-(\d+)([mhdwM])$/u.exec(from ?? "") + const value = match === null ? undefined : `${match[1]}${match[2] === "M" ? "mo" : match[2]}` + if (value !== undefined && to === "now" && validateRelativeRange(value, MAX_QUERY_RANGE_SECONDS).ok) { + return { type: "relative" as const, value } + } + if (from !== undefined) { + warnings.push( + `The time range "${from}" to "${to}" has no Maple equivalent; the dashboard shows the last ${DEFAULT_RANGE}.`, + ) + } + return { type: "relative" as const, value: DEFAULT_RANGE } +} + +const REFRESH_STEPS: ReadonlyArray = [5, 10, 30, 60, 300, 900] + +/** The allowed refresh interval nearest to Grafana's, or none when it was off. */ +function refreshInterval(dashboard: UnknownRecord) { + const seconds = intervalSeconds(dashboard.refresh) + if (seconds === undefined) return undefined + return Arr.reduce(REFRESH_STEPS, 900 satisfies DashboardRefreshIntervalSeconds, (best, step) => + Math.abs(step - seconds) < Math.abs(best - seconds) ? step : best, + ) +} + +const tags = (dashboard: UnknownRecord) => + Arr.dedupe([ + ...Arr.flatMap(asArray(dashboard.tags), (tag) => Arr.fromNullishOr(asString(tag))), + "grafana-import", + ]) + +interface Section { + readonly id: string + readonly title: string + readonly collapsed?: boolean + readonly tabs: ReadonlyArray<{ readonly id: string; readonly title: string }> +} + +/** The container a panel lands in: the root canvas, or a section starting at Grafana row `originY`. */ +interface Container { + readonly sectionId: string | undefined + readonly originY: number +} + +interface PlacedPanel extends Container { + readonly panel: UnknownRecord + readonly pos: ReturnType +} + +const MAX_SECTIONS = 50 + +/** Panels in grid order with positions, a missing `gridPos` stacked below the ones before it. */ +function positioned(panels: ReadonlyArray) { + let bottom = 0 + const out = Arr.flatMap(panels, (item) => { + const panel = asRecord(item) + if (panel === null) return [] + const pos = readGridPos(panel, bottom) + bottom = Math.max(bottom, pos.y + pos.h) + return [{ panel, pos }] + }) + return Arr.sort( + out, + Order.combine( + Order.mapInput(Order.Number, (entry: (typeof out)[number]) => entry.pos.y), + Order.mapInput(Order.Number, (entry: (typeof out)[number]) => entry.pos.x), + ), + ) +} + +/** Rows become sections; a panel belongs to the row above it, a collapsed row carries its own. */ +function placePanels(panels: ReadonlyArray, warnings: string[]) { + const sections: Section[] = [] + const sectionIds = new Set() + const placed: PlacedPanel[] = [] + let current: Container = { sectionId: undefined, originY: 0 } + for (const { panel, pos } of positioned(panels)) { + if (panel.type !== "row") { + placed.push({ panel, pos, ...current }) + continue + } + const title = Str.trim(asString(panel.title) ?? "") || "Row" + if (sections.length >= MAX_SECTIONS) { + warnings.push( + `Row "${title}" was merged into the row above it; Maple holds ${MAX_SECTIONS} sections at most.`, + ) + } else { + const id = uniqueWidgetId("grafana-row", title, sectionIds) + sections.push({ + id, + title, + ...(panel.collapsed === true ? { collapsed: true } : undefined), + tabs: [{ id: `${id}-tab`, title }], + }) + current = { sectionId: id, originY: pos.y + 1 } + } + if (asString(panel.repeat) !== undefined) { + warnings.push( + `Row "${title}" repeats per value of $${asString(panel.repeat)} in Grafana; Maple shows it once.`, + ) + } + for (const nested of positioned(asArray(panel.panels))) placed.push({ ...nested, ...current }) + } + return { sections, placed } +} + +const invalid = (detail: string) => + new DashboardValidationError({ message: "Invalid Grafana dashboard", details: [detail] }) + +/** Widgets per container, laid out on Maple's grid with overlaps pushed down. */ +function convertPanels(placed: ReadonlyArray, context: PanelContext) { + const converted = Arr.map(placed, (entry) => { + const result = convertGrafanaPanel(entry.panel, { x: 0, y: 0, w: 1, h: 1 }, context) + const { minW, minH } = defaultWidgetLayout(result.widget.visualization) + const { layout, grown } = convertGridPos(entry.pos, entry.originY, { minW, minH }) + return { ...result, sectionId: entry.sectionId, layout, grown } + }) + const widgets: DashboardWidget[] = [] + for (const sectionId of Arr.dedupe(Arr.map(converted, (entry) => entry.sectionId))) { + const inSection = Arr.filter(converted, (entry) => entry.sectionId === sectionId) + const layouts = resolveOverlaps(inSection) + Arr.forEach(inSection, (entry, index) => { + widgets.push({ + ...entry.widget, + layout: layouts[index] ?? entry.layout, + ...(sectionId === undefined ? undefined : { sectionId, tabId: `${sectionId}-tab` }), + }) + }) + } + const placeholders = Arr.filter(converted, (entry) => entry.placeholder).length + return { + widgets, + stats: { panels: converted.length, converted: converted.length - placeholders, placeholders }, + } +} + +// Returns the validation error rather than failing; unexpected throws are caught by the caller. +function convertSync(input: unknown): GrafanaImportConversion | DashboardValidationError { + const dashboard = unwrapGrafanaDashboard(input) + if (dashboard === null) return invalid("Expected a Grafana dashboard with a panels or rows list.") + const warnings: string[] = [] + const variables = convertGrafanaVariables( + dashboard.templating, + inputTypes(asRecord(input) ?? {}, dashboard), + warnings, + ) + const legacy = !Arr.isArray(dashboard.panels) && Arr.isArray(dashboard.rows) + const { sections, placed } = placePanels( + legacy ? panelsFromLegacyRows(dashboard.rows) : asArray(dashboard.panels), + warnings, + ) + if (placed.length === 0) return invalid("The dashboard has no panels to import.") + const { widgets, stats } = convertPanels(placed, { variables, widgetIds: new Set(), warnings }) + const description = asString(dashboard.description) + const refresh = refreshInterval(dashboard) + return { + dashboard: decodePortableDashboard({ + name: Str.trim(asString(dashboard.title) ?? "") || "Imported Grafana dashboard", + ...(description === undefined ? undefined : { description }), + tags: tags(dashboard), + timeRange: timeRange(dashboard, warnings), + ...(refresh === undefined ? undefined : { refreshIntervalSeconds: refresh }), + ...(variables.variables.length > 0 ? { variables: variables.variables } : undefined), + ...(sections.length > 0 ? { sections } : undefined), + widgets, + }), + warnings, + stats, + } +} + +export const convertGrafanaDashboardToPortable = Effect.fn("GrafanaDashboardImport.convert")(function* ( + input: unknown, +) { + const result = yield* Effect.try({ + try: () => convertSync(input), + catch: (error) => + new DashboardValidationError({ + message: "Invalid Grafana dashboard", + details: [error instanceof Error ? error.message : String(error)], + }), + }) + if (Schema.is(DashboardValidationError)(result)) return yield* result + return result +}) diff --git a/packages/backend/src/services/dashboards/grafana-import-display.ts b/packages/backend/src/services/dashboards/grafana-import-display.ts new file mode 100644 index 0000000000..2bac62a501 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-import-display.ts @@ -0,0 +1,176 @@ +// Grafana field config (unit, thresholds, min/max, legend) to Maple widget display. Pure. +import { Array as Arr, String as Str } from "effect" +import { asArray, asFiniteNumber, asRecord, asString, type UnknownRecord } from "./dashboard-import-shared" + +/** The Maple chart a Grafana panel lands on; `line` and `bar` are both `visualization: "chart"`. */ +export type GrafanaTarget = "line" | "bar" | "stat" | "gauge" | "table" | "pie" | "heatmap" | "histogram" + +const UNITS: ReadonlyMap = new Map([ + ["s", { unit: "duration_s" }], + ["ms", { unit: "duration_ms" }], + ["µs", { unit: "duration_us" }], + ["us", { unit: "duration_us" }], + ["ns", { unit: "duration_ns" }], + ["bytes", { unit: "bytes" }], + ["decbytes", { unit: "bytes" }], + // Grafana's `percent` is already 0 to 100; its `percentunit` is the 0 to 1 fraction. + ["percent", { unit: "percent_100" }], + ["percentunit", { unit: "percent" }], + ["reqps", { unit: "requests_per_sec" }], + ["ops", { unit: "short", suffix: " ops/s" }], + ["short", { unit: "short" }], + ["none", { unit: "none" }], +]) + +// Grafana's named palette, base shades. `dark-`, `light-` and similar prefixes map to the base. +const NAMED_COLORS: ReadonlyMap = new Map([ + ["green", "#73BF69"], + ["red", "#F2495C"], + ["yellow", "#FADE2A"], + ["orange", "#FF9830"], + ["blue", "#5794F2"], + ["purple", "#B877D9"], + ["text", "#CCCCDC"], +]) + +function grafanaColor(color: string): string { + const base = Str.replace(/^(super-light|semi-dark|light|dark)-/u, "")(color) + return NAMED_COLORS.get(base) ?? color +} + +function fieldDefaults(panel: UnknownRecord): UnknownRecord | null { + return asRecord(asRecord(panel.fieldConfig)?.defaults) +} + +/** The display unit (and suffix, for units Maple spells differently), or a warning. */ +function unitDisplay(panel: UnknownRecord, title: string, warnings: string[]): UnknownRecord { + // Field config first; the old graph and singlestat panels kept it on `yaxes[0].format` / `format`. + const unit = + asString(fieldDefaults(panel)?.unit) ?? + asString(asRecord(asArray(panel.yaxes)[0])?.format) ?? + asString(panel.format) + if (unit === undefined) return {} + const known = UNITS.get(unit) + if (known === undefined) { + warnings.push( + `Panel "${title}" uses the Grafana unit "${unit}", which Maple has no match for; it shows plain numbers.`, + ) + return {} + } + return { unit: known.unit, ...(known.suffix === undefined ? undefined : { suffix: known.suffix }) } +} + +/** Absolute threshold steps; the base step (value null) is the default colour, so it is dropped. */ +function thresholds(panel: UnknownRecord, title: string, warnings: string[]) { + const config = asRecord(fieldDefaults(panel)?.thresholds) + if (config === null) return undefined + if (config.mode === "percentage") { + warnings.push( + `Panel "${title}" has percentage thresholds, which Maple does not support; they were dropped.`, + ) + return undefined + } + const steps = Arr.flatMap(asArray(config.steps), (step) => { + const record = asRecord(step) + const value = asFiniteNumber(record?.value) + const color = asString(record?.color) + return value === undefined || color === undefined ? [] : [{ value, color: grafanaColor(color) }] + }) + return steps.length > 0 ? steps : undefined +} + +/** `line` or `bar`, and whether series stack, from the timeseries or old graph panel options. */ +export function chartStyle(panel: UnknownRecord): { + readonly target: "line" | "bar" + readonly stacked: boolean + /** Grafana normalized the stack to 100%, which Maple does not draw. */ + readonly percent: boolean +} { + if (panel.type === "graph") { + return { + target: panel.bars === true && panel.lines !== true ? "bar" : "line", + stacked: panel.stack === true, + percent: panel.stack === true && panel.percentage === true, + } + } + const custom = asRecord(fieldDefaults(panel)?.custom) + const stacking = asString(asRecord(custom?.stacking)?.mode) + return { + target: custom?.drawStyle === "bars" ? "bar" : "line", + stacked: stacking === "normal" || stacking === "percent", + percent: stacking === "percent", + } +} + +function legend(panel: UnknownRecord): "visible" | "hidden" | "right" { + const options = asRecord(asRecord(panel.options)?.legend) ?? asRecord(panel.legend) + if (options?.showLegend === false || options?.show === false || options?.displayMode === "hidden") + return "hidden" + return options?.placement === "right" || options?.rightSide === true ? "right" : "visible" +} + +/** The widget's `display`: title, unit, thresholds and the chart options the target draws. */ +export function grafanaDisplay(args: { + panel: UnknownRecord + target: GrafanaTarget + title: string + description: string | undefined + warnings: string[] +}): UnknownRecord { + const { panel, target, title, warnings } = args + const defaults = fieldDefaults(panel) + const min = asFiniteNumber(defaults?.min) + const max = asFiniteNumber(defaults?.max) + const steps = target === "table" || target === "pie" ? undefined : thresholds(panel, title, warnings) + const base: UnknownRecord = { + title, + ...(args.description === undefined ? undefined : { description: args.description }), + ...unitDisplay(panel, title, warnings), + ...(steps === undefined ? undefined : { thresholds: steps }), + } + switch (target) { + case "line": + case "bar": { + const { stacked, percent } = chartStyle(panel) + if (percent) { + warnings.push( + `Panel "${title}" stacked its series as percentages of the total; Maple stacks the raw values.`, + ) + } + const custom = asRecord(defaults?.custom) + return { + ...base, + chartId: target === "bar" ? "query-builder-bar" : "query-builder-line", + chartPresentation: { legend: legend(panel), seriesStats: target === "line" && !stacked }, + stacked, + curveType: custom?.lineInterpolation === "smooth" ? "monotone" : "linear", + ...(min === undefined && max === undefined + ? undefined + : { + yAxis: { + ...(min === undefined ? undefined : { min }), + ...(max === undefined ? undefined : { max }), + }, + }), + } + } + case "gauge": + return { + ...base, + gauge: { + ...(min === undefined ? undefined : { min }), + ...(max === undefined ? undefined : { max }), + ...(panel.type === "bargauge" ? { style: "bar" } : undefined), + }, + } + case "pie": + return { ...base, chartId: "query-builder-pie" } + case "heatmap": + return { ...base, chartId: "query-builder-heatmap" } + case "histogram": + return { ...base, chartId: "query-builder-histogram" } + case "stat": + case "table": + return base + } +} diff --git a/packages/backend/src/services/dashboards/grafana-import-layout.ts b/packages/backend/src/services/dashboards/grafana-import-layout.ts new file mode 100644 index 0000000000..93581ddd70 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-import-layout.ts @@ -0,0 +1,94 @@ +// Grafana grid (24 columns, 30px rows) to Maple's (12 columns, 60px rows). Pure. +import { DASHBOARD_GRID_COLS } from "@maple/domain/http" +import { Array as Arr, Option, Order } from "effect" +import { asFiniteNumber, asRecord, type DashboardWidget } from "./dashboard-import-shared" + +export interface GrafanaGridPos { + readonly x: number + readonly y: number + readonly w: number + readonly h: number +} + +type Layout = DashboardWidget["layout"] + +/** Grafana's own default for a panel saved without a `gridPos`. */ +const DEFAULT_GRID_POS = { x: 0, w: 12, h: 8 } as const + +/** A panel's `gridPos`, defaulted like Grafana does; `fallbackY` places a panel that has none. */ +export function readGridPos(panel: unknown, fallbackY: number): GrafanaGridPos { + const pos = asRecord(asRecord(panel)?.gridPos) + return { + x: Math.max(0, asFiniteNumber(pos?.x) ?? DEFAULT_GRID_POS.x), + y: Math.max(0, asFiniteNumber(pos?.y) ?? fallbackY), + w: Math.max(1, asFiniteNumber(pos?.w) ?? DEFAULT_GRID_POS.w), + h: Math.max(1, asFiniteNumber(pos?.h) ?? DEFAULT_GRID_POS.h), + } +} + +const half = (edge: number) => Math.round(edge / 2) + +/** + * Converts by edges, so two Grafana panels that share an edge still share one: + * neighbours never overlap. `originY` is the Grafana row the container starts at. + */ +export function convertGridPos( + pos: GrafanaGridPos, + originY: number, + minimum: { readonly minW: number; readonly minH: number }, +): { readonly layout: Layout; readonly grown: boolean } { + const left = Math.min(DASHBOARD_GRID_COLS - 1, half(Math.min(pos.x, 24))) + const right = Math.min(DASHBOARD_GRID_COLS, half(Math.min(pos.x + pos.w, 24))) + const top = half(Math.max(0, pos.y - originY)) + const bottom = half(Math.max(0, pos.y + pos.h - originY)) + const w = Math.min(DASHBOARD_GRID_COLS, Math.max(minimum.minW, right - left, 1)) + const h = Math.max(minimum.minH, bottom - top, 1) + return { + layout: { x: Math.min(left, DASHBOARD_GRID_COLS - w), y: top, w, h, ...minimum }, + grown: w !== right - left || h !== bottom - top, + } +} + +const overlaps = (a: Layout, b: Layout) => + a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h + +interface Tile { + readonly layout: Layout + readonly grown: boolean + readonly index: number +} + +// Tiles kept at their converted size claim their place first, top to bottom. +const placementOrder = Order.combine( + Order.mapInput(Order.Boolean, (tile: Tile) => tile.grown), + Order.combine( + Order.mapInput(Order.Number, (tile: Tile) => tile.layout.y), + Order.mapInput(Order.Number, (tile: Tile) => tile.layout.x), + ), +) + +/** + * Pushes a tile down below anything it overlaps. Only a tile grown to its panel type's + * minimum can overlap after `convertGridPos`, so those move and their neighbours stay put. + */ +export function resolveOverlaps( + tiles: ReadonlyArray<{ readonly layout: Layout; readonly grown: boolean }>, +): ReadonlyArray { + const order = Arr.sort( + Arr.map(tiles, (tile, index) => ({ ...tile, index })), + placementOrder, + ) + const placed: Layout[] = [] + const out: Layout[] = Arr.map(tiles, (tile) => tile.layout) + for (const { layout, index } of order) { + let current = layout + let blocker = Arr.findFirst(placed, (other) => overlaps(current, other)) + while (Option.isSome(blocker)) { + current = { ...current, y: blocker.value.y + blocker.value.h } + blocker = Arr.findFirst(placed, (other) => overlaps(current, other)) + } + placed.push(current) + out[index] = current + } + return out +} diff --git a/packages/backend/src/services/dashboards/grafana-import-legacy.ts b/packages/backend/src/services/dashboards/grafana-import-legacy.ts new file mode 100644 index 0000000000..0b18e8004f --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-import-legacy.ts @@ -0,0 +1,55 @@ +// Grafana's pre-5.0 `rows[].panels` schema (12-unit `span`, pixel row heights) as modern panels. Pure. +import { Array as Arr, String as Str } from "effect" +import { asArray, asFiniteNumber, asRecord, asString, type UnknownRecord } from "./dashboard-import-shared" + +const DEFAULT_ROW_HEIGHT_PX = 250 + +/** A row height of `250px`, `"250"` or `250` in Grafana's 30px grid units. */ +function rowUnits(height: unknown): number { + const px = asFiniteNumber(height) ?? Number(Str.replace(/px$/u, "")(asString(height) ?? "")) + return Math.max(2, Math.round((Number.isFinite(px) && px > 0 ? px : DEFAULT_ROW_HEIGHT_PX) / 30)) +} + +/** + * Each old row becomes a modern row panel (when it shows a title) followed by its panels, + * left to right by `span`, wrapping at 24 columns. A collapsed row keeps its panels nested. + */ +export function panelsFromLegacyRows(rows: unknown): ReadonlyArray { + const out: UnknownRecord[] = [] + let y = 0 + for (const item of asArray(rows)) { + const row = asRecord(item) + if (row === null) continue + const title = asString(row.title) + const titled = title !== undefined && row.showTitle !== false + const collapsed = row.collapse === true + const h = rowUnits(row.height) + const rowPanel: UnknownRecord | undefined = titled + ? { type: "row", title, collapsed, gridPos: { x: 0, y, w: 24, h: 1 } } + : undefined + if (rowPanel !== undefined) y += 1 + const panels = Arr.flatMap(asArray(row.panels), (panel) => Arr.fromNullishOr(asRecord(panel))) + let x = 0 + const placed = Arr.map(panels, (panel) => { + const w = Math.min( + 24, + Math.max(1, Math.round((asFiniteNumber(panel.span) ?? 12 / Math.max(1, panels.length)) * 2)), + ) + if (x + w > 24) { + x = 0 + y += h + } + const gridPos = { x, y, w, h } + x += w + return { ...panel, gridPos } + }) + y += panels.length > 0 ? h : 0 + if (rowPanel !== undefined && collapsed) { + out.push({ ...rowPanel, panels: placed }) + } else { + if (rowPanel !== undefined) out.push(rowPanel) + out.push(...placed) + } + } + return out +} diff --git a/packages/backend/src/services/dashboards/grafana-import-panels.ts b/packages/backend/src/services/dashboards/grafana-import-panels.ts new file mode 100644 index 0000000000..7165b9a025 --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-import-panels.ts @@ -0,0 +1,344 @@ +// One Grafana panel to one Maple widget. Pure. +import { type RawSqlDisplayType, type WidgetVisualization, widgetTypeByGrafanaType } from "@maple/domain/http" +import { makePromqlDataSource } from "@maple/widgets/dashboard" +import { Array as Arr, String as Str } from "effect" +import { + type DashboardWidget, + type UnknownRecord, + asArray, + asRecord, + asString, + markdownWidget, + normalizeClickHouseSql, + placeholderWidget, + rawSqlDataSource, + scalarTransform, + uniqueWidgetId, +} from "./dashboard-import-shared" +import { chartStyle, type GrafanaTarget, grafanaDisplay } from "./grafana-import-display" +import { + datasourceType, + type GrafanaVariableConversion, + rewriteVariableRefs, +} from "./grafana-import-variables" + +export interface PanelContext { + readonly variables: GrafanaVariableConversion + readonly widgetIds: Set + readonly warnings: string[] +} + +export interface ConvertedPanel { + readonly widget: DashboardWidget + readonly placeholder: boolean +} + +const CLICKHOUSE_TYPES = new Set(["grafana-clickhouse-datasource", "vertamedia-clickhouse-datasource"]) + +const DATASOURCE_NAMES: ReadonlyMap = new Map([ + ["loki", "Loki"], + ["tempo", "Tempo"], + ["elasticsearch", "Elasticsearch"], + ["influxdb", "InfluxDB"], + ["graphite", "Graphite"], + ["mysql", "MySQL"], + ["postgres", "PostgreSQL"], + ["grafana-postgresql-datasource", "PostgreSQL"], + ["cloudwatch", "CloudWatch"], + ["jaeger", "Jaeger"], + ["zipkin", "Zipkin"], + ["grafana", "Grafana built-in"], +]) + +type Query = + | { readonly kind: "promql"; readonly expr: string } + | { readonly kind: "clickhouse"; readonly sql: string } + | { readonly kind: "unsupported"; readonly datasource: string } + +const ASSUMED_PROMQL = + "Queries that name no datasource type (the default datasource, or a bare uid) were read as PromQL; check any that are not Prometheus." + +/** What a target queries; an unknown datasource with an `expr` is the default Prometheus. */ +function classifyTarget(target: UnknownRecord, panel: UnknownRecord, context: PanelContext): Query { + const type = datasourceType(target.datasource ?? panel.datasource, context.variables.datasourceTypes) + const expr = asString(target.expr) + const sql = asString(target.rawSql) ?? asString(target.query) + if (type === "prometheus" && expr !== undefined) return { kind: "promql", expr } + if (type === undefined && expr !== undefined) { + // An unresolvable datasource (the default, or a bare uid) is read as Prometheus; said once. + if (!Arr.contains(context.warnings, ASSUMED_PROMQL)) context.warnings.push(ASSUMED_PROMQL) + return { kind: "promql", expr } + } + if (type !== undefined && CLICKHOUSE_TYPES.has(type) && sql !== undefined) + return { kind: "clickhouse", sql } + if (type === undefined && asString(target.rawSql) !== undefined) { + return { kind: "clickhouse", sql: asString(target.rawSql) ?? "" } + } + return { + kind: "unsupported", + datasource: DATASOURCE_NAMES.get(type ?? "") ?? type ?? "an unknown datasource", + } +} + +function targetSummary(target: UnknownRecord): string { + const refId = asString(target.refId) ?? "?" + const text = asString(target.expr) ?? asString(target.rawSql) ?? asString(target.query) + return text === undefined ? refId : `${refId}: ${text}` +} + +/** A Grafana interval (`30s`, `1m`, `>15s`) in seconds; variables and garbage are `undefined`. */ +export function intervalSeconds(value: unknown): number | undefined { + const match = /^>?\s*(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$/u.exec(Str.trim(asString(value) ?? "")) + if (match === null) return undefined + const seconds = Number(match[1]) * (UNIT_SECONDS.get(match[2] ?? "s") ?? 1) + return seconds > 0 ? seconds : undefined +} + +const UNIT_SECONDS: ReadonlyMap = new Map([ + ["ms", 0.001], + ["s", 1], + ["m", 60], + ["h", 3600], + ["d", 86_400], + ["w", 604_800], +]) + +/** The Maple target for a panel type Maple can draw; charts split into line and bar by draw style. */ +function targetFor(panel: UnknownRecord): GrafanaTarget | undefined { + const meta = widgetTypeByGrafanaType(asString(panel.type)) + if (meta === undefined || meta.panelType === "markdown") return undefined + if (meta.panelType === "line") return chartStyle(panel).target + switch (meta.panelType) { + case "stat": + case "gauge": + case "table": + case "pie": + case "heatmap": + case "histogram": + return meta.panelType + default: + return undefined + } +} + +const VISUALIZATION = { + line: "chart", + bar: "chart", + stat: "stat", + gauge: "gauge", + table: "table", + pie: "pie", + heatmap: "heatmap", + histogram: "histogram", +} as const satisfies Record + +const DISPLAY_TYPE = { + line: "line", + bar: "bar", + stat: "stat", + gauge: "stat", + table: "table", + pie: "pie", + heatmap: "heatmap", + histogram: "histogram", +} as const satisfies Record + +/** A Grafana panel as a widget, or a placeholder note that says why it could not be one. */ +export function convertGrafanaPanel( + panel: UnknownRecord, + layout: DashboardWidget["layout"], + context: PanelContext, +): ConvertedPanel { + const { warnings } = context + const type = asString(panel.type) ?? "unknown" + const title = Str.trim(asString(panel.title) ?? "") || "Untitled panel" + const description = asString(panel.description) + const id = uniqueWidgetId("grafana", title, context.widgetIds) + const targets = Arr.filter( + Arr.flatMap(asArray(panel.targets), (t) => Arr.fromNullishOr(asRecord(t))), + (t) => t.hide !== true, + ) + const placeholder = (reason: string, warning?: string): ConvertedPanel => { + if (warning !== undefined) warnings.push(warning) + return { + placeholder: true, + widget: placeholderWidget({ + source: "Grafana", + id, + title, + description, + layout, + reason, + panelKind: ["Panel type", type], + querySummaries: Arr.map(targets, targetSummary), + }), + } + } + + if (asString(panel.repeat) !== undefined) { + warnings.push( + `Panel "${title}" repeats per value of $${asString(panel.repeat)} in Grafana; Maple shows it once.`, + ) + } + if (type === "text") { + const options = asRecord(panel.options) + const content = asString(options?.content) ?? asString(panel.content) ?? "" + if ((asString(options?.mode) ?? asString(panel.mode)) === "html") { + warnings.push(`Text panel "${title}" is HTML in Grafana; Maple shows it as markdown.`) + } + return { placeholder: false, widget: markdownWidget({ id, title, description, content, layout }) } + } + if (asRecord(panel.libraryPanel) !== null && asString(panel.type) === undefined) { + return placeholder( + "This panel is a Grafana library panel; its definition is not part of the dashboard JSON.", + `Panel "${title}" is a library panel, which the export does not include; it was imported as a placeholder.`, + ) + } + if (type === "logs") { + return placeholder( + "Maple has no logs panel for dashboards yet; open the Logs page for these lines.", + `Logs panel "${title}" was imported as a placeholder.`, + ) + } + const target = targetFor(panel) + if (target === undefined) { + return placeholder( + "Maple has no panel like this one yet.", + `Panel "${title}" uses the "${type}" panel type, which Maple cannot draw; it was imported as a placeholder.`, + ) + } + return convertQueryPanel({ panel, target, title, description, id, layout, targets, context, placeholder }) +} + +function convertQueryPanel(args: { + panel: UnknownRecord + target: GrafanaTarget + title: string + description: string | undefined + id: string + layout: DashboardWidget["layout"] + targets: ReadonlyArray + context: PanelContext + placeholder: (reason: string, warning?: string) => ConvertedPanel +}): ConvertedPanel { + const { panel, target, title, targets, context } = args + const [first, ...rest] = targets + if (first === undefined) { + return args.placeholder( + "This panel has no query.", + `Panel "${title}" has no queries; it was imported as a placeholder.`, + ) + } + // Maple widgets hold one query: the first visible target, the rest named so nothing drops silently. + if (rest.length > 0) { + context.warnings.push( + `Panel "${title}" has ${targets.length} queries; Maple imported ${asString(first.refId) ?? "the first"} only. Not imported: ${Arr.join(Arr.map(rest, targetSummary), "; ")}`, + ) + } + const query = classifyTarget(first, panel, context) + const visualization = VISUALIZATION[target] + const displayType = DISPLAY_TYPE[target] + if (query.kind === "unsupported") { + return args.placeholder( + `This panel queries ${query.datasource}, which Maple cannot run.`, + `Panel "${title}" queries ${query.datasource}, which Maple cannot run; it was imported as a placeholder.`, + ) + } + let dataSource: DashboardWidget["dataSource"] + if (query.kind === "clickhouse") { + const normalized = normalizeClickHouseSql( + rewriteVariableRefs(query.sql, context.variables), + context.warnings, + title, + ) + if ("placeholderReason" in normalized) { + // normalizeClickHouseSql already said why. + return args.placeholder(normalized.placeholderReason) + } + const transform = grafanaScalarTransform( + panel, + visualization, + displayType, + title, + context.warnings, + true, + ) + dataSource = rawSqlDataSource({ visualization, sql: normalized.sql, displayType, transform }) + } else { + // A PromQL widget's heatmap rows keep one value per series, not the time by bucket grid. + if (target === "heatmap") { + return args.placeholder( + "This heatmap needs its buckets over time, which Maple's PromQL widgets do not draw yet.", + `Heatmap "${title}" was imported as a placeholder: Maple's PromQL widgets cannot draw buckets over time yet.`, + ) + } + const legendFormat = asString(first.legendFormat) + const minStepSeconds = intervalSeconds(first.interval) ?? intervalSeconds(panel.interval) + const transform = grafanaScalarTransform(panel, visualization, displayType, title, context.warnings) + dataSource = makePromqlDataSource({ + query: rewriteVariableRefs(query.expr, context.variables), + ...(legendFormat === undefined || legendFormat === "__auto" ? undefined : { legendFormat }), + ...(minStepSeconds === undefined ? undefined : { minStepSeconds }), + displayType, + ...(transform === undefined ? undefined : { transform }), + }) + } + return { + placeholder: false, + widget: { + id: args.id, + visualization, + dataSource, + display: grafanaDisplay({ + panel, + target, + title, + description: args.description, + warnings: context.warnings, + }), + layout: args.layout, + }, + } +} + +/** Grafana's `reduceOptions.calcs` to Maple's reducers; `last` reads the first row, as a stat's rows come newest first. */ +const GRAFANA_CALCS = new Map([ + ["lastNotNull", "first"], + ["last", "first"], + ["mean", "avg"], + ["max", "max"], + ["min", "min"], + ["sum", "sum"], + ["count", "count"], +]) + +/** A scalar panel's reducer: Grafana's own calculation where Maple has it, else the latest value. */ +function grafanaScalarTransform( + panel: UnknownRecord, + visualization: string, + displayType: string, + title: string, + warnings: string[], + /** Raw SQL rows keep the query's own order, so a "last value" reads whichever row comes first. */ + rowsInQueryOrder = false, +) { + const transform = scalarTransform(visualization, displayType) + if (transform === undefined) return undefined + const calc = asString(asArray(asRecord(asRecord(panel.options)?.reduceOptions)?.calcs)[0]) + const mapped = calc === undefined ? undefined : GRAFANA_CALCS.get(calc) + // What a missing or unsupported calc falls back to: the first row, which is the latest only when + // rows come newest first (always for PromQL, only when the query orders them so for raw SQL). + const shown = rowsInQueryOrder ? "the value of the query's first row" : "the latest value" + if (calc !== undefined && mapped === undefined) { + warnings.push( + `Panel "${title}" reduces with "${calc}", which Maple does not have; it shows ${shown}.`, + ) + } + const aggregate = mapped ?? "first" + if (rowsInQueryOrder && aggregate === "first") { + warnings.push( + `Panel "${title}" reads the query's first row as its value; order the query newest first (ORDER BY time DESC) to show the latest.`, + ) + } + return mapped === undefined ? transform : { reduceToValue: { field: "value", aggregate } } +} diff --git a/packages/backend/src/services/dashboards/grafana-import-variables.ts b/packages/backend/src/services/dashboards/grafana-import-variables.ts new file mode 100644 index 0000000000..99d9f3102b --- /dev/null +++ b/packages/backend/src/services/dashboards/grafana-import-variables.ts @@ -0,0 +1,268 @@ +// Grafana `templating.list` to Maple dashboard variables. Pure. +import type { DashboardVariable } from "@maple/domain/http" +import { replaceWith } from "@maple/strings" +import { Array as Arr, Order, String as Str } from "effect" +import { asArray, asRecord, asString, type UnknownRecord } from "./dashboard-import-shared" + +export interface GrafanaVariableConversion { + readonly variables: ReadonlyArray + /** Grafana name to Maple name, for names `DashboardVariableName` refuses. */ + readonly renames: ReadonlyMap + /** `interval` variables: their references become `$__interval`. */ + readonly intervalNames: ReadonlySet + /** `datasource` variables: name to the plugin type they select. */ + readonly datasourceTypes: ReadonlyMap +} + +const VALID_NAME = /^[A-Za-z][A-Za-z0-9_]*$/u +const METRIC_NAME = /^[A-Za-z_:][A-Za-z0-9_:]*$/u +const LABEL_VALUES = /^\s*label_values\(\s*(?:(.+?)\s*,\s*)?([A-Za-z_][A-Za-z0-9_]*)\s*\)\s*$/su + +function mapleName(name: string, taken: Set): string { + const cleaned = Str.replace(/^[^A-Za-z]+/u, "")(Str.replace(/[^A-Za-z0-9_]/gu, "_")(name)) + const base = cleaned === "" ? "var" : cleaned + let candidate = base + let index = 2 + while (taken.has(candidate)) candidate = `${base}_${index++}` + taken.add(candidate) + return candidate +} + +/** The selected value, unless it is Grafana's "All" sentinel. */ +function currentValue(variable: UnknownRecord): string | undefined { + const value = asRecord(variable.current)?.value + const first = Arr.isArray(value) ? value[0] : value + return typeof first === "string" && first !== "$__all" && first !== "" ? first : undefined +} + +function queryText(variable: UnknownRecord): string | undefined { + return ( + asString(variable.query) ?? asString(asRecord(variable.query)?.query) ?? asString(variable.definition) + ) +} + +function customOptions(variable: UnknownRecord): Array<{ value: string; label?: string }> { + const fromOptions = Arr.flatMap(asArray(variable.options), (option) => { + const record = asRecord(option) + const value = asString(record?.value) + const text = asString(record?.text) + if (value === undefined || value === "$__all") return [] + return [text !== undefined && text !== value ? { value, label: text } : { value }] + }) + if (fromOptions.length > 0) return fromOptions + // `a,b,c` or `label : value` pairs, as Grafana's custom variable editor writes them. + return Arr.flatMap(Str.split(queryText(variable) ?? "", ","), (part) => { + const [label, value] = Arr.map(Str.split(part, " : "), Str.trim) + if (label === undefined || label === "") return [] + return value === undefined || value === "" ? [{ value: label }] : [{ value, label }] + }) +} + +/** Prometheus metric types Maple keeps in different tables; guessed from the name's suffix. */ +function guessMetricType(metric: string): "sum" | "gauge" | "histogram" { + if (/_(total|created)$/u.test(metric)) return "sum" + if (/_(bucket|count|sum)$/u.test(metric)) return "histogram" + return "gauge" +} + +type QuerySource = Extract["source"] + +/** A `label_values(...)` Prometheus query as a Maple variable source, when it can be one. */ +function labelValuesSource(query: string, name: string, warnings: string[]): QuerySource | undefined { + const match = LABEL_VALUES.exec(query) + if (match === null) return undefined + const [, selector, label = ""] = match + // `job` is the service name: OTel metrics carry it only as `service.name`, and the scraper sets + // `service.name` to the job too, so the service list holds every job a dashboard can filter by. + if (label === "job") return { kind: "facet", facet: "service" } + if (selector === undefined) return undefined + const [metricPart, matchers] = Str.split(selector, "{") + const metric = Str.trim(metricPart) + if (!METRIC_NAME.test(metric)) return undefined + if (matchers !== undefined && !/^\s*\}/u.test(matchers)) { + warnings.push( + `Variable "${name}" lists every ${label} of ${metric}; the label filters in "${selector}" were not imported.`, + ) + } + // Scraped Prometheus data, what these dashboards read, carries job and instance as datapoint + // labels on the metric itself, like every other label. + return { + kind: "metric", + metricType: guessMetricType(metric), + metricNames: [metric], + scope: "metric", + attributeKey: label, + } +} + +/** The plugin type a datasource reference names: `{ type }`, or a `${NAME}` input or `$name` datasource variable. */ +export function datasourceType( + datasource: unknown, + datasourceTypes: ReadonlyMap, +): string | undefined { + const record = asRecord(datasource) + const type = asString(record?.type) + if (type !== undefined && type !== "datasource") return type + const ref = asString(record?.uid) ?? asString(datasource) + const name = ref === undefined ? undefined : /^\$\{?([A-Za-z0-9_]+)\}?$/u.exec(ref)?.[1] + return name === undefined ? undefined : datasourceTypes.get(name) +} + +function convertOne( + variable: UnknownRecord, + name: string, + datasourceTypes: ReadonlyMap, + warnings: string[], +): DashboardVariable | undefined { + const type = asString(variable.type) + const label = asString(variable.label) + const current = currentValue(variable) + const base = { + name, + ...(label === undefined ? undefined : { label }), + ...(variable.includeAll === true ? { includeAll: true } : undefined), + } + const textbox = (value: string | undefined): DashboardVariable => ({ + ...base, + type: "textbox", + ...(value === undefined ? undefined : { defaultValue: value }), + }) + switch (type) { + case "custom": + return { + ...base, + type: "custom", + options: customOptions(variable), + ...(current === undefined ? undefined : { defaultValue: current }), + } + case "constant": + return textbox(queryText(variable) ?? current) + case "textbox": + return textbox(current ?? queryText(variable)) + case "query": { + const query = queryText(variable) ?? "" + const plugin = datasourceType(variable.datasource, datasourceTypes) + const source = + plugin === undefined || plugin === "prometheus" + ? labelValuesSource(query, name, warnings) + : undefined + if (source !== undefined) { + return { + ...base, + type: "query", + source, + ...(current === undefined ? undefined : { defaultValue: current }), + } + } + warnings.push( + `Variable "${name}" became a text box: Maple cannot run its ${plugin ?? "Prometheus"} query "${query}".`, + ) + return textbox(current) + } + default: + warnings.push(`Variable "${name}" of type "${type ?? "unknown"}" became a text box.`) + return textbox(current) + } +} + +/** Every `templating.list` entry Maple can hold, plus how queries must be rewritten for it. */ +export function convertGrafanaVariables( + templating: unknown, + inputTypes: ReadonlyMap, + warnings: string[], +): GrafanaVariableConversion { + const list = Arr.flatMap(asArray(asRecord(templating)?.list), (item) => { + const record = asRecord(item) + const name = asString(record?.name) + return record === null || name === undefined ? [] : [{ record, name }] + }) + const datasourceTypes = new Map(inputTypes) + const intervalNames = new Set() + for (const { record, name } of list) { + const type = asString(record.type) + if (type === "datasource") datasourceTypes.set(name, asString(record.query) ?? "") + if (type === "interval") intervalNames.add(name) + } + + const taken = new Set() + // Valid names are claimed first, so a sanitized name never takes one a later variable owns. + const reserved = new Set( + Arr.flatMap(list, ({ record, name }) => { + const type = asString(record.type) + const skipped = type === "datasource" || type === "interval" || type === "adhoc" + return !skipped && VALID_NAME.test(name) ? [name] : [] + }), + ) + const renames = new Map() + const variables: DashboardVariable[] = [] + for (const { record, name } of list) { + const type = asString(record.type) + if (type === "datasource") continue + if (type === "interval") { + warnings.push(`Interval variable "${name}" was not imported; its references now use $__interval.`) + continue + } + if (type === "adhoc") { + warnings.push(`Ad hoc filter variable "${name}" was not imported.`) + continue + } + const maple = + VALID_NAME.test(name) && !taken.has(name) + ? name + : mapleName(name, new Set([...taken, ...reserved])) + taken.add(maple) + if (maple !== name) { + renames.set(name, maple) + warnings.push(`Variable "${name}" was renamed to "${maple}"; queries that use it were rewritten.`) + } + const converted = convertOne(record, maple, datasourceTypes, warnings) + if (converted !== undefined) variables.push(converted) + } + return { variables, renames, intervalNames, datasourceTypes } +} + +const escapeRegex = (value: string) => Str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")(value) + +/** Every reference to any of `names`, in all three syntaxes, longest name first. */ +const referencesPattern = (names: ReadonlyArray) => { + const alt = Arr.join( + Arr.map( + Arr.sort( + names, + Order.mapInput(Order.Number, (n: string) => -n.length), + ), + escapeRegex, + ), + "|", + ) + return new RegExp(`\\$\\{(${alt})(:[A-Za-z]+)?\\}|\\[\\[(${alt})\\]\\]|\\$(${alt})(?![A-Za-z0-9_])`, "gu") +} + +const renamedReference = (match: string, to: string, format: string | undefined) => { + if (Str.startsWith("[[")(match)) return `[[${to}]]` + if (Str.startsWith("${")(match)) return `\${${to}${format ?? ""}}` + return `$${to}` +} + +/** A query with renamed variables renamed and interval variables replaced by `$__interval`. */ +export function rewriteVariableRefs(query: string, conversion: GrafanaVariableConversion): string { + const names = [...conversion.intervalNames, ...conversion.renames.keys()] + if (names.length === 0) return query + // One pass over the original: a rename's output is never renamed again. + return replaceWith( + query, + referencesPattern(names), + ( + match: string, + braced: string | undefined, + format: string | undefined, + bracketed: string | undefined, + bare: string | undefined, + ) => { + const name = braced ?? bracketed ?? bare ?? "" + if (conversion.intervalNames.has(name)) return "$__interval" + const to = conversion.renames.get(name) + return to === undefined ? match : renamedReference(match, to, format) + }, + ) +} diff --git a/packages/backend/src/services/dashboards/perses-dashboard-import.ts b/packages/backend/src/services/dashboards/perses-dashboard-import.ts index 76d082b2b5..fcf246cb50 100644 --- a/packages/backend/src/services/dashboards/perses-dashboard-import.ts +++ b/packages/backend/src/services/dashboards/perses-dashboard-import.ts @@ -1,20 +1,26 @@ -import { dashboardTimeBoundIssue } from "@maple/domain/raw-sql" import { Effect, Schema, Array as Arr, Record as Rec, String as Str } from "effect" import { DashboardValidationError, - DashboardWidgetSchema, PortableDashboardDocument, type RawSqlDisplayType, defaultWidgetLayout, findNextPosition, widgetTypeByPersesKind, - widgetTypeByVisualization, type WidgetVisualization, } from "@maple/domain/http" -import { makeRawSqlDataSource, makeStaticDataSource } from "@maple/widgets/dashboard" - -type UnknownRecord = Record -type DashboardWidget = typeof DashboardWidgetSchema.Type +import { + type DashboardWidget, + type UnknownRecord, + asArray, + asFiniteNumber, + asRecord, + asString, + markdownWidget, + normalizeClickHouseSql, + placeholderWidget as sharedPlaceholderWidget, + rawSqlDataSource, + uniqueWidgetId, +} from "./dashboard-import-shared" export interface PersesImportConversion { readonly dashboard: PortableDashboardDocument @@ -40,24 +46,6 @@ const SUPPORTED_PANEL_KINDS = new Set([ "Heatmap", ]) -const isRecord = (value: unknown): value is UnknownRecord => - typeof value === "object" && value !== null && !Arr.isArray(value) - -const asRecord = (value: unknown): UnknownRecord | null => (isRecord(value) ? value : null) - -const asArray = (value: unknown): unknown[] => (Arr.isArray(value) ? value : []) - -const asString = (value: unknown): string | undefined => - typeof value === "string" && Str.trim(value).length > 0 ? value : undefined - -const asFiniteNumber = (value: unknown): number | undefined => - typeof value === "number" && Number.isFinite(value) ? value : undefined - -const sanitizeIdSegment = (value: string): string => { - const normalized = Str.replace(/^-+|-+$/g, "")(Str.replace(/[^a-z0-9_-]+/g, "-")(Str.toLowerCase(value))) - return normalized.length > 0 ? normalized : "panel" -} - const jsonPointerSegment = (segment: string): string => decodeURIComponent(Str.replace(/~0/g, "~")(Str.replace(/~1/g, "/")(segment))) @@ -203,17 +191,6 @@ function gridLayoutFromItem( return { x, y, w, h, minW: defaults.minW, minH: defaults.minH } } -function uniqueWidgetId(panelKey: string, existing: Set): string { - const base = `perses-${sanitizeIdSegment(panelKey)}` - let candidate = base - let index = 2 - while (existing.has(candidate)) { - candidate = `${base}-${index++}` - } - existing.add(candidate) - return candidate -} - function queryPluginFromQuery(query: unknown) { const queryRecord = asRecord(query) const spec = asRecord(queryRecord?.spec) @@ -235,119 +212,20 @@ function querySummaries(queries: readonly unknown[]): string[] { }) } -function hasOrgScope(sql: string): boolean { - return Str.includes("$__orgFilter")(sql) || /\bOrgId\b/.test(sql) -} - -function insertBeforeTrailingClauses(sql: string, fragment: string): string { - const match = /\b(GROUP\s+BY|ORDER\s+BY|LIMIT|FORMAT)\b/i.exec(sql) - if (!match) return `${Str.trimEnd(sql)} ${fragment}` - return `${Str.trimEnd(Str.slice(0, match.index)(sql))} ${fragment} ${Str.trimStart(Str.slice(match.index)(sql))}` -} - -type NormalizedSql = { readonly sql: string } | { readonly placeholderReason: string } - -function normalizeClickHouseSql(sql: string, warnings: string[], panelTitle: string): NormalizedSql { - if (!hasOrgScope(sql)) { - warnings.push( - `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query does not include $__orgFilter or an OrgId predicate.`, - ) - return { placeholderReason: "This ClickHouse query needs Maple org scoping before it can run." } - } - - const normalized = Str.includes("$__orgFilter")(sql) - ? sql - : insertBeforeTrailingClauses(sql, /\bWHERE\b/i.test(sql) ? "AND $__orgFilter" : "WHERE $__orgFilter") - - if (!Str.includes("$__orgFilter")(sql)) { - warnings.push( - `Panel "${panelTitle}" had an explicit OrgId reference; Maple added $__orgFilter so the widget stays tenant-scoped.`, - ) - } - - // Saving refuses raw SQL that reads outside the dashboard range (DashboardPersistenceService). - if (dashboardTimeBoundIssue(normalized) !== null) { - warnings.push( - `Panel "${panelTitle}" was imported as a placeholder because its ClickHouse query does not use $__timeFilter(...) or $__startTime, so it would read all retained data on every refresh.`, - ) - return { - placeholderReason: - "This ClickHouse query needs a Maple time filter ($__timeFilter(...) or $__startTime) before it can run.", - } - } - - return { sql: normalized } -} - -function rawSqlDataSource(args: { - visualization: string - sql: string - displayType: RawSqlDisplayType -}): DashboardWidget["dataSource"] { - // `displayType === "stat"` is kept alongside the panel's own scalar flag: a - // Perses panel can import as a non-scalar type while its query still yields - // the single-row shape a stat renders. - const isScalar = - args.displayType === "stat" || widgetTypeByVisualization(args.visualization)?.isScalar === true - - return makeRawSqlDataSource({ - sql: args.sql, - displayType: args.displayType, - ...(isScalar ? { transform: { reduceToValue: { field: "value", aggregate: "first" } } } : undefined), - }) -} - -function markdownDataSource(): DashboardWidget["dataSource"] { - return makeStaticDataSource() -} - -function markdownWidgetContent(args: { - reason: string - panelKind?: string - querySummaries?: readonly string[] -}) { - const lines = [ - "### Perses import placeholder", - args.reason, - ...(args.panelKind ? [`Panel plugin: \`${args.panelKind}\``] : []), - ] - - if (args.querySummaries && args.querySummaries.length > 0) { - lines.push("", "Queries:") - for (const summary of args.querySummaries) { - lines.push(`- ${summary}`) - } - } - - return Arr.join(lines, "\n") -} - function placeholderWidget(args: { id: string title: string - description?: string + description?: string | undefined layout: DashboardWidget["layout"] reason: string panelKind?: string querySummaries?: readonly string[] }): DashboardWidget { - return { - id: args.id, - visualization: "markdown", - dataSource: markdownDataSource(), - display: { - title: args.title, - ...(args.description ? { description: args.description } : undefined), - markdown: { - content: markdownWidgetContent({ - reason: args.reason, - panelKind: args.panelKind, - querySummaries: args.querySummaries, - }), - }, - }, - layout: args.layout, - } + return sharedPlaceholderWidget({ + ...args, + source: "Perses", + panelKind: args.panelKind === undefined ? undefined : ["Panel plugin", args.panelKind], + }) } function convertPanel(args: { @@ -360,7 +238,7 @@ function convertPanel(args: { const { spec, kind, pluginSpec } = getPanelPlugin(args.panel) const display = getDisplay(spec) const title = display.title ?? args.panelKey - const id = uniqueWidgetId(args.panelKey, args.widgetIds) + const id = uniqueWidgetId("perses", args.panelKey, args.widgetIds) const visualization = defaultVisualizationForPanelKind(kind) if (!kind) { @@ -394,17 +272,13 @@ function convertPanel(args: { if (!text) { args.warnings.push(`Markdown panel "${title}" has no text content.`) } - return { + return markdownWidget({ id, - visualization: "markdown", - dataSource: markdownDataSource(), - display: { - title, - ...(display.description ? { description: display.description } : undefined), - markdown: { content: text }, - }, + title, + description: display.description, + content: text, layout: args.layout, - } + }) } const queries = asArray(spec?.queries) diff --git a/packages/domain/src/http/analyst-access.test.ts b/packages/domain/src/http/analyst-access.test.ts index 3b991ba0d9..c5c474f3a5 100644 --- a/packages/domain/src/http/analyst-access.test.ts +++ b/packages/domain/src/http/analyst-access.test.ts @@ -41,6 +41,7 @@ describe("isOpenToAnalysts", () => { it("lets an analyst change dashboards in every way a member can", () => { const writes = [ "create", + "importGrafana", "importPerses", "instantiateTemplate", "update", diff --git a/packages/domain/src/http/v2/dashboards.ts b/packages/domain/src/http/v2/dashboards.ts index bd65d03d18..4426d1fda4 100644 --- a/packages/domain/src/http/v2/dashboards.ts +++ b/packages/domain/src/http/v2/dashboards.ts @@ -353,6 +353,32 @@ export const V2DashboardPersesImportResponse = Schema.Struct({ warnings: Schema.Array(Schema.String), }).annotate({ identifier: "DashboardPersesImport", title: "Perses dashboard import" }) +export const V2DashboardGrafanaImportParams = Schema.Struct({ + dashboard: Schema.Record(Schema.String, Schema.Unknown), +}).annotate({ + identifier: "DashboardGrafanaImportParams", + title: "Grafana import parameters", + description: + "A Grafana dashboard JSON: the bare dashboard, the `{ dashboard, meta }` API envelope, or an export for sharing.", +}) + +export const V2DashboardGrafanaImportStats = Schema.Struct({ + panels: Schema.Number, + converted: Schema.Number, + placeholders: Schema.Number, +}).annotate({ + identifier: "DashboardGrafanaImportStats", + title: "Grafana import stats", + description: "Panels read (rows excluded), panels that became working widgets, and panels kept as notes.", +}) + +export const V2DashboardGrafanaImportResponse = Schema.Struct({ + object: Schema.Literal("dashboard_import"), + dashboard: V2DashboardMutation, + warnings: Schema.Array(Schema.String), + stats: V2DashboardGrafanaImportStats, +}).annotate({ identifier: "DashboardGrafanaImport", title: "Grafana dashboard import" }) + /** * A dashboard's share link, as its owner sees it. * @@ -557,6 +583,22 @@ export class V2DashboardsApiGroup extends HttpApiGroup.make("dashboards") }), ), ) + .add( + HttpApiEndpoint.post("importGrafana", "/import/grafana", { + payload: V2DashboardGrafanaImportParams, + success: V2DashboardGrafanaImportResponse, + error: dashboardCreateErrors, + }) + .annotate(AnalystAccess, "author") + .annotateMerge( + OpenApi.annotations({ + identifier: "importGrafanaDashboard", + summary: "Import a Grafana dashboard", + description: + "Converts a Grafana dashboard into Maple's dashboard model: rows become sections, Prometheus targets PromQL widgets, and panels Maple cannot run notes. Returns the warnings and how many panels converted.", + }), + ), + ) .add( HttpApiEndpoint.get("listTemplates", "/templates", { query: ListQuery, diff --git a/packages/domain/src/http/v2/openapi.test.ts b/packages/domain/src/http/v2/openapi.test.ts index 6d8853ade2..788e380804 100644 --- a/packages/domain/src/http/v2/openapi.test.ts +++ b/packages/domain/src/http/v2/openapi.test.ts @@ -276,6 +276,7 @@ describe("MapleApiV2 OpenAPI", () => { "POST /v2/api_keys/{id}/roll", "POST /v2/attribute_mappings", "POST /v2/dashboards", + "POST /v2/dashboards/import/grafana", "POST /v2/dashboards/import/perses", "POST /v2/dashboards/templates/{template_id}/instantiate", "POST /v2/dashboards/templates/{template_id}/preview", @@ -884,6 +885,7 @@ describe("MapleApiV2 OpenAPI", () => { for (const [method, path] of [ ["delete", "/v2/dashboards/{id}"], ["post", "/v2/dashboards"], + ["post", "/v2/dashboards/import/grafana"], ["post", "/v2/dashboards/import/perses"], ["post", "/v2/dashboards/templates/{template_id}/instantiate"], ["get", "/v2/dashboards/templates"], diff --git a/packages/domain/src/http/widget-types.ts b/packages/domain/src/http/widget-types.ts index 2c68d1e729..77e9648d37 100644 --- a/packages/domain/src/http/widget-types.ts +++ b/packages/domain/src/http/widget-types.ts @@ -29,6 +29,7 @@ export { WIDGET_VISUALIZATIONS, type WidgetTypeMeta, type WidgetVisualization, + widgetTypeByGrafanaType, widgetTypeByPersesKind, widgetTypeByVisualization, } from "@maple/widgets" diff --git a/packages/domain/src/mcp-outputs/dashboards.ts b/packages/domain/src/mcp-outputs/dashboards.ts index e19acbef14..abd3c23deb 100644 --- a/packages/domain/src/mcp-outputs/dashboards.ts +++ b/packages/domain/src/mcp-outputs/dashboards.ts @@ -108,9 +108,15 @@ export const GetDashboardOutput = Schema.Struct({ export const CreateDashboardOutput = Schema.Struct({ dashboard: DashboardRow, validation: Schema.optionalKey(WidgetInspectionSummary), - /** Which of the three creation paths built it. */ - source: Schema.Literals(["template", "widgets", "dashboard_json"]), + /** Which creation path built it. */ + source: Schema.Literals(["template", "widgets", "dashboard_json", "grafana_import", "perses_import"]), template: Schema.optionalKey(Schema.String), + /** What a Grafana or Perses import changed or could not carry over. */ + importWarnings: Schema.optionalKey(Schema.Array(Schema.String)), + /** A Grafana import: panels read, converted to widgets, and kept as notes. */ + importStats: Schema.optionalKey( + Schema.Struct({ panels: Schema.Number, converted: Schema.Number, placeholders: Schema.Number }), + ), /** Advisory: saved anyway. */ renderWarnings: Schema.Array(Schema.String), }) diff --git a/packages/widgets/src/widget-types.test.ts b/packages/widgets/src/widget-types.test.ts index 54b20bb2fb..388fd1fa0b 100644 --- a/packages/widgets/src/widget-types.test.ts +++ b/packages/widgets/src/widget-types.test.ts @@ -6,6 +6,7 @@ import { MCP_VISUALIZATIONS, PANEL_TYPES, rawSqlDisplayTypeFor, + widgetTypeByGrafanaType, widgetTypeByPersesKind, widgetTypeByVisualization, WIDGET_VISUALIZATIONS, @@ -90,6 +91,22 @@ describe("widgetTypeByPersesKind", () => { }) }) +describe("widgetTypeByGrafanaType", () => { + it("maps Grafana panel types to the Maple panel that draws them", () => { + expect(widgetTypeByGrafanaType("timeseries")?.panelType).toBe("line") + expect(widgetTypeByGrafanaType("singlestat")?.panelType).toBe("stat") + expect(widgetTypeByGrafanaType("bargauge")?.panelType).toBe("gauge") + expect(widgetTypeByGrafanaType("piechart")?.panelType).toBe("pie") + expect(widgetTypeByGrafanaType("text")?.panelType).toBe("markdown") + }) + + it("has no panel for a type Maple cannot draw", () => { + expect(widgetTypeByGrafanaType("nodeGraph")).toBeUndefined() + expect(widgetTypeByGrafanaType("logs")).toBeUndefined() + expect(widgetTypeByGrafanaType(undefined)).toBeUndefined() + }) +}) + describe("MCP_VISUALIZATIONS", () => { it("collapses line/bar/area into one chart entry", () => { expect(Arr.filter(MCP_VISUALIZATIONS, (viz) => viz === "chart")).toHaveLength(1) diff --git a/packages/widgets/src/widget-types.ts b/packages/widgets/src/widget-types.ts index 82e73fc32b..2fe4d6f90d 100644 --- a/packages/widgets/src/widget-types.ts +++ b/packages/widgets/src/widget-types.ts @@ -130,6 +130,8 @@ export interface WidgetTypeMeta { readonly mcpExposed: boolean /** Perses panel `kind`s that import as this panel type. */ readonly persesKinds: ReadonlyArray + /** Grafana panel `type`s that import as this panel type; the importer refines charts by draw style. */ + readonly grafanaTypes: ReadonlyArray } const CHART_LAYOUT = { w: 4, h: 6, minW: 2, minH: 2 } as const @@ -139,6 +141,7 @@ const chartPanel = ( panelType: "line" | "bar" | "area", label: string, persesKinds: ReadonlyArray, + grafanaTypes: ReadonlyArray = [], ): WidgetTypeMeta => ({ panelType, label, @@ -158,6 +161,7 @@ const chartPanel = ( // undocumented `display.chartId`. mcpExposed: true, persesKinds, + grafanaTypes, }) /** @@ -170,6 +174,7 @@ const breakdownPanel = ( requiresGroupBy: boolean ownedDisplayKeys?: ReadonlyArray persesKinds?: ReadonlyArray + grafanaTypes?: ReadonlyArray }, ): WidgetTypeMeta => ({ panelType, @@ -184,10 +189,11 @@ const breakdownPanel = ( requiresGroupBy: options.requiresGroupBy, mcpExposed: true, persesKinds: options.persesKinds ?? [], + grafanaTypes: options.grafanaTypes ?? [], }) export const WIDGET_TYPES: Record = { - line: chartPanel("line", "Line", ["TimeSeriesChart"]), + line: chartPanel("line", "Line", ["TimeSeriesChart"], ["timeseries", "graph"]), bar: chartPanel("bar", "Bar", ["BarChart"]), area: chartPanel("area", "Area", []), @@ -203,6 +209,7 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: ["StatChart"], + grafanaTypes: ["stat", "singlestat"], }, gauge: { @@ -219,6 +226,7 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: ["GaugeChart"], + grafanaTypes: ["gauge", "bargauge"], }, table: { @@ -232,6 +240,7 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: ["Table", "LogsTable", "TimeSeriesTable"], + grafanaTypes: ["table", "table-old"], }, list: { @@ -249,9 +258,14 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: [], + grafanaTypes: [], }, - pie: breakdownPanel("pie", "Pie", { requiresGroupBy: true, persesKinds: ["PieChart"] }), + pie: breakdownPanel("pie", "Pie", { + requiresGroupBy: true, + persesKinds: ["PieChart"], + grafanaTypes: ["piechart", "grafana-piechart-panel"], + }), // A histogram is a *distribution*, so it has two legitimate shapes: grouped // (pre-bucketed bars) or raw per-row values the chart bucketizes client-side. // The second is valid without a group-by, so the blanket requirement is off @@ -259,11 +273,13 @@ export const WIDGET_TYPES: Record = { histogram: breakdownPanel("histogram", "Histogram", { requiresGroupBy: false, persesKinds: ["Histogram", "HistogramChart"], + grafanaTypes: ["histogram"], }), heatmap: breakdownPanel("heatmap", "Heatmap", { requiresGroupBy: true, ownedDisplayKeys: ["chartId", "heatmap"], persesKinds: ["HeatMap", "HeatMapChart", "Heatmap"], + grafanaTypes: ["heatmap"], }), // A funnel implies sequential stages with a monotonic drop-off, and it labels // each bar as a share of the *largest* bar. A ranked "top N by volume" @@ -286,6 +302,7 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: [], + grafanaTypes: [], }, hbar: breakdownPanel("hbar", "Horizontal Bar", { requiresGroupBy: true, @@ -307,6 +324,7 @@ export const WIDGET_TYPES: Record = { requiresGroupBy: false, mcpExposed: true, persesKinds: ["Markdown"], + grafanaTypes: ["text"], }, } satisfies Record @@ -349,6 +367,12 @@ export const widgetTypeByPersesKind = (kind: string | undefined): WidgetTypeMeta () => WIDGET_TYPES.line, ) +/** The panel type a Grafana panel `type` imports as; `undefined` when Maple has none. */ +export const widgetTypeByGrafanaType = (type: string | undefined): WidgetTypeMeta | undefined => + Option.getOrUndefined( + Arr.findFirst(PANEL_TYPES, (meta) => type != null && meta.grafanaTypes.includes(type)), + ) + /** * Rows a list widget shows when its limit is left blank. *