dt-app-dashboards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dynatrace Dashboard Skill

Dynatrace 仪表盘技能

Overview

概述

Dynatrace dashboards are JSON documents stored in the Document Store. Each dashboard contains:

Tiles: Visual components displaying markdown content or data visualizations
Layouts: Grid-based positioning (20-unit width) defining tile placement
Variables: Dynamic parameters (
```
$VariableName
```
) for query filtering
Configuration: Version metadata and dashboard-level settings

When to use this skill:

Creating new dashboards with skill-based query generation
Modifying existing dashboards (queries, tiles, layouts)
Querying dashboard JSON to extract data or analyze structure
Analyzing dashboard purpose, metrics coverage, and health

Four main workflows:

Creating - Build dashboards with skill-based queries
Modifying - Update tiles, queries, layouts, variables
Querying - Extract data from dashboard JSON
Analyzing - Understand structure, purpose, gaps, and health

Dynatrace仪表盘是存储在文档存储中的JSON文档。每个仪表盘包含：

Tiles：展示markdown内容或数据可视化的视觉组件
Layouts：基于网格的定位（宽度为20个单位），用于定义tile的摆放位置
Variables：用于查询过滤的动态参数（
```
$VariableName
```
）
配置：版本元数据和仪表盘层级的设置

何时使用该技能：

基于技能生成查询来创建新仪表盘
修改现有仪表盘（查询、tiles、布局）
查询仪表盘JSON以提取数据或分析结构
分析仪表盘的用途、指标覆盖范围和健康状态

四个主要工作流：

创建 - 基于技能生成的查询构建仪表盘
修改 - 更新tiles、查询、布局、variables
查询 - 从仪表盘JSON中提取数据
分析 - 了解结构、用途、缺口和健康状态

Dashboard Document Structure

仪表盘文档结构

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

json

{
  "id": "dashboard-abc123",
  "name": "My Dashboard",  
  "type": "dashboard",
  "owner": "user-uuid",
  "version": 60,
  "modificationInfo": {...},
  "content": {
    "version": 21,
    "variables": [],
    "tiles": {...},
    "layouts": {...}
  }
}

Metadata (top-level):

```
.id
```
- Document ID
```
.name
```
- Dashboard name
```
.owner
```
- Owner UUID
```
.version
```
- Document version (change tracking)
```
.modificationInfo
```
- Creation/modification timestamps

Dashboard content (
.content
):

```
.content.version
```
- Dashboard schema version (current: 21)
```
.content.tiles
```
- Tile definitions
```
.content.layouts
```
- Tile positioning
```
.content.variables
```
- Dashboard variables

All jq examples in this skill use the

.content.*

paths.

Dynatrace文档存储中的仪表盘同时包含元数据和内容：

json

{
  "id": "dashboard-abc123",
  "name": "My Dashboard",  
  "type": "dashboard",
  "owner": "user-uuid",
  "version": 60,
  "modificationInfo": {...},
  "content": {
    "version": 21,
    "variables": [],
    "tiles": {...},
    "layouts": {...}
  }
}

元数据（顶层）：

```
.id
```
- 文档ID
```
.name
```
- 仪表盘名称
```
.owner
```
- 所有者UUID
```
.version
```
- 文档版本（变更跟踪）
```
.modificationInfo
```
- 创建/修改时间戳

仪表盘内容（
.content
）：

```
.content.version
```
- 仪表盘schema版本（当前：21）
```
.content.tiles
```
- Tile定义
```
.content.layouts
```
- Tile定位
```
.content.variables
```
- 仪表盘变量

本技能中的所有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 Dashboards

使用仪表盘

For detailed workflows and mandatory requirements:

Creating & Updating dashboards → Load
```
references/create-update.md
```
for complete workflow, skill-based query generation, validation, and modification patterns
Analyzing dashboards → Load
```
references/analyzing.md
```
for structure analysis, health assessment, and JSON extraction

⚠️ MANDATORY for creation/modification:

Follow this exact order (do not reorder):

Define purpose and load required skills, references and assets
Explore available data fields/metrics
Plan dashboard structure: logic, variables, tiles and layout
Design and validate all variable/tile DQL with
```
dtctl query "<DQL>" --plain
```
Construct/update dashboard JSON
Validate the dashboard JSON structure and queries
Deploy the dashboard via the Dynatrace API

Full requirements and examples:

references/create-update.md

如需了解详细工作流和强制要求：

创建和更新仪表盘 → 加载
```
references/create-update.md
```
获取完整工作流、基于技能的查询生成、验证和修改模式
分析仪表盘 → 加载
```
references/analyzing.md
```
获取结构分析、健康评估和JSON提取相关内容

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

