Dt App Dashboards

Dynatrace Dashboard Skill

Overview

Dynatrace dashboards are JSON documents stored in the Document Store containing tiles (content/visualizations), layouts (grid positioning), and variables (dynamic query parameters).

When to use: Creating, modifying, querying, or analyzing dashboards.

Dashboard JSON Structure

{
  "name": "My Dashboard",
  "type": "dashboard",
  "content": {
    "version": 21,
    "variables": [],
    "tiles": { "<id>": { "type": "data|markdown", ... } },
    "layouts": { "<id>": { "x": 0, "y": 0, "w": 24, "h": 8 } }
  }
}

• Tile IDs in tiles must match IDs in layouts
• Grid is 24 units wide. Common widths: 24 (full), 12 (half), 6 (quarter)
• Two tile types: markdown (text content) and data (DQL query + visualization)

Optional content properties: settings, refreshRate, annotations

Create/Update Workflow (Mandatory Order)

Carefully follow the workflow described in references/create-update.md.

Key rules:

• Load domain skills BEFORE generating queries — do not invent DQL
• Validate ALL queries before adding to dashboard
• No time-range filters in queries unless explicitly requested by user
• Set name before deploying
• Updating — ALWAYS download first: dtctl get dashboard <id> -o json --plain > dashboard.json, modify, then deploy the downloaded file. Never reconstruct JSON from scratch or inject an id manually — both silently overwrite any UI edits the user made since last deployment.
• Deploy with `dtctl apply` — validation runs automatically, and the local file is deleted on success.

Visualization Types

• Time-series (require timeseries/makeTimeseries): lineChart, areaChart, barChart, bandChart
• Categorical (summarize ... by:{field}): categoricalBarChart, pieChart, donutChart
• Single value/gauge (single numeric record): singleValue, meterBar, gauge
• Tabular (any data shape): table, raw, recordList
• Distribution/status: histogram, honeycomb
• Maps: choroplethMap, dotMap, connectionMap, bubbleMap
• Matrix: heatmap, scatterplot

Required field types per visualization: references/tiles.md

Variables Quick Reference

{ "version": 2, "key": "Service", "type": "query", "visible": true,
  "editable": true, "input": "smartscapeNodes SERVICE | fields name",
  "multiple": false }

• Single-select: filter service.name == $Service
• Multi-select: filter in(service.name, array($Service))
• Types: query (DQL-populated), csv (static list), text (free-form)

Full variable reference: references/variables.md

References

Dashboard Analysis & Information Extraction

Two Main Workflows

1. Look into dashboard — read global context, then tiles top-to-bottom 2. Search for something — find specific content by keyword

---

Workflow 1: Read Dashboard

Global Context

Read .content.version for the schema version, count entries in .content.tiles for total tile count, and count entries in .content.variables for total variable count.

For each variable in .content.variables[], note its key, type, input, and defaultValue — these are the filters available to the user.

Tiles Top-to-Bottom

To read tiles in display order, iterate .content.layouts entries sorted by .value.y then .value.x. For each entry, look up the corresponding tile in .content.tiles[id].

For a specific tile, look it up by ID in .content.tiles["<id>"] and read: title, query, visualization, and visualizationSettings.

Per tile, extract: title (what it shows), query (DQL), visualization (chart type), thresholds (color interpretation), content (markdown text).

---

Workflow 2: Search

To search by title: iterate .content.tiles and find entries where .value.title (case-insensitive) contains the keyword.

To search by query content: iterate .content.tiles and find entries where .value.query contains the search pattern.

---

Executing Queries from Dashboard

1. Extract query with title, visualization, and thresholds for context 2. Check for variables ($VarName references) 3. Resolve variables: if type=="query", execute the variable's input query to get valid values; if type=="text", use defaultValue 4. Substitute variable values into the query 5. Execute and interpret results based on visualization type and thresholds

---

Purpose Identification

Analyze tile titles and data sources to infer dashboard purpose:

• "Request Rate", "Error Count", "Response Time" → Service Health (RED)
• "CPU Usage", "Memory Usage" → Infrastructure Monitoring
• "SLI", "Error Budget" → SLO Tracking
• Single values with thresholds → Executive / KPI dashboard

To identify data sources, scan .content.tiles[].query for fetch <entity> patterns to see which Dynatrace entity types are queried.

Dashboard Create & Update Workflows

Mandatory 7-Step Order

1. Define purpose and load required skills, references and assets 2. Explore available data fields/metrics 3. Plan dashboard structure: variables, tiles, layout 4. Design and validate all DQL with dtctl query '<DQL>' --plain 5. (Update only) Download existing dashboard JSON from the server 6. Construct new dashboard JSON (create) or modify the downloaded JSON (update) 7. Deploy with dtctl apply — when updating, deploy the file downloaded in step 5

---

Mandatory Requirements

• No time-range filters in tile queries — the dashboard UI time-frame

picker handles this. Only add time filters when user explicitly requests it.

• DQL validation — test ALL queries (tile and variable) before adding
• Skill-based queries — load domain skills BEFORE generating queries;

