dt-app-notebooks

Dynatrace Notebook Skill

How to Use This Skill

Notebooks and dashboards are structurally similar. Follow the dt-app-dashboards skill for all workflows (creating, modifying, querying, analyzing), applying the differences documented below.

Mandatory Create/Update Workflow

1. Load domain skills BEFORE generating queries — do not invent DQL
2. Validate ALL queries via dtctl query '<DQL>' --plain before adding to the notebook
3. Always set "autoSelectVisualization": true in visualizationSettings unless the user explicitly requests a specific visualization type
4. ALWAYS deploy via deploy_notebook.sh — never use dtctl apply directly:

   bash scripts/deploy_notebook.sh notebook.json
   

   The script validates the notebook first and blocks deployment on errors. Skipping it risks deploying broken notebooks. On successful deployment, the local file is deleted.
5. When updating an existing notebook: download first with dtctl get notebook <id> -o json --plain > notebook.json, modify, then deploy. Never reconstruct from scratch or inject an id manually.

Notebook JSON Structure

{
  "name": "My Notebook",
  "type": "notebook",
  "content": {
    "version": "7",
    "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
    "sections": [
      { "id": "uuid-1", "type": "markdown", "markdown": "# Title\nContext" },
      {
        "id": "uuid-2", "type": "dql", "title": "Query Section", "showInput": true,
        "state": {
          "input": { "value": "fetch logs | summarize count()" },
          "visualization": "table",
          "visualizationSettings": { "autoSelectVisualization": true, "chartSettings": {} },
          "querySettings": {
            "maxResultRecords": 1000, "defaultScanLimitGbytes": 500,
            "maxResultMegaBytes": 1, "defaultSamplingRatio": 10, "enableSampling": false
          }
        }
      }
    ]
  }
}

Key Differences from Dashboards

Document Structure

Section Types vs Tile Types

Dashboards have two tile types (markdown, data). Notebooks have three section types:

• markdown — Same concept. Fields: id, type, markdown
• dql — Equivalent to dashboard data tiles, but query and visualization are nested inside state (see table below)

Query & Visualization Path Mapping

Notebook-Only Section Properties

• autoSelectVisualization (boolean, in visualizationSettings) — when true, Dynatrace automatically selects the best visualization type for the query result. Prefer true when the user has no specific visualization preference. When set to false, you must explicitly set state.visualization to the desired type.
• showTitle (boolean) — show/hide section title
• showInput (boolean, default true) — show/hide query editor. Always set to true unless explicitly requested otherwise.
• height (number, px) — section height (default ~400)
• drilldownPath — navigation path for drilldown interactions
• filterSegments — section-level filter segments
• davis — Davis AI copilot configuration

Available Visualizations

Notebooks support: table, lineChart, areaChart, barChart, categoricalBarChart, pieChart, donutChart, singleValue, bandChart, histogram, honeycomb, raw, recordView

What Does NOT Apply from the Dashboard Skill

• Variables — Notebooks have no variables. Ignore all variable sections: types, substitution patterns ($Var, array($Var)), dependency resolution, variable validation.
• Layouts/grid — No positioning system. Section order in the array = display order. No x, y, w, h.
• Tile ID / Layout ID matching — Not applicable (no layouts object).
• UI timeframe picker warnings — Notebooks don't have a dashboard-style time picker that controls all queries. Instead, content.defaultTimeframe sets the default, and each section can override via section.state.input.timeframe. Hardcoded time filters in queries are acceptable in notebooks.
• Variable substitution in queries — Not applicable.

Validation & Deployment

Use the scripts in scripts/:

• notebook-validator.js — Validates notebook structure and executes all DQL queries. Run via:

  cat notebook.json | jq '{notebook: .}' | dtctl exec function -f scripts/notebook-validator.js --data - --plain | jq -r .result
  

  Or by notebook ID: echo '{"notebookId":"<id>"}' | dtctl exec function -f scripts/notebook-validator.js --data - --plain | jq -r .result

• deploy_notebook.sh — Validates then deploys:

  bash scripts/deploy_notebook.sh notebook.json
  bash scripts/deploy_notebook.sh --dry-run notebook.json
  

Related Skills

• dt-app-dashboards — Base skill for all workflows; this skill documents only the differences
• dt-dql-essentials — DQL query syntax, functions, and optimization