严格遵循以下顺序（不得调整顺序）：

明确用途，加载所需的技能、参考文档和资源
探索可用的数据字段/指标
规划仪表盘结构：逻辑、variables、tiles和布局
用
```
dtctl query "<DQL>" --plain
```
设计并验证所有variable/tile的DQL
构建/更新仪表盘JSON
验证仪表盘JSON结构和查询
通过Dynatrace API部署仪表盘

完整要求和示例见：

references/create-update.md

。

Dashboard Structure

仪表盘结构

Required Structure

必填结构

json

{
  "name": "My Dashboard",
  "type": "dashboard",
  "content": {
    "version": 21,
    "tiles": {},
    "layouts": {}
  }
}

Optional properties inside content:

```
variables
```
- Array of dashboard variables (filters/parameters)
```
settings
```
- Dashboard-level settings (grid layout, default timeframe)
```
refreshRate
```
- Dashboard refresh rate in milliseconds (e.g., 60000)
```
gridColumnsCount
```
- Number of grid columns (default: 20)
```
annotations
```
- Array of dashboard annotations

Structure concept: Variables define reusable parameters, tiles contain content/visualizations, layouts control positioning. Each tile ID in

tiles

must have a corresponding entry in

layouts

json

{
  "name": "My Dashboard",
  "type": "dashboard",
  "content": {
    "version": 21,
    "tiles": {},
    "layouts": {}
  }
}

content内的可选属性：

```
variables
```
- 仪表盘变量数组（过滤器/参数）
```
settings
```
- 仪表盘层级设置（网格布局、默认时间范围）
```
refreshRate
```
- 仪表盘刷新频率，单位为毫秒（例如：60000）
```
gridColumnsCount
```
- 网格列数（默认：20）
```
annotations
```
- 仪表盘注释数组

结构概念： Variables定义可复用的参数，tiles包含内容/可视化，layouts控制定位。

tiles

中的每个tile ID必须在

layouts

中有对应的条目。

Tiles Overview

Tiles 概述

📊 For detailed tile specifications, visualization settings, and query configuration, load
references/tiles.md

Markdown tiles:

{"type": "markdown", "content": "# Title"}

Data tiles:

{"type": "data", "title": "...", "query": "...", "visualization": "..."}

Visualizations:

