diff --git a/docs/src/content/docs/agent-guidance.md b/docs/src/content/docs/agent-guidance.md index 5a31bfd8..12cc3e60 100644 --- 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 "Error Count" --display big_number --query count +sentry dashboard widget add "P95 Duration" --display big_number --query p95:span.duration +sentry dashboard widget add "Throughput" --display big_number --query epm + +# 2 charts filling one row (3+3 = 6) +sentry dashboard widget add "Errors Over Time" --display line --query count +sentry dashboard widget add "Latency Over Time" --display line --query p95:span.duration + +# Full-width table (6 = 6) +sentry dashboard widget add "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 index 09ec0e10..337dd3a6 100644 --- 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 "Error Count" --display big_number --query count +sentry dashboard widget add "P95 Duration" --display big_number --query p95:span.duration +sentry dashboard widget add "Throughput" --display big_number --query epm + +# 2 charts filling one row (3+3 = 6) +sentry dashboard widget add "Errors Over Time" --display line --query count +sentry dashboard widget add "Latency Over Time" --display line --query p95:span.duration + +# Full-width table (6 = 6) +sentry dashboard widget add "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 index c53562b7..bfa56534 100644 --- 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 - Display type (line, bar, table, big_number, ...)` +- `-d, --display - 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 - Widget dataset (default: spans)` - `-q, --query ... - Aggregate expression (e.g. count, p95:span.duration)` - `-w, --where - Search conditions filter (e.g. is:unresolved)` @@ -106,7 +106,7 @@ Edit a widget in a dashboard - `-i, --index - Widget index (0-based)` - `-t, --title - Widget title to match` - `--new-title - New widget title` -- `-d, --display - Display type (line, bar, table, big_number, ...)` +- `-d, --display - 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 - Widget dataset (default: spans)` - `-q, --query ... - Aggregate expression (e.g. count, p95:span.duration)` - `-w, --where - Search conditions filter (e.g. is:unresolved)` diff --git a/src/commands/dashboard/widget/add.ts b/src/commands/dashboard/widget/add.ts index d62ff2b0..8938d3cb 100644 --- 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 index 54342b3f..a3b1d157 100644 --- 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 index a3e4144c..facdc39b 100644 --- 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 "Error Count" --display big_number --query count\n' + + ' sentry dashboard widget add "P95" --display big_number --query p95:span.duration\n' + + ' sentry dashboard widget add "Throughput" --display big_number --query epm\n\n' + + " # 2 charts (3+3 = 6)\n" + + ' sentry dashboard widget add "Errors" --display line --query count\n' + + ' sentry dashboard widget add "Latency" --display line --query p95:span.duration\n\n' + + " # Full-width table (6 = 6)\n" + + ' sentry dashboard widget add "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" +