Skip to content

Commit ccabec3

Browse files
betegonclaude
betegon
and
claude
authored
feat(dashboard): add layout guidance and widget type reference for agents (#521)
## 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>
1 parent 112c078 commit ccabec3

6 files changed

Lines changed: 127 additions & 4 deletions

File tree

‎docs/src/content/docs/agent-guidance.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,53 @@ sentry api /api/0/organizations/my-org/
102102
sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'
103103
```
104104

105+
## Dashboard Layout
106+
107+
Sentry dashboards use a **6-column grid**. When adding widgets, aim to fill complete rows (widths should sum to 6).
108+
109+
Display types with default sizes:
110+
111+
| Display Type | Width | Height | Category | Notes |
112+
|---|---|---|---|---|
113+
| `big_number` | 2 | 1 | common | Compact KPI — place 3 per row (2+2+2=6) |
114+
| `line` | 3 | 2 | common | Half-width chart — place 2 per row (3+3=6) |
115+
| `area` | 3 | 2 | common | Half-width chart — place 2 per row |
116+
| `bar` | 3 | 2 | common | Half-width chart — place 2 per row |
117+
| `table` | 6 | 2 | common | Full-width — always takes its own row |
118+
| `stacked_area` | 3 | 2 | specialized | Stacked area chart |
119+
| `top_n` | 3 | 2 | specialized | Top N ranked list |
120+
| `categorical_bar` | 3 | 2 | specialized | Categorical bar chart |
121+
| `text` | 3 | 2 | specialized | Static text/markdown widget |
122+
| `details` | 3 | 2 | internal | Detail view |
123+
| `wheel` | 3 | 2 | internal | Pie/wheel chart |
124+
| `rage_and_dead_clicks` | 3 | 2 | internal | Rage/dead click visualization |
125+
| `server_tree` | 3 | 2 | internal | Hierarchical tree display |
126+
| `agents_traces_table` | 3 | 2 | internal | Agents traces table |
127+
128+
Use **common** types for general dashboards. Use **specialized** only when specifically requested. Avoid **internal** types unless the user explicitly asks.
129+
130+
Available datasets: `spans` (default, covers most use cases), `discover`, `issue`, `error-events`, `transaction-like`, `metrics`, `logs`.
131+
132+
Run `sentry dashboard widget --help` for the full list including aggregate functions.
133+
134+
**Row-filling examples:**
135+
136+
```bash
137+
# 3 KPIs filling one row (2+2+2 = 6)
138+
sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
139+
sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
140+
sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm
141+
142+
# 2 charts filling one row (3+3 = 6)
143+
sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
144+
sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration
145+
146+
# Full-width table (6 = 6)
147+
sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
148+
--query count --query p95:span.duration \
149+
--group-by transaction --sort -count --limit 10
150+
```
151+
105152
## Common Mistakes
106153

107154
- **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.

‎plugins/sentry-cli/skills/sentry-cli/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,53 @@ sentry api /api/0/organizations/my-org/
112112
sentry api /api/0/organizations/my-org/projects/ --method POST --data '{"name":"new-project","platform":"python"}'
113113
```
114114

115+
### Dashboard Layout
116+
117+
Sentry dashboards use a **6-column grid**. When adding widgets, aim to fill complete rows (widths should sum to 6).
118+
119+
Display types with default sizes:
120+
121+
| Display Type | Width | Height | Category | Notes |
122+
|---|---|---|---|---|
123+
| `big_number` | 2 | 1 | common | Compact KPI — place 3 per row (2+2+2=6) |
124+
| `line` | 3 | 2 | common | Half-width chart — place 2 per row (3+3=6) |
125+
| `area` | 3 | 2 | common | Half-width chart — place 2 per row |
126+
| `bar` | 3 | 2 | common | Half-width chart — place 2 per row |
127+
| `table` | 6 | 2 | common | Full-width — always takes its own row |
128+
| `stacked_area` | 3 | 2 | specialized | Stacked area chart |
129+
| `top_n` | 3 | 2 | specialized | Top N ranked list |
130+
| `categorical_bar` | 3 | 2 | specialized | Categorical bar chart |
131+
| `text` | 3 | 2 | specialized | Static text/markdown widget |
132+
| `details` | 3 | 2 | internal | Detail view |
133+
| `wheel` | 3 | 2 | internal | Pie/wheel chart |
134+
| `rage_and_dead_clicks` | 3 | 2 | internal | Rage/dead click visualization |
135+
| `server_tree` | 3 | 2 | internal | Hierarchical tree display |
136+
| `agents_traces_table` | 3 | 2 | internal | Agents traces table |
137+
138+
Use **common** types for general dashboards. Use **specialized** only when specifically requested. Avoid **internal** types unless the user explicitly asks.
139+
140+
Available datasets: `spans` (default, covers most use cases), `discover`, `issue`, `error-events`, `transaction-like`, `metrics`, `logs`.
141+
142+
Run `sentry dashboard widget --help` for the full list including aggregate functions.
143+
144+
**Row-filling examples:**
145+
146+
```bash
147+
# 3 KPIs filling one row (2+2+2 = 6)
148+
sentry dashboard widget add <dashboard> "Error Count" --display big_number --query count
149+
sentry dashboard widget add <dashboard> "P95 Duration" --display big_number --query p95:span.duration
150+
sentry dashboard widget add <dashboard> "Throughput" --display big_number --query epm
151+
152+
# 2 charts filling one row (3+3 = 6)
153+
sentry dashboard widget add <dashboard> "Errors Over Time" --display line --query count
154+
sentry dashboard widget add <dashboard> "Latency Over Time" --display line --query p95:span.duration
155+
156+
# Full-width table (6 = 6)
157+
sentry dashboard widget add <dashboard> "Top Endpoints" --display table \
158+
--query count --query p95:span.duration \
159+
--group-by transaction --sort -count --limit 10
160+
```
161+
115162
### Common Mistakes
116163

117164
- **Wrong issue ID format**: Use `PROJECT-123` (short ID), not the numeric ID `123456789`. The short ID includes the project prefix.

‎plugins/sentry-cli/skills/sentry-cli/references/dashboards.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ sentry dashboard widget add 'Frontend Performance' "Error Count" --display big_n
9090
Add a widget to a dashboard
9191

9292
**Flags:**
93-
- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
93+
- `-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)`
9494
- `--dataset <value> - Widget dataset (default: spans)`
9595
- `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
9696
- `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`
@@ -106,7 +106,7 @@ Edit a widget in a dashboard
106106
- `-i, --index <value> - Widget index (0-based)`
107107
- `-t, --title <value> - Widget title to match`
108108
- `--new-title <value> - New widget title`
109-
- `-d, --display <value> - Display type (line, bar, table, big_number, ...)`
109+
- `-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)`
110110
- `--dataset <value> - Widget dataset (default: spans)`
111111
- `-q, --query <value>... - Aggregate expression (e.g. count, p95:span.duration)`
112112
- `-w, --where <value> - Search conditions filter (e.g. is:unresolved)`

‎src/commands/dashboard/widget/add.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,8 @@ export const addCommand = buildCommand({
105105
display: {
106106
kind: "parsed",
107107
parse: String,
108-
brief: "Display type (line, bar, table, big_number, ...)",
108+
brief:
109+
"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)",
109110
},
110111
dataset: {
111112
kind: "parsed",

‎src/commands/dashboard/widget/edit.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,8 @@ export const editCommand = buildCommand({
156156
display: {
157157
kind: "parsed",
158158
parse: String,
159-
brief: "Display type (line, bar, table, big_number, ...)",
159+
brief:
160+
"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)",
160161
optional: true,
161162
},
162163
dataset: {

‎src/commands/dashboard/widget/index.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,33 @@ export const widgetRoute = buildRouteMap({
1313
brief: "Manage dashboard widgets",
1414
fullDescription:
1515
"Add, edit, or delete widgets in a Sentry dashboard.\n\n" +
16+
"Dashboards use a 6-column grid. Widget widths should sum to 6 per row.\n\n" +
17+
"Display types (width × height):\n" +
18+
" common: big_number (2×1), line (3×2), area (3×2), bar (3×2), table (6×2)\n" +
19+
" specialized: stacked_area (3×2), top_n (3×2), categorical_bar (3×2), text (3×2)\n" +
20+
" internal: details (3×2), wheel (3×2), rage_and_dead_clicks (3×2),\n" +
21+
" server_tree (3×2), agents_traces_table (3×2)\n\n" +
22+
"Datasets: spans (default), discover, issue, error-events, transaction-like,\n" +
23+
" metrics, logs, tracemetrics, preprod-app-size\n\n" +
24+
"Aggregates (spans): count, count_unique, sum, avg, percentile, p50, p75,\n" +
25+
" p90, p95, p99, p100, eps, epm, any, min, max\n" +
26+
"Aggregates (discover adds): failure_count, failure_rate, apdex,\n" +
27+
" count_miserable, user_misery, count_web_vitals, count_if, count_at_least,\n" +
28+
" last_seen, latest_event, var, stddev, cov, corr, performance_score,\n" +
29+
" opportunity_score, count_scores\n" +
30+
"Aliases: spm → epm, sps → eps, tpm → epm, tps → eps\n\n" +
31+
"Row-filling examples:\n" +
32+
" # 3 KPIs (2+2+2 = 6)\n" +
33+
' sentry dashboard widget add <d> "Error Count" --display big_number --query count\n' +
34+
' sentry dashboard widget add <d> "P95" --display big_number --query p95:span.duration\n' +
35+
' sentry dashboard widget add <d> "Throughput" --display big_number --query epm\n\n' +
36+
" # 2 charts (3+3 = 6)\n" +
37+
' sentry dashboard widget add <d> "Errors" --display line --query count\n' +
38+
' sentry dashboard widget add <d> "Latency" --display line --query p95:span.duration\n\n' +
39+
" # Full-width table (6 = 6)\n" +
40+
' sentry dashboard widget add <d> "Top Endpoints" --display table \\\n' +
41+
" --query count --query p95:span.duration --group-by transaction \\\n" +
42+
" --sort -count --limit 10\n\n" +
1643
"Commands:\n" +
1744
" add Add a widget to a dashboard\n" +
1845
" edit Edit a widget in a dashboard\n" +

0 commit comments

Comments
 (0)