do not invent DQL queries, field names, or data sources

• Verify field names — run a sample query (e.g. limit 1) and only use

fields that actually exist in the result

DQL Validation

Syntax + execution validation is mandatory for all queries.

1. Validate tile queries and variable input queries 2. For queries with $VariableName: extract the variable's input query, execute it to get real values, then test the tile query with those values 3. Variable queries MUST return at least one value; tile queries may return empty results (e.g. error logs when no errors exist)

Creating Dashboards

Step 1: Define Purpose

Identify metrics, audience, and actions. Then load relevant domain skills.

Step 2: Explore Data

For fields and metrics already documented in the loaded domain skill, skip exploration — confirm with one | limit 1 query. Only run broader discovery queries for data models not covered by the skill.

Step 3: Plan Structure

Sketch approximate layout: number of tiles, positions, variables needed.

Layout Grid

Default: 24 columns (settings.gridLayout.columnsCount). Full-width w: 24, half w: 12, quarter w: 6. Height: h: 1 for headers, h: 6-8 for charts, h: 12-16 for detailed views.

Each tile in tiles must have a matching entry in layouts with x, y, w, h. Tiles with x + w > columnsCount wrap. Use standard widths for responsiveness.

"layouts": {
  "1": { "x": 0, "y": 0, "w": 24, "h": 1 },
  "2": { "x": 0, "y": 1, "w": 12, "h": 8 },
  "3": { "x": 12, "y": 1, "w": 12, "h": 8 },
  "4": { "x": 0, "y": 9, "w": 24, "h": 8 }
}

Step 4: Design and Validate Queries

dtctl query '<your DQL query>' --plain

Always use single quotes around the DQL string to avoid shell interpretation of $, \, and other special characters.

Use limit to cap results. Use summarize before visualization. Source queries from loaded skills.

Step 5 (Update only): Download Existing Dashboard JSON

Skip when creating. Download the current server state before making any modifications:

dtctl get dashboard <id> -o json --plain > dashboard.json

This preserves user UI edits since the last deployment. The downloaded file contains the id — do not add or change it manually.

Step 6: Construct New or Modify Downloaded Dashboard JSON

For new dashboards, build JSON from scratch (no id — server assigns one). For updates, modify the file downloaded in Step 5 — do not construct new JSON and inject an id.

{
  "name": "My Dashboard Name",  // "id" is present when updating (from downloaded JSON)
  "type": "dashboard",
  "content": {
    "version": 21,
    "variables": [],
    "tiles": {
      "1": { "type": "markdown", "content": "# Title" },
      "2": {
        "type": "data", "title": "Metric",
        "query": "fetch ... | summarize ...",
        "visualization": "lineChart",
        "visualizationSettings": {}, "querySettings": {}
      }
    },
    "layouts": { "1": { "x": 0, "y": 0, "w": 24, "h": 1 }, "2": { "x": 0, "y": 1, "w": 24, "h": 8 } }
  }
}

Checklist before writing JSON:

• Every data tile has: unique ID, validated DQL, visualizationSettings, querySettings, matching layout entry
• Every defined variable is referenced in at least one tile query — remove unused variables
• When updating: confirm the JSON is the downloaded file (id field present), not a freshly constructed one

See tiles.md for visualization types and field requirements. See variables.md for variable definitions and usage patterns.

Step 7: Deploy

dtctl apply -f dashboard.json -o yaml
# preview without persisting:
dtctl apply -f dashboard.json -o yaml --dry-run

Validation runs automatically before deployment. If validation fails, fix all reported errors before re-running — do not fix one error and re-deploy in a loop.

When updating: ensure dashboard.json is the file downloaded in Step 5. A missing id field means a fresh JSON is being deployed — a new dashboard will be created instead of updating.

On success, dtctl apply outputs the deployment result (action, id, name, url) and the local file is deleted automatically. Present the URL to the user.

---

Anti-Patterns

• Inventing queries without loading skills first
• Inventing DQL field names without checking sample output
• Overlapping layouts
• Hardcoding time-range filters (overrides UI time picker)
• Defining variables that are not referenced in any tile query (every variable must be used as $key in at least one tile query)
• Missing name in dashboard JSON
• Setting a custom id on a new dashboard (server assigns IDs; only downloaded dashboards carry their id)
• Skipping the download when updating — building JSON from scratch loses user UI edits made since last deployment
• Injecting an `id` into freshly-constructed JSON — same as above; overwrites server state with stale content
• Downloading but not using the file — deploying a freshly-constructed JSON instead of the downloaded one defeats the download step

Dashboard Tiles

Tiles are stored in content.tiles as an object map with string keys.

Tile Types

Markdown Tiles

{ "type": "markdown", "content": "# Section Header" }

Data Tiles

{
  "type": "data", "title": "Tile Name",
  "query": "timeseries avg(metric), by:{dimension}",
  "visualization": "lineChart",
  "visualizationSettings": {},
  "querySettings": {}
}

Optional properties: description, customLinkSettings, davis, davisCopilot, timeframe, segments.

Code Tiles

