Dynatrace Notebook Skill

Overview

Dynatrace notebooks are JSON documents stored in the Document Store for interactive data analysis, investigation, and documentation. Each notebook contains:

Sections: Modular blocks organizing markdown and query content
DQL Queries: Executable queries with cached results and visualizations
Markdown: Documentation, context, and narrative content
Timeframes: Default and section-specific time ranges
Metadata: Ownership, versioning, and modification tracking

When to use this skill:

Creating investigation notebooks or analysis templates
Modifying existing notebooks (queries, sections, visualizations, markdown)
Querying notebook JSON to extract DQL queries or analyze structure
Analyzing notebook purpose, investigation workflow, and data coverage
Building collaborative documentation with embedded analytics

Four main workflows:

Creating - Build notebooks from scratch for investigations, documentation, or query libraries
Modifying - Update sections, queries, visualizations, markdown, or timeframes
Querying - Extract data from notebook JSON or search Document Store
Analyzing - Understand structure, purpose, investigation workflow, and content gaps

Notebook Document Structure

Notebooks in the Dynatrace Document Store include both metadata and content:

json

{
  "id": "notebook-abc123",
  "name": "Production Investigation",
  "type": "notebook",
  "owner": "user-uuid",
  "isPrivate": false,
  "version": 42,
  "modificationInfo": {...},
  "content": {
    "version": "7",
    "defaultTimeframe": {
      "from": "now()-2h",
      "to": "now()"
    },
    "sections": [...]
  }
}

Metadata (top-level):

```
.id
```
- Document ID (UUID or semantic like "dynatrace.notebooks.getting-started")
```
.name
```
- Notebook display name
```
.type
```
- Always "notebook"
```
.owner
```
- Owner UUID
```
.isPrivate
```
- Visibility (true = private, false = shared)
```
.version
```
- Document version (incremental, auto-managed)
```
.modificationInfo
```
- Creation/modification timestamps

Notebook content (
.content
):

```
.content.version
```
- Content schema version (currently "7")
```
.content.defaultTimeframe
```
- Default time range for all DQL sections
```
.content.defaultSegments
```
- Default filter segments (usually empty)
```
.content.sections
```
- Array of markdown and DQL query sections

All jq examples in this skill use the

.content.*

paths.

When to Load References

This skill uses progressive disclosure - load only what you need:

Start here: SKILL.md provides core concepts and quick-start examples
Load references on-demand: Each reference file covers a specific deep-dive topic
Context efficiency: Progressive loading enables task completion without external documentation

Loading strategy:

Try answering with just SKILL.md first
If you need detailed specifications or advanced patterns, load the relevant reference file
The "References" section below maps each file to its use case

💡 Tip: Reference files are linked throughout this document with
→
arrows pointing to when you should load them.

Working with Notebooks

For detailed workflows and mandatory requirements:

Creating & Updating notebooks → Load
```
references/create-update.md
```
for complete workflow, test-first approach, DQL query validation, and modification patterns
Analyzing notebooks → Load
```
references/analyzing.md
```
for structure analysis, JSON extraction, and query execution

⚠️ MANDATORY for creation/modification:

Always load the relevant reference file first
Load relevant skills for query generation (MANDATORY - do not invent queries)
Test and validate all DQL queries before adding to notebook (see create-update.md)
Validate notebook JSON against schema before save/upload (see Schema Validation below)

Notebook Structure

Root Properties

Required properties:

json

{
  "version": "7",              // Content schema version (current: "7")
  "sections": []               // Array of markdown and DQL sections
}

Optional properties:

```
defaultTimeframe
```
- Default time range for all DQL sections
```
defaultSegments
```
- Default filter segments (usually empty)

Structure concept: Sections are ordered array (display order = array order). Each section has unique UUID. Section types: markdown (documentation) and dql (queries with visualizations).

Sections Overview

📝 For detailed section specifications, visualization settings, and configuration options, load
references/sections.md

Markdown sections:

{"type": "markdown", "markdown": "# Content"}

DQL sections:

{"type": "dql", "state": {"input": {"value": "query"}, "visualization": "table"}}

Visualizations:

table

lineChart

barChart

pieChart

singleValue

areaChart

→ See references/sections.md for complete specifications

Schema Validation

⚠️ MANDATORY for create/update workflows: Always validate notebook JSON before save/upload. → Load

references/create-update.md

for validation commands, query validation, error interpretation, and test workflow.

Schema location:

notebook-schema.json

(Notebook content schema v7)

References

Reference File	When to Use
create-update.md	Creating and updating notebooks - workflows, test-first approach, DQL query validation, patterns
analyzing.md	Extract information from notebooks, understand structure and content, query execution
sections.md	Section types, visualization settings, configuration reference

Common Patterns & Best Practices

Notebook types:

Investigation: Markdown context → DQL queries → Analysis → Findings
Documentation: Narrative with embedded queries demonstrating concepts
Query Library: Collection of reusable DQL patterns with explanations

Key rules:

Use unique UUIDs for section IDs · Start with markdown context · Set content version="7" · Use relative timeframes (
```
now()-2h
```
) · Omit result objects when creating sections · Order sections logically · Add markdown between query sections for context

Timeframe strategies:

Default timeframe: Sets baseline for all DQL sections
Section-specific: Override default for specific queries (e.g., longer lookback for trends)
Relative:
```
now()-2h
```
,
```
now()-7d
```
for dynamic ranges
Absolute: ISO timestamps for historical analysis

Related Skills

dt-dql-essentials - DQL query syntax, functions, and optimization
dt-app-dashboards - Dashboard creation for operational monitoring (vs notebooks for investigation)

dt-app-notebooks

NPX Install

Tags

SKILL.md Content