Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/stacked-line-charts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@hyperdx/common-utils': minor
'@hyperdx/app': minor
'@hyperdx/api': minor
'@hyperdx/cli': minor
---

feat: add stacked line (stacked area) time-series display type
150 changes: 148 additions & 2 deletions packages/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,16 @@
}
]
},
"AlertStackedLineChartConfig": {
"allOf": [
{
"$ref": "#/components/schemas/StackedLineChartConfig"
},
{
"$ref": "#/components/schemas/AlertChartConfigOverlay"
}
]
},
"AlertNumberChartConfig": {
"allOf": [
{
Expand All @@ -149,14 +159,17 @@
]
},
"AlertChartConfig": {
"description": "The chart configuration an inline alert evaluates, in the same dialect as dashboard tile configs plus the alert-only fields in AlertChartConfigOverlay. Only the display types the alert evaluator supports are accepted: line, stacked_bar, and number, in both builder and Raw SQL (configType \"sql\") variants. Raw SQL templates must reference the evaluation window via the time-filter and interval macros (e.g. $__timeFilter and $__timeInterval), and the referenced source/connection must belong to the team.\n",
"description": "The chart configuration an inline alert evaluates, in the same dialect as dashboard tile configs plus the alert-only fields in AlertChartConfigOverlay. Only the display types the alert evaluator supports are accepted: line, stacked_bar, stacked_line, and number, in both builder and Raw SQL (configType \"sql\") variants. Raw SQL templates must reference the evaluation window via the time-filter and interval macros (e.g. $__timeFilter and $__timeInterval), and the referenced source/connection must belong to the team.\n",
"oneOf": [
{
"$ref": "#/components/schemas/AlertLineChartConfig"
},
{
"$ref": "#/components/schemas/AlertBarChartConfig"
},
{
"$ref": "#/components/schemas/AlertStackedLineChartConfig"
},
{
"$ref": "#/components/schemas/AlertNumberChartConfig"
}
Expand Down Expand Up @@ -1031,6 +1044,7 @@
"type": "string",
"enum": [
"stacked_bar",
"stacked_line",
"line"
],
"description": "Visual representation type for the time series."
Expand Down Expand Up @@ -1940,6 +1954,83 @@
}
}
},
"StackedLineBuilderChartConfig": {
"type": "object",
"required": [
"displayType",
"sourceId",
"select"
],
"description": "Builder configuration for a stacked-line time-series chart.",
"properties": {
"displayType": {
"type": "string",
"enum": [
"stacked_line"
],
"description": "Display type discriminator. Must be \"stacked_line\" for stacked-line charts.",
"example": "stacked_line"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query.",
"example": "65f5e4a3b9e77c001a111111"
},
"select": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "One or more aggregated values to plot. When asRatio is true, exactly two select items are required.\n",
"items": {
"$ref": "#/components/schemas/SelectItem"
}
},
"groupBy": {
"type": "string",
"description": "Field expression to group results by (creates separate stacked bands per group value).",
"example": "service",
"maxLength": 10000
},
"asRatio": {
"type": "boolean",
"description": "Plot select[0] / select[1] as a ratio. Requires exactly two select items.",
"default": false
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Align the date range boundaries to the query granularity interval.",
"default": true
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
},
"seriesLimit": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of series rendered (top-N by value). Omit to use the default render cap, set 0 for unlimited, or a positive N to keep the top N series.",
"example": 5
},
"formulas": {
"type": "array",
"maxItems": 10,
"description": "Derived series computed from the select items via letter-ref arithmetic (\"A\" = select[0], \"B\" = select[1], ...). Metric, log, and trace sources only. Cannot be combined with asRatio.\n",
"items": {
"$ref": "#/components/schemas/Formula"
}
},
"showOperandSeries": {
"type": "boolean",
"description": "Only meaningful with formulas. When false, only the formula series are returned; the raw operand series are hidden.\n",
"default": true
}
}
},
"TableBuilderChartConfig": {
"type": "object",
"required": [
Expand Down Expand Up @@ -2568,6 +2659,40 @@
}
]
},
"StackedLineRawSqlChartConfig": {
"description": "Raw SQL configuration for a stacked-line time-series chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"stacked_line"
],
"description": "Display as a stacked-line time-series chart.",
"example": "stacked_line"
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Expand date range boundaries to the query granularity interval.",
"default": true
}
}
}
]
},
"TableRawSqlChartConfig": {
"description": "Raw SQL configuration for a table chart.",
"allOf": [
Expand Down Expand Up @@ -2714,6 +2839,23 @@
}
}
},
"StackedLineChartConfig": {
"description": "Stacked-line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n",
"oneOf": [
{
"$ref": "#/components/schemas/StackedLineBuilderChartConfig"
},
{
"$ref": "#/components/schemas/StackedLineRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/StackedLineRawSqlChartConfig"
}
}
},
"OnClickFilterTemplate": {
"type": "object",
"description": "A templated filter applied to the link-out destination. The rendered template value is combined with the expression as `expression IN (...)` on the destination search or dashboard. Multiple templates sharing the same expression are merged into a single IN clause.\n",
Expand Down Expand Up @@ -2989,14 +3131,17 @@
}
},
"TileConfig": {
"description": "Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. For displayTypes that support both builder and Raw SQL modes (line, stacked_bar, table, number, pie, bar), configType is the secondary discriminant: omit it for the builder variant or set it to \"sql\" for the Raw SQL variant. The heatmap, search, event_patterns, and markdown displayTypes only have a builder variant.\n",
"description": "Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. For displayTypes that support both builder and Raw SQL modes (line, stacked_bar, stacked_line, table, number, pie, bar), configType is the secondary discriminant: omit it for the builder variant or set it to \"sql\" for the Raw SQL variant. The heatmap, search, event_patterns, and markdown displayTypes only have a builder variant.\n",
"oneOf": [
{
"$ref": "#/components/schemas/LineChartConfig"
},
{
"$ref": "#/components/schemas/BarChartConfig"
},
{
"$ref": "#/components/schemas/StackedLineChartConfig"
},
{
"$ref": "#/components/schemas/TableChartConfig"
},
Expand Down Expand Up @@ -3027,6 +3172,7 @@
"mapping": {
"line": "#/components/schemas/LineChartConfig",
"stacked_bar": "#/components/schemas/BarChartConfig",
"stacked_line": "#/components/schemas/StackedLineChartConfig",
"table": "#/components/schemas/TableChartConfig",
"number": "#/components/schemas/NumberChartConfig",
"pie": "#/components/schemas/PieChartConfig",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1006,6 +1006,10 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
numberFormat,
seriesLimit: 3,
};
const stackedLineConfig = {
...barConfig,
displayType: 'stacked_line' as const,
};
const tableConfig = {
displayType: 'table' as const,
sourceId,
Expand Down Expand Up @@ -1053,6 +1057,7 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
const tiles = [
{ name: 'Line', config: lineConfig },
{ name: 'Bar', config: barConfig },
{ name: 'Stacked Line', config: stackedLineConfig },
{ name: 'Table', config: tableConfig },
{ name: 'Pie', config: pieConfig },
{ name: 'Categorical Bar', config: categoricalBarConfig },
Expand All @@ -1061,6 +1066,7 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
const configByName: Record<string, object> = {
Line: lineConfig,
Bar: barConfig,
'Stacked Line': stackedLineConfig,
Table: tableConfig,
Pie: pieConfig,
'Categorical Bar': categoricalBarConfig,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ describe('tile-level where rejection (builder tiles)', () => {
const builderTypes = [
{ displayType: 'line' },
{ displayType: 'stacked_bar' },
{ displayType: 'stacked_line' },
{ displayType: 'table', extra: { groupBy: 'SpanName' } },
{ displayType: 'number' },
{ displayType: 'pie', extra: { groupBy: 'SpanName' } },
Expand Down Expand Up @@ -384,6 +385,13 @@ describe('getRawSqlTileMacroHints', () => {
'SELECT $__timeInterval(Timestamp) AS ts, count() FROM $__sourceTable ' +
'WHERE $__timeFilter(Timestamp) AND $__filters GROUP BY ts',
}),
makeSqlTile({
Comment thread
pulpdrew marked this conversation as resolved.
Resolved
displayType: 'stacked_line',
sourceId,
sqlTemplate:
'SELECT $__timeInterval(Timestamp) AS ts, count() FROM $__sourceTable ' +
'WHERE $__timeFilter(Timestamp) AND $__filters GROUP BY ts',
}),
]),
).toEqual([]);
});
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/prompts/dashboards/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ Recommended pattern:
Use BUILDER tiles (with sourceId) for most cases:
line Time-series trends (error rate, request volume, latency over time).
stacked_bar Compare categories over time (requests by service, errors by status code).
stacked_line Same as stacked_bar but as filled area bands (smooth cumulative totals).
number Single KPI metric (total requests, current error rate, p99 latency).
table Ranked lists (top endpoints by latency, error counts by service). Tables can wire row-click navigation via config.onClick to the /search page or another dashboard. See "TABLE TILE LINKING" below.
pie Proportional breakdowns (traffic share by service, errors by type). Keep slice count under 8.
Expand All @@ -67,7 +68,7 @@ Use BUILDER tiles (with sourceId) for most cases:
markdown Use sparingly. The dashboard already shows its name in the title bar at the top; do NOT add a "About this dashboard" tile that repeats it. Markdown bodies render h1/h2/h3 headings at title-bar scale, so a single \`## Service Catalog\` line eats most of the tile and pushes real KPIs below the fold. Skip markdown tiles for starter dashboards. If you must add one, size it to fit the text (h: 2-3 for a line or two; h: 1 clips it), use plain prose, no \`#\`/\`##\`/\`###\` headings. Use containers/tabs for section grouping instead.

Use RAW SQL tiles (with connectionId) only for queries the builder cannot express:
Requires configType: "sql" plus a displayType (line, stacked_bar, table, number, pie, bar).
Requires configType: "sql" plus a displayType (line, stacked_bar, stacked_line, table, number, pie, bar).
Use when you need JOINs, sub-queries, CTEs, or expressions the builder does not generate.
ALWAYS set sourceId on a raw SQL tile (in addition to connectionId) UNLESS the query reads
from multiple tables (e.g. JOINs across sources). sourceId enables the $__filters and
Expand Down
15 changes: 11 additions & 4 deletions packages/api/src/mcp/tools/alerts/schemas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import {
mcpLineTileSchema,
mcpNumberTileSchema,
mcpSqlTileSchema,
mcpStackedLineTileSchema,
} from '@/mcp/tools/dashboards/schemas';

// ---------------------------------------------------------------------------
Expand All @@ -28,7 +29,8 @@ import {

// Inline alerts carry their chart config in the same dialect as dashboard
// tile configs, restricted to the display types the alert evaluator can run
// as a time series: line, stacked_bar, and number (builder or raw SQL).
// as a time series: line, stacked_bar, stacked_line, and number (builder or
// raw SQL).
// Reuses the dashboard tile config shapes so agents author both from one
// vocabulary; the raw SQL variant narrows displayType and drops the
// tile-only onClick affordance. Full validation (formulas, number
Expand Down Expand Up @@ -78,6 +80,11 @@ const mcpAlertChartConfigSchema = z
where: mcpAlertChartLevelWhereSchema,
whereLanguage: SearchConditionTrimmedLanguageSchema.optional(),
}),
mcpStackedLineTileSchema.shape.config.extend({
name: mcpAlertChartConfigNameSchema,
where: mcpAlertChartLevelWhereSchema,
whereLanguage: SearchConditionTrimmedLanguageSchema.optional(),
}),
mcpNumberTileSchema.shape.config.extend({
name: mcpAlertChartConfigNameSchema,
where: mcpAlertChartLevelWhereSchema,
Expand All @@ -88,16 +95,16 @@ const mcpAlertChartConfigSchema = z
where: rejectedRawSqlAlertWhereField,
whereLanguage: rejectedRawSqlAlertWhereField,
displayType: z
.enum(['line', 'stacked_bar', 'number'])
.enum(['line', 'stacked_bar', 'stacked_line', 'number'])
.describe(
'How to render the SQL results. Alerts evaluate line, stacked_bar, or number charts only.',
'How to render the SQL results. Alerts evaluate line, stacked_bar, stacked_line, or number charts only.',
),
}),
])
.describe(
'Chart configuration for inline alerts (required when source is "inline"). ' +
'Same shape as a dashboard tile config, limited to displayType line, ' +
'stacked_bar, or number. Omit configType for the builder variant ' +
'stacked_bar, stacked_line, or number. Omit configType for the builder variant ' +
'(sourceId + select); set configType to "sql" for the Raw SQL variant ' +
'(connectionId + sqlTemplate; the template must use the $__timeFilter ' +
'and $__timeInterval macros so each evaluation window can be queried).',
Expand Down
Loading
Loading