dt-app-notebooks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Dynatrace notebooks是存储在文档存储中的JSON文档，用于交互式数据分析、问题调查和文档编写。每个notebook包含以下元素：

章节：组织markdown和查询内容的模块化块
DQL查询：带缓存结果和可视化能力的可执行查询
Markdown：文档说明、上下文信息和叙述类内容
时间范围：全局默认时间范围和章节专属时间范围
元数据：归属信息、版本控制和修改轨迹

适用场景：

创建问题调查notebook或分析模板
修改现有notebook（查询、章节、可视化、markdown内容）
查询notebook JSON以提取DQL查询或分析结构
分析notebook用途、调查工作流和数据覆盖范围
构建内嵌分析能力的协同文档

四大核心工作流：

创建 - 从零搭建用于问题调查、文档沉淀或查询库的notebook
修改 - 更新章节、查询、可视化配置、markdown内容或时间范围
查询 - 从notebook JSON中提取数据或搜索文档存储
分析 - 梳理结构、用途、调查工作流和内容缺口

Notebook Document Structure

Notebook文档结构

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.

存储在Dynatrace文档存储中的notebook包含元数据和内容两部分：

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": [...]
  }
}

顶层元数据字段：

```
.id
```
- 文档ID（UUID或语义化名称，如"dynatrace.notebooks.getting-started"）
```
.name
```
- Notebook展示名称
```
.type
```
- 固定为"notebook"
```
.owner
```
- 所有者UUID
```
.isPrivate
```
- 可见性（true=私有，false=共享）
```
.version
```
- 文档版本（自增，系统自动维护）
```
.modificationInfo
```
- 创建/修改时间戳

Notebook内容（
.content
字段）：

```
.content.version
```
- 内容 schema 版本（当前为"7"）
```
.content.defaultTimeframe
```
- 所有DQL章节的默认时间范围
```
.content.defaultSegments
```
- 默认过滤片段（通常为空）
```
.content.sections
```
- markdown和DQL查询章节的数组

本技能中所有jq示例都使用

.content.*

路径。

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.

本技能采用渐进式信息披露策略，仅加载你需要的内容：

入门首选：SKILL.md提供核心概念和快速上手示例
按需加载引用：每个引用文件覆盖特定的深度主题
上下文效率：渐进式加载无需额外外部文档即可完成任务

加载策略：

优先仅用SKILL.md的内容解答问题
若需要详细规范或高级模式，加载对应的引用文件
下方的「引用」部分列明了各文件的适用场景

💡 提示：本文档中带
→
箭头的位置标注了需要加载对应引用文件的场景。

Working with Notebooks

操作Notebook

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 → 加载
```
references/create-update.md
```
获取完整工作流、测试优先方案、DQL查询校验和修改模式
分析notebook → 加载
```
references/analyzing.md
```
获取结构分析、JSON提取和查询执行相关说明

⚠️ 创建/修改操作强制要求：

必须先加载对应的引用文件
必须加载查询生成相关技能（强制要求，不得自行编造查询）
所有DQL查询添加到notebook前必须经过测试和校验（参见create-update.md）
保存/上传前必须按schema校验notebook JSON（参见下方schema校验部分）

Notebook Structure

Notebook结构规范

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).

必填属性：

json

{
  "version": "7",              // 内容schema版本（当前为"7"）
  "sections": []               // markdown和DQL章节数组
}

可选属性：

```
defaultTimeframe
```
- 所有DQL章节的默认时间范围
```
defaultSegments
```
- 默认过滤片段（通常为空）

**结构逻辑：**章节为有序数组（展示顺序=数组顺序），每个章节有唯一UUID。章节类型分为：markdown（文档说明）和dql（带可视化的查询）。

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

📝 如需详细的章节规范、可视化设置和配置选项，请加载
references/sections.md

Markdown章节：

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

DQL章节：

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

支持的可视化类型：

table

、

lineChart

、

barChart

、

pieChart

、

singleValue

、

areaChart

→ 完整规范参见references/sections.md

Schema Validation

Schema校验

⚠️ 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)

⚠️ 创建/更新工作流强制要求： 保存/上传前必须校验notebook JSON。 → 加载

references/create-update.md

获取校验命令、查询校验、错误解读和测试工作流说明。

Schema位置：

notebook-schema.json

（Notebook内容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

引用文件	适用场景
create-update.md	创建和更新notebook：工作流、测试优先方案、DQL查询校验、模式参考
analyzing.md	从notebook提取信息、梳理结构和内容、执行查询
sections.md	章节类型、可视化设置、配置参考

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

Notebook类型：

问题调查类：Markdown上下文说明 → DQL查询 → 分析 → 结论
文档类：结合内嵌查询演示概念的叙述性文档
查询库类：带说明的可复用DQL模式集合

核心规则：

章节ID使用唯一UUID · 以Markdown上下文说明开篇 · 内容版本设置为version="7" · 使用相对时间范围（
```
now()-2h
```
） · 创建章节时省略结果对象 · 按逻辑顺序排列章节 · 查询章节之间添加Markdown补充上下文

时间范围设置策略：

全局默认时间范围：为所有DQL章节设置基准时间范围
章节专属时间范围：为特定查询覆盖默认时间范围（例如趋势分析需要更长的回溯周期）
相对时间：
```
now()-2h
```
、
```
now()-7d
```
等动态时间范围
绝对时间：ISO时间戳，用于历史分析

dt-app-notebooks

Original

Translation

Dynatrace Notebook Skill

Dynatrace Notebook Skill

Overview

概述

Notebook Document Structure

Notebook文档结构

When to Load References

引用文件加载规则

Working with Notebooks

操作Notebook

Notebook Structure

Notebook结构规范

Root Properties

根属性

Sections Overview

章节概览

Schema Validation

Schema校验

References

引用

Common Patterns & Best Practices

通用模式与最佳实践

Related Skills

相关技能