Time-series (MUST have time dimension via

timeseries

makeTimeseries

lineChart

areaChart

barChart

bandChart

Categorical (no time dimension,

summarize ... by:{field}

categoricalBarChart

pieChart

donutChart

Single value / gauge (single numeric record):
```
singleValue
```
,
```
meterBar
```
,
```
gauge
```
Tabular / raw (any data shape):
```
table
```
,
```
raw
```
,
```
recordList
```
Distribution / status:
```
histogram
```
,
```
honeycomb
```

Geographic maps:

choroplethMap

dotMap

connectionMap

bubbleMap

Matrix / correlation:
```
heatmap
```
,
```
scatterplot
```

→ See references/tiles.md for specifications

📊 如需了解详细的tile规范、可视化设置和查询配置，请加载
references/tiles.md

Markdown tiles：

{"type": "markdown", "content": "# Title"}

数据tiles：

{"type": "data", "title": "...", "query": "...", "visualization": "..."}

可视化类型：

时间序列（必须通过
```
timeseries
```
/
```
makeTimeseries
```
包含时间维度）：
```
lineChart
```
、
```
areaChart
```
、
```
barChart
```
、
```
bandChart
```

分类（无时间维度，

summarize ... by:{field}

）：

categoricalBarChart

、

pieChart

、

donutChart

单值/仪表盘（单个数值记录）：
```
singleValue
```
、
```
meterBar
```
、
```
gauge
```
表格/原始数据（任意数据结构）：
```
table
```
、
```
raw
```
、
```
recordList
```
分布/状态：
```
histogram
```
、
```
honeycomb
```

地理地图：

choroplethMap

、

dotMap

、

connectionMap

、

bubbleMap

矩阵/相关性：
```
heatmap
```
、
```
scatterplot
```

→ 查看references/tiles.md获取规范

Layouts Overview

Layouts 概述

📐 For complex layout patterns, grid system details, and positioning examples, load
references/layouts.md

Grid: 20 units wide. Common widths: Full (20), Half (10), Third (6-7), Quarter (5) Properties:

(0-19),

(0+),

(1-20),

(1-20)

Example:

{"1": {"x": 0, "y": 0, "w": 20, "h": 1}, "2": {"x": 0, "y": 1, "w": 10, "h": 8}}

→ See references/layouts.md for patterns

📐 如需了解复杂布局模式、网格系统细节和定位示例，请加载
references/layouts.md

网格： 宽度为20个单位。常用宽度：全屏（20）、半屏（10）、三分之一（6-7）、四分之一（5） 属性：

（0-19）、

（0及以上）、

（1-20）、

（1-20）

示例：

{"1": {"x": 0, "y": 0, "w": 20, "h": 1}, "2": {"x": 0, "y": 1, "w": 10, "h": 8}}

→ 查看references/layouts.md获取布局模式

Variables Overview

Variables 概述

🔧 For detailed variable configurations, replacement strategies, multi-select, and limitations, load
references/variables.md

Definition:

{"version": 2, "key": "ServiceFilter", "type": "query", "visible": true, "editable": true, "input": "smartscapeNodes SERVICE | fields name", "multiple": false, "defaultValue": "*"}

Usage (single-select):

fetch logs | filter service.name == $ServiceFilter

Usage (multi-select):

fetch logs | filter in(service.name, array($ServiceFilter))

→ See references/variables.md for complete property reference, replacement strategies (
:noquote
,
:backtick
), and usage patterns

🔧 如需了解详细的变量配置、替换策略、多选功能和限制，请加载
references/variables.md

定义示例：

{"version": 2, "key": "ServiceFilter", "type": "query", "visible": true, "editable": true, "input": "smartscapeNodes SERVICE | fields name", "multiple": false, "defaultValue": "*"}

用法（单选）：

fetch logs | filter service.name == $ServiceFilter

用法（多选）：

fetch logs | filter in(service.name, array($ServiceFilter))

→ 查看references/variables.md获取完整的属性参考、替换策略（

:noquote

、

:backtick

）和使用模式

Validation

验证

⚠️ MANDATORY for create/update workflows: Validate the dashboard JSON before deploying. Check:

Schema structure — required top-level keys (
```
name
```
,
```
type
```
,
```
content
```
) and content keys (
```
version
```
,
```
variables
```
,
```
tiles
```
,
```
layouts
```
)
Variable resolution — all variable queries execute successfully
Tile query execution — all tile DQL queries run without errors
Best-practice checks — warnings for hardcoded time filters, CSV variables, etc.

→ Load

references/create-update.md

for full validation workflow.

⚠️ 创建/更新工作流的强制要求： 部署前必须验证仪表盘JSON。检查项包括：

Schema结构 — 必填的顶层键（
```
name
```
、
```
type
```
、
```
content
```
）和content内的键（
```
version
```
、
```
variables
```
、
```
tiles
```
、
```
layouts
```
）
变量解析 — 所有变量查询都能成功执行
Tile查询执行 — 所有tile的DQL查询运行无错误
最佳实践检查 — 对硬编码时间过滤器、CSV变量等情况发出警告

→ 加载

references/create-update.md

获取完整的验证工作流。

References

参考文档

Reference File	When to Use
create-update.md	Creating and updating dashboards - workflows, skill-based queries, validation, patterns
tiles.md	Tile types, visualization settings, query configuration, thresholds
layouts.md	Grid system details, layout patterns, positioning examples
variables.md	Variable types, multi-select, default values, query integration
analyzing.md	Structure analysis, purpose identification, health assessment, JSON extraction

参考文件	使用场景
create-update.md	创建和更新仪表盘 - 工作流、基于技能的查询、验证、模式
tiles.md	Tile类型、可视化设置、查询配置、阈值
layouts.md	网格系统细节、布局模式、定位示例
variables.md	变量类型、多选、默认值、查询集成
analyzing.md	结构分析、用途识别、健康评估、JSON提取

Common Patterns & Best Practices

通用模式与最佳实践

Patterns: Executive (header + KPIs + trends) · Service Health (RED metrics) · Infrastructure (resource metrics + tables)

Key rules: Match tile IDs in

tiles

and

layouts

· Use descriptive variable IDs · Start with full-width headers (y=0) · Optimize queries with

limit

summarize

· Set version=21 · No time-range filters in queries unless explicitly requested by the user

模式： 高管视图（标题 + KPI + 趋势） · 服务健康（RED指标） · 基础设施（资源指标 + 表格）

核心规则： 匹配

tiles

和

layouts

中的tile ID · 使用表意清晰的变量ID · 以全屏宽度的标题开头（y=0） · 用

limit

summarize

优化查询 · 设置version=21 · 查询中不要包含时间范围过滤器，除非用户明确要求。