{ "type": "code", "title": "Custom", "input": "// JS code",
  "visualization": "lineChart", "visualizationSettings": {} }

SLO Tiles

{ "type": "slo", "title": "SLO Name", "input": "slo-id",
  "visualizationSettings": {} }

Visualization Types and Required Field Types

Each visualization requires specific field types in the query result. If the query produces wrong types, the tile renders blank or errors. The field types below correspond to DQL output types: timestamp, timeframe, long, double, duration, string, numericArray (array of long/double — the output of timeseries/makeTimeseries value columns).

Legend: R = required, O = optional, C = conditional.

Time-Series Charts

`lineChart`, `areaChart`, `barChart`: Display metric data over time.

When the query uses timeseries or makeTimeseries, values are numericArrays and the interval field (duration) must be present. If you pipe through | fields after timeseries, always include interval and timeframe.

`bandChart`: Same as above plus two additional required numericArray slots for band min and band max values.

Categorical Charts

`categoricalBarChart`, `pieChart`, `donutChart`: Show values grouped by categories.

Typical query pattern: summarize <agg>, by:{category}.

`barChart` vs `categoricalBarChart`: barChart is a time-series chart requiring a timestamp/timeframe axis. For "values per category" (e.g. request count per service), use categoricalBarChart. If you use barChart with summarize ... by:{category} (no time axis), the tile will fail validation.

Timeseries data in categorical charts: If you need to show summarized metrics (not over time), first convert the timeseries arrays to scalars using array functions (arrayAvg, arraySum, etc.), then use categoricalBarChart.

Single Value / Gauge

`singleValue`: Displays a single metric.

`meterBar`, `gauge`: Display a numeric value on a scale.

Configure minValue/maxValue in visualizationSettings.

Tabular

`table`, `raw`, `recordList`: Any data shape. No field-type requirements.

Distribution / Status

`histogram`: Shows distribution of values.

`honeycomb`: Grid of colored cells.

Geographic Maps

`choroplethMap`: Colored regions on a map.

`dotMap`, `connectionMap`: Points on a map.

`bubbleMap`: Sized circles on a map.

Matrix / Correlation

`heatmap`: 2D grid with colored cells.

bin(timestamp, ...) returns timestamp — heatmap axes do not accept timestamp. Wrap with toString(): by:{x = toString(bin(timestamp, 1h))}.

`scatterplot`: X/Y point chart.

Visualization Settings

See assets/visualization-settings.reference.jsonc for the complete per-visualization settings reference.

Common settings across visualizations: legend, tooltip, zoom, unitsOverrides, coloring, thresholds, colorModeType.

Dashboard Variables

Variables provide dynamic filtering across tiles. Defined in content.variables array, referenced in queries as $key.

Required Properties

Variable Types

Query Variables (type: "query")

Dynamic values from DQL. Most common type.

{
  "version": 2, "key": "Service", "type": "query",
  "visible": true, "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": false
}

Critical: Query must return exactly one field. Multiple fields break the dropdown. Variable query MUST return at least one row — empty results mean the dashboard is invalid.

Getting distinct values for variable dropdowns:

• For entity names: smartscapeNodes SERVICE | fields name | sort name asc
• For logs/events fields: fetch logs | filter isNotNull(field) | filter field != "" | dedup field | fields field | sort field asc
• Do not use summarize by: {field} without an aggregation; use dedup field for distinct values
• Filter out empty strings (field != "") to avoid blank variable options and empty tile results

Multi-select with all-selected default:

{
  "version": 2, "key": "Services", "type": "query",
  "visible": true, "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": true,
  "defaultValue": "3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"
}

Text Variables (type: "text")

Free-form text input.

{ "version": 1, "key": "Threshold", "type": "text",
  "visible": true, "editable": true, "defaultValue": "" }

CSV Variables (type: "csv")

Static predefined values. Prefer `type: "query"` when values come from live data — CSV values must exactly match real data or tiles show blank.

{ "version": 1, "key": "Status", "type": "csv",
  "visible": true, "editable": true,
  "input": "WARN,ERROR,INFO,NONE", "multiple": true,
  "defaultValue": "3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*" }

Default Values

• query/csv, `multiple: true`: use magic token "3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*" to select all
• query/csv, `multiple: false`: omit defaultValue (first value auto-selected). Do NOT use magic token.
• text: omit or use "". Do NOT use "*" (passed literally into query).

Query Reference Syntax

Modifiers

Do not double-wrap: :backtick already adds backticks. Write $GroupBy:backtick, never ` $GroupBy:backtick `.

For durations: duration(toLong($Minutes:noquote), unit:"m").

Variable Dependencies

Variables can reference other variables. Dependent variables recalculate when dependencies change. Circular dependencies are not allowed.

[
  { "key": "Cluster", "type": "query",
    "input": "smartscapeNodes K8S_CLUSTER | fields name" },
  { "key": "Namespace", "type": "query",
    "input": "smartscapeNodes K8S_NAMESPACE | filter belongs_to == $Cluster | fields name" }
]

Version

Use version: 2 for new dashboards (supports fetch, expand, summarize). version: 1 is legacy.

Limitations