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:

{

"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:

{

"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