Dt App Notebooks

Dynatrace Notebook Skill

Overview

Dynatrace notebooks are JSON documents stored in the Document Store containing an ordered array of sections — markdown blocks for narrative and dql blocks for DQL queries with visualizations. Sections render top-to-bottom in array order.

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

Notebook JSON Structure

{
  "name": "My Notebook",
  "type": "notebook",
  "content": {
    "version": "7",
    "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
    "sections": [
      { "id": "1", "type": "markdown", "markdown": "# Title" },
      {
        "id": "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
          }
        }
      }
    ]
  }
}

• Sections render in array order.
• Section types: markdown, dql. (function exists but is rare.)
• Use string-int IDs ("1", "2", …); UUIDs are also accepted.
• content.defaultTimeframe sets the default timeframe; each section can override via section.state.input.timeframe. Hardcoded time filters in DQL are allowed.

Optional content properties: defaultSegments.

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 section queries before adding to the notebook.
• Set name before deploying.
• Prefer `autoSelectVisualization: true` in visualizationSettings unless the user requested a specific visualization type — when false, state.visualization must be set explicitly.
• Updating — ALWAYS download first: dtctl get notebook <id> -o json --plain > notebook.json, modify, then deploy the downloaded file. Never reconstruct JSON from scratch or inject an id manually — both silently overwrite 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

Notebooks support a subset of Dynatrace visualizations:

• Time-series (require timeseries/makeTimeseries): lineChart, areaChart, barChart, bandChart
• Categorical (summarize ... by:{field}): categoricalBarChart, pieChart, donutChart
• Single value / gauge / meter: singleValue, meterBar, gauge
• Tabular (any data shape): table, raw, recordView
• Distribution/status: histogram, honeycomb
• Geographic maps: choropleth, dotMap, connectionMap, bubbleMap
• Matrix/correlation: heatmap, scatterplot

Required field types per visualization: references/sections.md.

References

Notebook Analysis & Information Extraction

Two Main Workflows

1. Look into the notebook — read global context, then sections in display order 2. Search for something — find specific content by keyword

---

Workflow 1: Read Notebook

Global Context

Read .content.version for the schema version, .content.defaultTimeframe for the notebook's default time range, and count entries in .content.sections for total section count.

Sections in Display Order

Sections render top-to-bottom in array order.

Iterate .content.sections in order. For each section, read: id, type, title, state.input.value (the DQL query), and state.visualization.

For a specific section, find the entry where .id == "<id>" and read: title, state.input.value, visualization, and state.visualizationSettings.

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

---

Workflow 2: Search

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

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

---

Executing Queries from a Section

1. Extract query (section.state.input.value) with title, visualization, and thresholds for context 2. Check for hardcoded timeframe (section.state.input.timeframe) — if absent, the notebook's content.defaultTimeframe applies 3. Execute the query and interpret results based on visualization type and thresholds

---

Purpose Identification

Analyze section titles and data sources to infer notebook 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 overview

To identify data sources, scan .content.sections[].state.input.value for fetch <entity> patterns to see which Dynatrace entity types are queried.

Notebook 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 notebook structure: section order, markdown vs DQL sections 4. Design and validate all DQL with dtctl query '<DQL>' --plain 5. (Update only) Download existing notebook JSON from the server 6. Construct new notebook JSON (create) or modify the downloaded JSON (update) 7. Deploy with dtctl apply — when updating, deploy the file downloaded in step 5

---

Mandatory Requirements

• DQL validation — test ALL section queries 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

• Time-range filters in queries — hardcoded time filters are fine in

notebooks. The default timeframe is content.defaultTimeframe; each section can override via section.state.input.timeframe.

DQL Validation

Syntax + execution validation is mandatory for all queries. Section queries may return empty results (e.g. error logs when no errors exist) — empty is OK, but the query must execute without errors.

Creating Notebooks

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

Sections render top-to-bottom in content.sections array order. Use markdown sections to introduce groups of DQL sections (e.g. one markdown header followed by 2–3 related DQL sections).

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 Notebook JSON

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

dtctl get notebook <id> -o json --plain > notebook.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 Notebook JSON

For new notebooks, 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 Notebook Name",  // "id" is present when updating (from downloaded JSON)
  "type": "notebook",
  "content": {
    "version": "7",
    "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
    "sections": [
      { "id": "1", "type": "markdown", "markdown": "# Title" },
      {
        "id": "2", "type": "dql", "title": "Metric", "showInput": true,
        "state": {
          "input": { "value": "fetch ... | summarize ..." },
          "visualizationSettings": { "autoSelectVisualization": true, "chartSettings": {} },
          "querySettings": {
            "maxResultRecords": 1000, "defaultScanLimitGbytes": 500,
            "maxResultMegaBytes": 1, "defaultSamplingRatio": 10, "enableSampling": false
          }
        }
      }
    ]
  }
}

Visualization tip: prefer visualizationSettings.autoSelectVisualization: true and omit state.visualization. Set both only when the user wants a specific chart type.

Checklist before writing JSON:

• Every dql section has: unique id, validated DQL, visualizationSettings,

querySettings

• Section IDs are unique across the sections array
• When updating: confirm the JSON is the downloaded file (id field

present), not a freshly constructed one

See sections.md for visualization types and field requirements.

Step 7: Deploy

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

Validation runs automatically before deployment (every DQL query is executed against the tenant and visualization compatibility is checked). If validation fails, fix all reported errors before re-running — do not fix one error and re-deploy in a loop.

When updating: ensure notebook.json is the file downloaded in Step 5. A missing id field means a fresh JSON is being deployed — a new notebook 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
• Missing name in notebook JSON
• Setting a custom id on a new notebook (server assigns IDs; only downloaded

notebooks 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

Notebook Sections

Sections are stored in content.sections as an ordered array. Each section has its own id field. Section types: markdown and dql.

Section Types

Markdown Sections

{ "id": "1", "type": "markdown", "markdown": "# Section Header" }

DQL Sections

{
  "id": "2", "type": "dql", "title": "Section Name",
  "showInput": true,
  "state": {
    "input": { "value": "timeseries avg(metric), by:{dimension}" },
    "visualization": "lineChart",
    "visualizationSettings": { "autoSelectVisualization": true, "chartSettings": {} },
    "querySettings": {
      "maxResultRecords": 1000, "defaultScanLimitGbytes": 500,
      "maxResultMegaBytes": 1, "defaultSamplingRatio": 10, "enableSampling": false
    }
  }
}

Optional properties: showTitle, height, drilldownPath, filterSegments, davis.

Section properties:

• autoSelectVisualization (boolean, in visualizationSettings) — when

true, Dynatrace automatically picks the best visualization. Prefer `true` unless the user requested a specific visualization. When false, state.visualization must be set explicitly.

• showTitle (boolean) — show/hide section title
• showInput (boolean, default true) — show/hide query editor. Keep true

unless told otherwise

• height (number, px) — section height (default ~400)

Visualization Types and Required Field Types

Each visualization requires specific field types in the query result. If the query produces wrong types, the section renders blank or errors. Field types correspond to DQL output types: timestamp, timeframe, long, double, duration, string, numericArray (array of long/double — 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 section 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

`singleValue`: Displays a single metric.

Tabular

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

Distribution / Status

`histogram`: Shows distribution of values.

`honeycomb`: Grid of colored cells.

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.

Visualization tip: when you don't have a strong reason to pick a specific visualization, set visualizationSettings.autoSelectVisualization: true and omit state.visualization — Dynatrace picks a sensible default for the query result.