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
Design a dashboard layout that tells a clear story — from high-level health signals down to granular diagnostics — using proper widget types, group organization, and template variables for reusability.
19
19
20
-
**Important**: Always check for existing dashboards first with `pup dashboards list`. Do not create a new dashboard if one already exists for the same service or purpose — update the existing one instead. Only create a new dashboard when no relevant one exists or the user explicitly asks for a new one.
20
+
**Important**: Always check for existing dashboards first with `pup dashboards list --agent`. Do not create a new dashboard if one already exists for the same service or purpose — update the existing one instead. Only create a new dashboard when no relevant one exists or the user explicitly asks for a new one.
21
21
22
22
**Philosophy**: The frameworks, layouts, and widget guides in this skill are starting points — not rigid rules. Every product and business is different. Understand the domain first, then adapt the frameworks to fit. The best dashboards reflect how the business actually works, not how a generic template says they should.
23
23
@@ -38,7 +38,7 @@ First, determine the mode:
38
38
3.**Data Sources** — "Which Datadog products are involved? Metrics only, APM + Metrics, Logs + Metrics, or full stack?"
39
39
4.**Scope** — "Is this for a single service, a group of services, or infrastructure-wide?"
40
40
5.**Dashboard Strategy** — "One dashboard per service, or a consolidated view?" — share the trade-offs from [references/layouts.md](references/layouts.md) to help them decide. If unsure, ask: "During an outage, does your team investigate one service at a time, or do they need to see all services simultaneously?"
41
-
6.**Existing Dashboard** — "Is there an existing dashboard to audit or redesign?" If yes, fetch with `pup dashboards get <id>` before designing.
41
+
6.**Existing Dashboard** — "Is there an existing dashboard to audit or redesign?" If yes, fetch with `pup dashboards get <id> --agent` before designing.
42
42
43
43
### Audit Questions
44
44
@@ -80,8 +80,8 @@ Before designing, understand what you are building observability for. The metric
80
80
### 1. Gather existing context
81
81
82
82
```bash
83
-
pup dashboards list
84
-
pup dashboards get <dashboard-id>
83
+
pup dashboards list --agent
84
+
pup dashboards get <dashboard-id> --agent
85
85
```
86
86
87
87
If auditing an existing dashboard, fetch its definition first and analyze its current structure before redesigning.
@@ -92,10 +92,10 @@ Before designing widgets, check what metrics and tag values actually exist for t
92
92
93
93
```bash
94
94
# See what metrics are available for the service
95
-
pup metrics list --filter="<service-name>.*"
95
+
pup metrics list --filter="<service-name>.*" --agent
96
96
97
97
# Verify the service tag is active and see what metrics are flowing
98
-
pup metrics list --filter="trace.*" --tag-filter="service:<service-name>"
98
+
pup metrics list --filter="trace.*" --tag-filter="service:<service-name>" --agent
99
99
```
100
100
101
101
Use the actual metric names and tag values you find here when writing widget queries — do not guess or invent them. If a metric you expect does not appear, flag it to the user before building widgets around it.
@@ -159,15 +159,15 @@ These are guiding principles — not a rigid checklist. Apply judgment based on
159
159
160
160
```bash
161
161
# If given a service name, list all dashboards and identify the relevant one by title
162
-
pup dashboards list
162
+
pup dashboards list --agent
163
163
164
164
# If given a URL, extract the dashboard ID from the path (e.g., /dashboard/abc-def-ghi/...)
165
165
166
166
# Get the full dashboard definition (includes the dashboard URL in the response)
167
-
pup dashboards get <dashboard-id>
167
+
pup dashboards get <dashboard-id> --agent
168
168
169
169
# Verify real metric names exist
170
-
pup metrics list --filter="trace.http.request.*"
170
+
pup metrics list --filter="trace.http.request.*" --agent
171
171
```
172
172
173
173
Parse the response to build an inventory of all widgets, groups, and their configurations.
@@ -303,12 +303,12 @@ Compile all findings into a structured report:
303
303
304
304
## Quality Principles
305
305
306
-
-[ ] Widget queries use real metric names verified via `pup metrics list` — no invented metric names
306
+
-[ ] Widget queries use real metric names verified via `pup metrics list --agent` — no invented metric names
307
307
-[ ] Dashboard reflects the actual product and business — metrics tailored to the domain
308
308
-[ ] Dashboard title follows `[service] Purpose` pattern — no "Dashboard" suffix, no environment in the title
309
309
-[ ]`title` field updated in the JSON (not just the filename) — redeploy after any title change
310
310
-[ ] Template variables match the dashboard type — see [references/layouts.md](references/layouts.md)
311
-
-[ ] Widget queries use template variable scopes verified via `pup metrics list` — no hardcoded env, service, or host values; use the variable set appropriate for the dashboard type (see [references/layouts.md](references/layouts.md))
311
+
-[ ] Widget queries use template variable scopes verified via `pup metrics list --agent` — no hardcoded env, service, or host values; use the variable set appropriate for the dashboard type (see [references/layouts.md](references/layouts.md))
312
312
-[ ]**Business group** with 5-8 `B`-prefixed metrics tailored to the service's customer-visible outcomes
313
313
-[ ] Groups ordered macro-to-micro (business → overview → details)
314
314
-[ ]**Every widget title uses the layer-priority prefix** (`I0:`, `P1:`, `D0:`, `B0:`, etc.) — see [references/widgets.md](references/widgets.md)
0 commit comments