datadog-dashboards

Datadog Dashboards

The decisions Datadog forces when you build a dashboard, and how to settle them. Every rule names the wrong default it corrects; there is no rule for what the model already gets right.

Pinned to a date, not a version. Datadog ships continuously, so every claim here was verified against docs.datadoghq.com in July 2026. Re-verify before trusting anything version-shaped — deprecations here (q, default, is_read_only, week_before()) still parse today.

Assumes the Datadog MCP server is connected (https://mcp.<site>/v1/mcp, toolsets=dashboards,widgets). Widget schemas are deliberately not restated in this skill — get_widget_reference returns them current at call time, and a copy here would go stale. If the server is not connected, set it up first (ship-endpoint-follows-the-site); this skill does not cover Terraform or raw API management.

When to Apply

Use this skill when:

• Creating or editing a Datadog dashboard, or reviewing one someone else built — especially a board assembled programmatically rather than in the graph editor, which is where the .as_count() divergence bites
• Writing any Datadog query destined for a widget: metric queries with space aggregators and modifiers, or logs / spans / rum queries with search + compute + group_by
• Choosing between visualizations, or being handed a request that says "graph" but wants a ranking, a single number, or an error budget
• A dashboard shows numbers nobody trusts, panels that render "No data", or a value that changes when the time frame changes
• Asked for "a dashboard for X" with no stated audience — the interview in scope-ask-audience-and-decision runs before anything is built

This skill is NOT for:

• Managing dashboards through Terraform or the raw Dashboard API (this skill assumes the MCP server)
• Authoring monitors or defining SLOs — though scope-not-every-question-is-a-dashboard covers recognising when the request is one of those
• Datadog instrumentation: agent config, tracer setup, or deciding which metrics to emit in the first place
• Non-Datadog observability platforms — the query semantics here do not transfer

Rule Categories

#	Category	Prefix	Covers
1	Purpose & Scope	scope-	Audience, the decision it drives, variables over duplication, when it should not be a dashboard
2	Grounding in the Account	disco-	Confirming metrics, tags, and facets exist before querying them
3	Query Semantics	query-	The queries that return a number and are wrong
4	Choosing the Widget	widget-	Matching question to visualization; the pairs that are not interchangeable
5	Dashboard JSON	json-	What widget validation cannot see or cannot explain
6	Layout & Readability	layout-	Datadog's own standard for structure, display types, titles, sizing
7	Shipping It	ship-	Validate-and-smoke-test before writing; region endpoints

Quick Reference

1. Purpose & Scope

• scope-ask-audience-and-decision — Four questions before the first widget; the answers belong in description, not in chat
• scope-one-dashboard-many-variables — Six services is one dashboard; variable dropdowns only offer values the board's own widgets query
• scope-clone-before-building — Presets exist for 1000+ integrations and are invisible to GET /dashboard; search, don't list
• scope-not-every-question-is-a-dashboard — "Tell us when X" is a monitor; a narrative is a notebook

2. Grounding in the Account

• disco-never-invent-metric-names — A wrong metric name renders an empty graph, never an error
• disco-read-type-and-unit-first — DogStatsD increment() is stored as a RATE; type decides the modifier, unit decides the title
• disco-absence-is-not-proof — Metrics age out of discovery in 24h but are retained 15 months
• disco-log-attributes-need-facets — Unfaceted attributes cannot be grouped, and no API lists facets

3. Query Semantics

• query-append-as-count-explicitly — The costliest default. The UI appends .as_count(); the API does not, and rolls up with avg
• query-percentiles-require-distributions — p95: needs a distribution with percentiles enabled; avg: of a p95 is not a percentile
• query-aggregate-before-dividing — A ratio without .as_count() sums per-interval ratios and can read 150%
• query-gauge-gaps-are-interpolated — Up to 5 minutes of fabricated points fill each gap by default
• query-rollup-changes-the-number — The same widget means something different at each time frame
• query-event-sources-take-objects — Logs and spans take search+compute+group_by; interval is milliseconds, percentiles are pc95
• query-scope-syntax-does-not-mix — {env:prod AND !region:x} is invalid; a wildcard after $var matches nothing
• query-top-n-subtotals-are-partial — The total under a top list is the sum of the visible rows

4. Choosing the Widget

• widget-match-the-question — Timeseries answers one question; rankings, single values, and deltas want other widgets
• widget-heatmap-is-not-distribution — One has time on the x-axis, the other quantity
• widget-reuse-alerting-primitives — Embed the SLO and monitor instead of guessing a threshold line

5. Dashboard JSON

• json-type-strings-differ-from-ui-names — Pie Chart is sunburst, Table is query_table, Monitor Summary is manage_status
• json-queries-and-formulas-not-q — q and every *_query field are deprecated; data_source is profiles, not profile_metrics
• json-layout-follows-reflow-type — Under reflow_type: auto, layout must be omitted, not merely ignored
• json-template-variables-take-defaults — defaults is an array; singular default is deprecated
• json-dashboard-tags-are-constrained — Max 5, team:-shaped; is_read_only is deprecated but restricted_roles is not

6. Layout & Readability

• layout-put-widgets-in-groups — About and Overview first, streams last, nothing bare on the background
• layout-display-type-follows-metric-shape — Area for volume, bars for counts, lines for comparison
• layout-let-datadog-render-units — Alias every formula; the axis already shows the unit
• layout-size-for-the-medium — A wallboard and a triage board cannot be the same dashboard

7. Shipping It

• ship-validate-before-upserting — Smoke-test the query and validate per widget before the write
• ship-endpoint-follows-the-site — EU, AP, and UK orgs need their own MCP host; GovCloud is unsupported

How to Use

Read a reference file when its decision comes up. Each rule names the wrong default it corrects, then shows the canonical form — with an incorrect/correct contrast only where the wrong way is a real trap.

Three shortcuts worth taking first:

• Building a dashboard from a request? Run scope-ask-audience-and-decision, then disco-never-invent-metric-names, before emitting anything. Skipping either produces a board that is fluent and useless.

• Reviewing a dashboard whose numbers look wrong? Start with query-append-as-count-explicitly and query-percentiles-require-distributions. Together they account for most Datadog panels that are confidently incorrect, and neither leaves a trace in the UI.

• Porting dashboard JSON written before 2025? json-queries-and-formulas-not-q and json-template-variables-take-defaults are the deprecations that still parse, so nothing points you at them.

• Section definitions — category structure and ordering rationale

• Rule template — for adding new rules

• AGENTS.md — auto-built table of contents across all rules