feat(dashboard): add layout guidance and widget type reference for agents (#521)

betegon · claude · web-flow · commit ccabec3212d6 · 2026-03-20T21:12:30.000+01:00
## Summary Agents creating dashboards don't know about the 6-column grid layout, available display types, or their default sizes. This surfaces all that info where agents naturally look: - `sentry dashboard widget --help` now includes display types with default grid sizes, datasets, aggregate functions, aliases, and row-filling examples - Agent guidance (embedded in SKILL.md) gets a "Dashboard Layout" section with the full display type table and examples - `--display` flag brief expanded to show 8 types instead of 4 ## Test plan - [ ] `bun test test/commands/dashboard/` — all dashboard tests pass - [ ] `bun run typecheck && bun run lint` — clean - [ ] `bun src/bin.ts dashboard widget --help` — shows full layout/types/aggregates info - [ ] `bun run check:skill` — skill files up to date 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/docs/src/content/docs/agent-guidance.md b/docs/src/content/docs/agent-guidance.md
@@ -102,6 +102,53 @@ sentry api /api/0/organizations/my-org/
 sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'
 ```
 
+## Dashboard Layout
+
+Sentry dashboards use a **6-column grid**. When adding widgets, aim to fill complete rows (widths should sum to 6).
+
+Display types with default sizes:
+
+| Display Type | Width | Height | Category | Notes |
+|---|---|---|---|---|
+| `big_number` | 2 | 1 | common | Compact KPI — place 3 per row (2+2+2=6) |
+| `line` | 3 | 2 | common | Half-width chart — place 2 per row (3+3=6) |
+| `area` | 3 | 2 | common | Half-width chart — place 2 per row |
+| `bar` | 3 | 2 | common | Half-width chart — place 2 per row |
+| `table` | 6 | 2 | common | Full-width — always takes its own row |
+| `stacked_area` | 3 | 2 | specialized | Stacked area chart |
+| `top_n` | 3 | 2 | specialized | Top N ranked list |
+| `categorical_bar` | 3 | 2 | specialized | Categorical bar chart |
+| `text` | 3 | 2 | specialized | Static text/markdown widget |
+| `details` | 3 | 2 | internal | Detail view |
+| `wheel` | 3 | 2 | internal | Pie/wheel chart |
+| `rage_and_dead_clicks` | 3 | 2 | internal | Rage/dead click visualization |
+| `server_tree` | 3 | 2 | internal | Hierarchical tree display |
+| `agents_traces_table` | 3 | 2 | internal | Agents traces table |
+
+Use **common** types for general dashboards. Use **specialized** only when specifically requested. Avoid **internal** types unless the user explicitly asks.
+
+Available datasets: `spans` (default, covers most use cases), `discover`, `issue`, `error-events`, `transaction-like`, `metrics`, `logs`.
+
+Run `sentry dashboard widget --help` for the full list including aggregate functions.
+
+**Row-filling examples:**
+
+```bash
+# 3 KPIs filling one row (2+2+2 = 6)
+sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
+sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
+sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm
+
+# 2 charts filling one row (3+3 = 6)
+sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
+sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration
+
+# Full-width table (6 = 6)
+sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
+  --query count --query p95:span.duration \
+  --group-by transaction --sort -count --limit 10
+```
+
 ## Common Mistakes
 
 - **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.
diff --git a/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/plugins/sentry-cli/skills/sentry-cli/SKILL.md
@@ -112,6 +112,53 @@ sentry api /api/0/organizations/my-org/
 sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'
 ```
 
+### Dashboard Layout
+
+Sentry dashboards use a **6-column grid**. When adding widgets, aim to fill complete rows (widths should sum to 6).
+
+Display types with default sizes:
+
+| Display Type | Width | Height | Category | Notes |
+|---|---|---|---|---|
+| `big_number` | 2 | 1 | common | Compact KPI — place 3 per row (2+2+2=6) |
+| `line` | 3 | 2 | common | Half-width chart — place 2 per row (3+3=6) |
+| `area` | 3 | 2 | common | Half-width chart — place 2 per row |
+| `bar` | 3 | 2 | common | Half-width chart — place 2 per row |
+| `table` | 6 | 2 | common | Full-width — always takes its own row |
+| `stacked_area` | 3 | 2 | specialized | Stacked area chart |
+| `top_n` | 3 | 2 | specialized | Top N ranked list |
+| `categorical_bar` | 3 | 2 | specialized | Categorical bar chart |
+| `text` | 3 | 2 | specialized | Static text/markdown widget |
+| `details` | 3 | 2 | internal | Detail view |
+| `wheel` | 3 | 2 | internal | Pie/wheel chart |
+| `rage_and_dead_clicks` | 3 | 2 | internal | Rage/dead click visualization |
+| `server_tree` | 3 | 2 | internal | Hierarchical tree display |
+| `agents_traces_table` | 3 | 2 | internal | Agents traces table |
+
+Use **common** types for general dashboards. Use **specialized** only when specifically requested. Avoid **internal** types unless the user explicitly asks.
+
+Available datasets: `spans` (default, covers most use cases), `discover`, `issue`, `error-events`, `transaction-like`, `metrics`, `logs`.
+
+Run `sentry dashboard widget --help` for the full list including aggregate functions.
+
+**Row-filling examples:**
+
+```bash
+# 3 KPIs filling one row (2+2+2 = 6)
+sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
+sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
+sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm
+
+# 2 charts filling one row (3+3 = 6)
+sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
+sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration
+
+# Full-width table (6 = 6)
+sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
+  --query count --query p95:span.duration \
+  --group-by transaction --sort -count --limit 10
+```
+
 ### Common Mistakes
 
 - **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.
diff --git a/plugins/sentry-cli/skills/sentry-cli/references/dashboards.md b/plugins/sentry-cli/skills/sentry-cli/references/dashboards.md
@@ -90,7 +90,7 @@ sentry dashboard widget add 'Frontend Performance' "Error Count" --display big_n
 Add a widget to a dashboard
 
 **Flags:**
-- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
+- `-d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)`
 - `--dataset <value> - Widget dataset (default: spans)`
 - `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
 - `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
@@ -106,7 +106,7 @@ Edit a widget in a dashboard
 - `-i, --index <value> - Widget index (0-based)`
 - `-t, --title <value> - Widget title to match`
 - `--new-title <value> - New widget title`
-- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
+- `-d, --display <value> - Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)`
 - `--dataset <value> - Widget dataset (default: spans)`
 - `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
 - `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
diff --git a/src/commands/dashboard/widget/add.ts b/src/commands/dashboard/widget/add.ts
@@ -105,7 +105,8 @@ export const addCommand = buildCommand({
       display: {
         kind: "parsed",
         parse: String,
-        brief: "Display type (line, bar, table, big_number, ...)",
+        brief:
+          "Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)",
       },
       dataset: {
         kind: "parsed",
diff --git a/src/commands/dashboard/widget/edit.ts b/src/commands/dashboard/widget/edit.ts
@@ -156,7 +156,8 @@ export const editCommand = buildCommand({
       display: {
         kind: "parsed",
         parse: String,
-        brief: "Display type (line, bar, table, big_number, ...)",
+        brief:
+          "Display type (big_number, line, area, bar, table, stacked_area, top_n, text, categorical_bar, details, wheel, rage_and_dead_clicks, server_tree, agents_traces_table)",
         optional: true,
       },
       dataset: {
diff --git a/src/commands/dashboard/widget/index.ts b/src/commands/dashboard/widget/index.ts
@@ -13,6 +13,33 @@ export const widgetRoute = buildRouteMap({
     brief: "Manage dashboard widgets",
     fullDescription:
       "Add, edit, or delete widgets in a Sentry dashboard.\n\n" +
+      "Dashboards use a 6-column grid. Widget widths should sum to 6 per row.\n\n" +
+      "Display types (width × height):\n" +
+      "  common:      big_number (2×1), line (3×2), area (3×2), bar (3×2), table (6×2)\n" +
+      "  specialized: stacked_area (3×2), top_n (3×2), categorical_bar (3×2), text (3×2)\n" +
+      "  internal:    details (3×2), wheel (3×2), rage_and_dead_clicks (3×2),\n" +
+      "               server_tree (3×2), agents_traces_table (3×2)\n\n" +
+      "Datasets: spans (default), discover, issue, error-events, transaction-like,\n" +
+      "          metrics, logs, tracemetrics, preprod-app-size\n\n" +
+      "Aggregates (spans): count, count_unique, sum, avg, percentile, p50, p75,\n" +
+      "  p90, p95, p99, p100, eps, epm, any, min, max\n" +
+      "Aggregates (discover adds): failure_count, failure_rate, apdex,\n" +
+      "  count_miserable, user_misery, count_web_vitals, count_if, count_at_least,\n" +
+      "  last_seen, latest_event, var, stddev, cov, corr, performance_score,\n" +
+      "  opportunity_score, count_scores\n" +
+      "Aliases: spm → epm, sps → eps, tpm → epm, tps → eps\n\n" +
+      "Row-filling examples:\n" +
+      "  # 3 KPIs (2+2+2 = 6)\n" +
+      '  sentry dashboard widget add <d> "Error Count" --display big_number --query count\n' +
+      '  sentry dashboard widget add <d> "P95" --display big_number --query p95:span.duration\n' +
+      '  sentry dashboard widget add <d> "Throughput" --display big_number --query epm\n\n' +
+      "  # 2 charts (3+3 = 6)\n" +
+      '  sentry dashboard widget add <d> "Errors" --display line --query count\n' +
+      '  sentry dashboard widget add <d> "Latency" --display line --query p95:span.duration\n\n' +
+      "  # Full-width table (6 = 6)\n" +
+      '  sentry dashboard widget add <d> "Top Endpoints" --display table \\\n' +
+      "    --query count --query p95:span.duration --group-by transaction \\\n" +
+      "    --sort -count --limit 10\n\n" +
       "Commands:\n" +
       "  add    Add a widget to a dashboard\n" +
       "  edit   Edit a widget in a dashboard\n" +
