You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d323769
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: packages/api/openapi.json
+73-2Lines changed: 73 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -2225,14 +2225,14 @@
2225
2225
}
2226
2226
}
2227
2227
},
2228
-
"HeatmapChartConfig": {
2228
+
"HeatmapDistributionChartConfig": {
2229
2229
"type": "object",
2230
2230
"required": [
2231
2231
"displayType",
2232
2232
"sourceId",
2233
2233
"select"
2234
2234
],
2235
-
"description": "Builder configuration for a heatmap tile. Heatmap is builder-only (no Raw SQL variant) and currently supports trace sources. The row-level filter lives at the chart-config level (where / whereLanguage), matching the HeatmapSeriesEditor in the UI.\n",
2235
+
"description": "Builder configuration for a distribution-mode heatmap tile, which buckets a numeric value on the y-axis. Requires a trace source. The row-level filter lives at the chart-config level (where / whereLanguage), matching the HeatmapSeriesEditor in the UI.\n",
2236
2236
"properties": {
2237
2237
"displayType": {
2238
2238
"type": "string",
@@ -2242,6 +2242,14 @@
2242
2242
"description": "Display type discriminator. Must be \"heatmap\" for heatmap tiles.",
2243
2243
"example": "heatmap"
2244
2244
},
2245
+
"heatmapMode": {
2246
+
"type": "string",
2247
+
"enum": [
2248
+
"distribution"
2249
+
],
2250
+
"description": "Heatmap mode. \"distribution\" is the default when omitted.",
2251
+
"example": "distribution"
2252
+
},
2245
2253
"sourceId": {
2246
2254
"type": "string",
2247
2255
"description": "ID of the data source to query.",
@@ -2274,6 +2282,69 @@
2274
2282
}
2275
2283
}
2276
2284
},
2285
+
"HeatmapSeriesChartConfig": {
2286
+
"type": "object",
2287
+
"required": [
2288
+
"displayType",
2289
+
"heatmapMode",
2290
+
"sourceId",
2291
+
"select"
2292
+
],
2293
+
"description": "Builder configuration for a series-mode heatmap tile, which shows one aggregated series per groupBy value as a row on the y-axis. Requires a trace, log, or metric source. Any filter lives on the select item (where / whereLanguage).\n",
2294
+
"properties": {
2295
+
"displayType": {
2296
+
"type": "string",
2297
+
"enum": [
2298
+
"heatmap"
2299
+
],
2300
+
"description": "Display type discriminator. Must be \"heatmap\" for heatmap tiles.",
2301
+
"example": "heatmap"
2302
+
},
2303
+
"heatmapMode": {
2304
+
"type": "string",
2305
+
"enum": [
2306
+
"series"
2307
+
],
2308
+
"description": "Heatmap mode. Must be \"series\" for series heatmaps.",
2309
+
"example": "series"
2310
+
},
2311
+
"sourceId": {
2312
+
"type": "string",
2313
+
"description": "ID of the data source to query.",
2314
+
"example": "65f5e4a3b9e77c001a111111"
2315
+
},
2316
+
"select": {
2317
+
"type": "array",
2318
+
"minItems": 1,
2319
+
"maxItems": 1,
2320
+
"description": "Exactly one aggregated value used to color each cell.",
2321
+
"items": {
2322
+
"$ref": "#/components/schemas/SelectItem"
2323
+
}
2324
+
},
2325
+
"groupBy": {
2326
+
"type": "string",
2327
+
"maxLength": 10000,
2328
+
"description": "Field expression to group results by (one row per group value).",
2329
+
"example": "ServiceName"
2330
+
},
2331
+
"numberFormat": {
2332
+
"$ref": "#/components/schemas/NumberFormat",
2333
+
"description": "Number formatting options for displayed values."
2334
+
}
2335
+
}
2336
+
},
2337
+
"HeatmapChartConfig": {
2338
+
"description": "Heatmap tile. Heatmap is builder-only (no Raw SQL variant). Omit heatmapMode (or set it to \"distribution\") for the distribution variant; set heatmapMode to \"series\" for the series variant.\n",
Copy file name to clipboardExpand all lines: packages/api/src/mcp/prompts/dashboards/content.ts
+4-3Lines changed: 4 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -62,6 +62,7 @@ Use BUILDER tiles (with sourceId) for most cases:
62
62
pie Proportional breakdowns (traffic share by service, errors by type). Keep slice count under 8.
63
63
bar Categorical comparisons (request counts by service, errors by endpoint). One bar per group value; not a time series (use stacked_bar for that).
64
64
heatmap Distribution of a numeric value over time (latency buckets, payload size). Trace sources only. Requires non-empty valueExpression.
65
+
With heatmapMode: "series": one row per groupBy value, colored by a normal select item. Trace, Log, or Metric sources.
65
66
search Browse raw log/event rows (error logs, recent traces).
66
67
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.
67
68
@@ -88,7 +89,7 @@ Apply these before calling clickstack_save_dashboard. Each rule is enforced by t
88
89
89
90
1. ONE QUESTION PER DASHBOARD. A dashboard answers a single observability question well. Split if the request mixes traces, logs, and metrics into unrelated views.
90
91
91
-
2. ALIAS EVERY SELECT ITEM. Every entry in select MUST carry an alias. Tables, lines, stacked_bars, pies, AND number tiles. The number-tile case is the one most often missed because the rendered UI uses the tile's name (not the column alias), so the absence looks invisible; the underlying query still emits a raw-expression column name (count(), quantile(0.95)(Duration)), which breaks orderBy references, CSV export, and any downstream onClick template that references the column by name. Treat "no alias" as a save-time bug, not a style nit. Heatmap is the only exception: heatmap select items take a valueExpression and no alias.
92
+
2. ALIAS EVERY SELECT ITEM. Every entry in select MUST carry an alias. Tables, lines, stacked_bars, pies, AND number tiles. The number-tile case is the one most often missed because the rendered UI uses the tile's name (not the column alias), so the absence looks invisible; the underlying query still emits a raw-expression column name (count(), quantile(0.95)(Duration)), which breaks orderBy references, CSV export, and any downstream onClick template that references the column by name. Treat "no alias" as a save-time bug, not a style nit. Distribution heatmaps are the only exception: their select items take a valueExpression and no alias.
@@ -139,7 +140,7 @@ Apply these before calling clickstack_save_dashboard. Each rule is enforced by t
139
140
140
141
14. SIZE TILES TO FIT THEIR CONTENT. The layout w/h are not one-size-fits-all; a tile that is too short clips its content (a table loses rows below the fold, a number tile crops its label) and one that is too wide wastes the row. Match the size to the displayType: number tiles stay small (w 6-8, h 3-4) so three or four KPIs share a row; line / stacked_bar / pie / bar want w 8-12 and h 4-6; tables and search lists want the full row (w 24) and h 6-10 so rows are not cut off; heatmaps want w 12 and h 5-6; a markdown note wants h 2-3 (never h 1, which clips the text). The per-field w/h descriptions on the tile schema carry the same per-displayType ranges; reach for them instead of leaving every tile at the 12x4 default.
141
142
142
-
15. FILTER A BUILDER TILE ON THE SELECT ITEM, NOT THE TILE. To scope a table / line / stacked_bar / number / pie / bar tile to a subset of rows (a service, an error status), put the filter on EACH select item's where: select: [{ aggFn: "count", where: "ServiceName:payment", whereLanguage: "lucene", alias: "..." }]. The chart editor renders that per-series where as the tile's visible "Where" box, so the user can see and edit it. Do NOT put a filter at the tile config's top level for these types: the editor does not show it, so it is ignored. For a whole-dashboard scope use a dashboard-level filter (gotcha 9). The only display types with a tile-level where are search, heatmap, and event_patterns, where the editor does render it.
143
+
15. FILTER A BUILDER TILE ON THE SELECT ITEM, NOT THE TILE. To scope a table / line / stacked_bar / number / pie / bar tile to a subset of rows (a service, an error status), put the filter on EACH select item's where: select: [{ aggFn: "count", where: "ServiceName:payment", whereLanguage: "lucene", alias: "..." }]. The chart editor renders that per-series where as the tile's visible "Where" box, so the user can see and edit it. Do NOT put a filter at the tile config's top level for these types: the editor does not show it, so it is ignored. For a whole-dashboard scope use a dashboard-level filter (gotcha 9). The only display types with a tile-level where are search, distribution heatmap, and event_patterns, where the editor does render it. Series heatmaps filter on the select item like the other builder types.
143
144
144
145
== ADAPT, DO NOT COPY ==
145
146
@@ -165,7 +166,7 @@ Dashboards open with a 15-minute default window. There is no dashboard-level fie
165
166
- Multiple select items on number / pie / bar / heatmap tiles (each takes exactly one).
166
167
- Missing level on aggFn "quantile" (must specify 0.5, 0.9, 0.95, or 0.99).
167
168
- Assuming StatusCode or SeverityText values (always inspect lowCardinalityValues from clickstack_describe_source).
168
-
- Heatmap on a non-Trace source (heatmap is Trace-only today).
169
+
- Distribution heatmap on a non-Trace source, or series heatmap on a source that is not Trace, Log, or Metric.
169
170
- Hardcoding a focus dimension into every tile's where clause (use a dashboard-level filter instead).
170
171
- Putting a filter at the tile-config top level on a table / line / stacked_bar / number / pie / bar tile (ignored for these types; put the where on each select item instead, see gotcha 15).
171
172
- Enabling both isBroadcastEnabled and isVariableEnabled on one filter (the picked value is then applied twice; set isBroadcastEnabled: false when you add a variable). The exception is rule 9c: a variable read only by another filter's where never reaches a tile, so that filter can keep broadcasting.
0 commit comments