dtctl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dynatrace Control with dtctl

使用 dtctl 管控 Dynatrace

Operate

dtctl

, the kubectl-style CLI for Dynatrace. This skill teaches core dtctl command patterns and operations.

操作

dtctl

，这是 Dynatrace 推出的类 kubectl 风格 CLI。本技能讲解 dtctl 的核心命令模式和操作方法。

Recommended Initialization

Discover all available commands, flags, and resources

查看所有可用命令、参数和资源

dtctl commands --brief -o json

Show current context

展示当前上下文

dtctl config current-context

Show context details

展示上下文详情

dtctl config describe-context $(dtctl config current-context) --plain

Show authenticated user

展示已认证用户信息

dtctl auth whoami --plain


This displays:
- Current context name and environment URL
- Safety level (readonly, readwrite-mine, readwrite-all, dangerously-unrestricted)
- Authenticated user identity (name, email, UUID)

dtctl auth whoami --plain


上述命令会输出以下内容：
- 当前上下文名称和环境URL
- 安全级别（readonly、readwrite-mine、readwrite-all、dangerously-unrestricted）
- 已认证用户身份（姓名、邮箱、UUID）

DQL Reference Usage

DQL 参考使用规则

Before writing, modifying, or executing any DQL that fetches Dynatrace data (for example via

dtctl query

dtctl wait query

, or query files), you MUST consult

references/DQL-reference.md

and follow its documented syntax and templates.

If there is any conflict between memory/assumptions and the reference, prefer the reference.

在编写、修改或执行任何拉取 Dynatrace 数据的 DQL 语句（例如通过

dtctl query

、

dtctl wait query

或查询文件执行）之前，你必须查阅

references/DQL-reference.md

并遵循其文档中规定的语法和模板。

如果记忆/假设内容与参考文档存在冲突，以参考文档为准。

Prerequisites

前置条件

If dtctl is not installed or not working, see references/troubleshooting.md for installation and setup.

如果 dtctl 未安装或无法正常运行，请查看 references/troubleshooting.md 了解安装和配置方法。

Resources & Commands

资源与命令

Available Resources

可用资源

dtctl uses a uniform pattern for all resource types. Discover schema from actual output with

dtctl describe <resource> <id> -o json --plain

Resource	Aliases
analyzer	analyzers
app	apps
bucket	bkt
copilot-skill	copilot-skills
dashboard	dash
edgeconnect	ec
extension	ext, extensions
extension-config	extcfg, extension-configs
function	fn, func
group	groups
intent	intents
lookup	lookups, lkup
notebook	nb
notification	notifications
sdk-version	sdk-versions
settings	setting
settings-schema	schema
slo	-
slo-template	slo-templates
trash	deleted
user	users
workflow	wf
workflow-execution	wfe

Use IDs whenever possible instead of names to avoid ambiguity.

dtctl 对所有资源类型使用统一的操作模式。你可以通过

dtctl describe <resource> <id> -o json --plain

命令的实际输出获取资源 schema。

资源	别名
analyzer	analyzers
app	apps
bucket	bkt
copilot-skill	copilot-skills
dashboard	dash
edgeconnect	ec
extension	ext, extensions
extension-config	extcfg, extension-configs
function	fn, func
group	groups
intent	intents
lookup	lookups, lkup
notebook	nb
notification	notifications
sdk-version	sdk-versions
settings	setting
settings-schema	schema
slo	-
slo-template	slo-templates
trash	deleted
user	users
workflow	wf
workflow-execution	wfe

为避免歧义，请优先使用ID而非名称操作资源。

Command Verbs

命令动词

Verb	Description	Example
get	List resources	`dtctl get workflows --mine`
describe	Show resource details	`dtctl describe workflow <id>`
edit	Edit resource interactively	`dtctl edit dashboard <id>`
apply	Create/update from file	`dtctl apply -f workflow.yaml --set env=prod`
delete	Delete resource	`dtctl delete workflow <id>`
exec	Execute workflow/function/analyzer/copilot	`dtctl exec workflow <id>`
query	Run DQL query	`dtctl query "fetch logs \| limit 10"`
logs	Print resource logs	`dtctl logs workflow-execution <id>`
wait	Wait for conditions	`dtctl wait query "fetch logs" --for=any`
history	Show document history	`dtctl history dashboard <id>`
restore	Restore document version	`dtctl restore dashboard <id> --version 3`
share	Share document	`dtctl share dashboard <id> --user email@example.com`
unshare	Remove sharing	`dtctl unshare dashboard <id> --user email@example.com`
find	Discover resources	`dtctl find intents --data trace.id=abc`
open	Open in browser	`dtctl open intent <app/intent> --data key=value`
diff	Compare resources	`dtctl diff -f workflow.yaml`
verify	Validate without executing	`dtctl verify query 'fetch logs' --fail-on-warn`
commands	List all commands (machine-readable)	`dtctl commands --brief -o json`

动词	描述	示例
get	列出资源	`dtctl get workflows --mine`
describe	展示资源详情	`dtctl describe workflow <id>`
edit	交互式编辑资源	`dtctl edit dashboard <id>`
apply	从文件创建/更新资源	`dtctl apply -f workflow.yaml --set env=prod`
delete	删除资源	`dtctl delete workflow <id>`
exec	执行工作流/函数/分析器/copilot	`dtctl exec workflow <id>`
query	运行DQL查询	`dtctl query "fetch logs \| limit 10"`
logs	打印资源日志	`dtctl logs workflow-execution <id>`
wait	等待条件满足	`dtctl wait query "fetch logs" --for=any`
history	展示文档历史版本	`dtctl history dashboard <id>`
restore	恢复文档版本	`dtctl restore dashboard <id> --version 3`
share	共享文档	`dtctl share dashboard <id> --user email@example.com`
unshare	取消共享	`dtctl unshare dashboard <id> --user email@example.com`
find	搜索资源	`dtctl find intents --data trace.id=abc`
open	在浏览器中打开	`dtctl open intent <app/intent> --data key=value`
diff	对比资源	`dtctl diff -f workflow.yaml`
verify	校验而不执行	`dtctl verify query 'fetch logs' --fail-on-warn`
commands	列出所有命令（机器可读格式）	`dtctl commands --brief -o json`

Key Concepts for AI Agents

AI Agent 核心概念

Output Modes

输出模式

bash

undefined

bash

undefined

Agent envelope mode (auto-detected in AI environments)

Agent 封装模式（AI环境下自动检测）

-A, --agent # Structured JSON envelope with ok/result/error/context --no-agent # Opt out of auto-detected agent mode

-A, --agent # 包含 ok/result/error/context 字段的结构化JSON封装 --no-agent # 退出自动检测的Agent模式

Machine-readable formats (use these for AI agents)

机器可读格式（推荐AI Agent使用）

-o json # JSON output -o yaml # YAML output -o csv # CSV output -o chart # ASCII chart (for time series) -o sparkline # ASCII sparkline (for time series) -o barchart # ASCII bar chart (for time series)

-o json # JSON格式输出 -o yaml # YAML格式输出 -o csv # CSV格式输出 -o chart # ASCII图表（适用于时间序列数据） -o sparkline # ASCII迷你图（适用于时间序列数据） -o barchart # ASCII柱状图（适用于时间序列数据）

Human-readable formats

人类可读格式

-o table # Table format (default) -o wide # Wide table with more columns

-o table # 表格格式（默认） -o wide # 包含更多列的宽表格

Always use --plain flag for AI consumption (implied by --agent)

AI消费场景请始终使用--plain参数（--agent参数会自动启用该特性）

--plain # Strips colors and prompts, best for parsing


**For AI agents, prefer:** `dtctl <command> --agent` (auto-detected) or `dtctl <command> -o json --plain`

The `--agent` envelope provides structured metadata alongside results:

```json
{
  "ok": true,
  "result": [ ... ],
  "context": {
    "verb": "get", "resource": "workflow",
    "total": 5, "has_more": false,
    "suggestions": ["Run 'dtctl describe workflow <id>' for details"]
  }
}

--plain # 去掉颜色和提示符，最适合程序解析


**AI Agent 场景优先使用：** `dtctl <command> --agent`（自动检测）或 `dtctl <command> -o json --plain`

`--agent` 封装模式会在返回结果外附带结构化元数据：

```json
{
  "ok": true,
  "result": [ ... ],
  "context": {
    "verb": "get", "resource": "workflow",
    "total": 5, "has_more": false,
    "suggestions": ["Run 'dtctl describe workflow <id>' for details"]
  }
}

Template Variables

模板变量

In YAML/DQL files, use Go template syntax:

yaml

undefined

在YAML/DQL文件中，可以使用Go模板语法：

yaml

undefined

workflow.yaml

title: "{{.environment}} Deployment" owner: "{{.team}}" trigger: schedule: cron: "{{.schedule | default "0 0 * * *"}}"


```dql

title: "{{.environment}} Deployment" owner: "{{.team}}" trigger: schedule: cron: "{{.schedule | default "0 0 * * *"}}"


```dql

query.dql

fetch logs | filter host.name == "{{.host}}" | filter timestamp > now() - {{.timerange | default "1h"}}


Execute with: `dtctl apply -f file.yaml --set environment=prod --set team=platform`

fetch logs | filter host.name == "{{.host}}" | filter timestamp > now() - {{.timerange | default "1h"}}


执行命令：`dtctl apply -f file.yaml --set environment=prod --set team=platform`

Copilot, Functions, Analyzers

Copilot、函数、分析器

bash

undefined

bash

undefined

Copilot skills

Copilot技能

dtctl get copilot-skills -o json --plain

Functions

函数

dtctl get functions -o json --plain dtctl exec function <id-or-name> --payload '{"key":"value"}' --plain

Analyzers

分析器

dtctl get analyzers -o json --plain dtctl exec analyzer <id-or-name> --input '{"timeframe":"now-2h"}' --plain


Prefer `get ... -o json --plain` first, then `describe`/`exec` with explicit IDs.

dtctl get analyzers -o json --plain dtctl exec analyzer <id-or-name> --input '{"timeframe":"now-2h"}' --plain


优先使用 `get ... -o json --plain` 拉取列表，再通过明确的ID执行`describe`/`exec`操作。

Authentication & Permissions

认证与权限

bash

undefined

bash

undefined

Check current user and permissions

检查当前用户和权限

dtctl auth whoami --plain dtctl auth can-i create workflows dtctl auth can-i delete dashboards


Use `can-i` to verify permissions before attempting operations.

dtctl auth whoami --plain dtctl auth can-i create workflows dtctl auth can-i delete dashboards


尝试操作前使用`can-i`命令验证权限。

Quick Reference: DQL Queries

快速参考：DQL查询

Required workflow for DQL data fetching:

First consult
```
references/DQL-reference.md
```
Build/validate the query using the documented patterns

Execute with

dtctl query ... -o json --plain

(or

dtctl wait query ...

when waiting for results)

bash

undefined

DQL数据拉取必须遵循的流程：

首先查阅
```
references/DQL-reference.md
```
参考文档中记录的模式构建/校验查询语句

使用

dtctl query ... -o json --plain

执行（等待结果时使用

dtctl wait query ...

）

bash

undefined

Inline query

内联查询

dtctl query "fetch logs | filter status='ERROR' | limit 100" -o json --plain

Query from file with variables

带变量的文件查询

dtctl query -f query.dql --set host=h-123 --set timerange=2h -o json --plain

Wait for query results

等待查询结果

dtctl wait query "fetch spans | filter test_id='test-123'" --for=count=1 --timeout 5m

Query with chart output

图表格式输出查询结果

dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain

undefined

dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain

undefined

Dashboards

仪表板

For full examples and field-level gotchas, see references/resources/dashboards.md.

Create/update:

dtctl apply -f dashboard.yaml --plain

. Export for reference:

dtctl get dashboard <id> -o yaml --plain

完整示例和字段注意事项请查看 references/resources/dashboards.md。

创建/更新命令：

dtctl apply -f dashboard.yaml --plain

。导出参考配置命令：

dtctl get dashboard <id> -o yaml --plain

。

YAML skeleton

YAML 结构框架

yaml

name: "Dashboard Name"
type: dashboard
content:
  annotations: []
  importedWithCode: false
  settings:
    defaultTimeframe:
      enabled: true
      value: { from: now()-2h, to: now() }
  layouts:
    "1":                    # string key, must match a tile key
      x: 0                 # 24-column grid (full=24, half=12, third=8)
      "y": 0               # MUST quote "y" to avoid YAML boolean parse
      w: 12
      h: 6
  tiles:
    "1":
      title: "Tile Title"
      type: data            # data | markdown
      query: |
        fetch logs | limit 10
      visualization: lineChart
      visualizationSettings:
        autoSelectVisualization: false
      davis: { enabled: false, davisVisualization: { isAvailable: true } }

yaml

name: "Dashboard Name"
type: dashboard
content:
  annotations: []
  importedWithCode: false
  settings:
    defaultTimeframe:
      enabled: true
      value: { from: now()-2h, to: now() }
  layouts:
    "1":                    # 字符串键，必须与对应的tile键匹配
      x: 0                 # 24列网格（整行=24，半行=12，三分之一行=8）
      "y": 0               # 必须给"y"加引号，避免被YAML解析为布尔值
      w: 12
      h: 6
  tiles:
    "1":
      title: "Tile Title"
      type: data            # data | markdown
      query: |
        fetch logs | limit 10
      visualization: lineChart
      visualizationSettings:
        autoSelectVisualization: false
      davis: { enabled: false, davisVisualization: { isAvailable: true } }

Tile types & visualizations

卡片类型与可视化配置

type: data
— DQL tile with

query

visualization

singleValue

lineChart

areaChart

barChart

pieChart

table

honeycomb

scatterplot

type: markdown
— static text via
```
content
```
field (supports markdown)

For detailed visualizationSettings (singleValue, charts, tables, thresholds, unit overrides), see references/resources/dashboards.md.

type: data
— 带

query

visualization

的DQL卡片：可选可视化类型包括

singleValue

、

lineChart

、

areaChart

、

barChart

、

pieChart

、

table

、

honeycomb

、

scatterplot

type: markdown
— 通过
```
content
```
字段配置的静态文本（支持markdown语法）

详细的visualizationSettings配置（单值、图表、表格、阈值、单位覆盖）请查看 references/resources/dashboards.md。

Gotchas

注意事项

Always set
```
davis.enabled: false
```
on data tiles.
Use
```
makeTimeseries
```
for log/span time series;
```
timeseries
```
for metrics.
```
version
```
field warning on create is benign.
No
```
id
```
field → creates new; with
```
id
```
field → updates existing.

数据卡片必须设置
```
davis.enabled: false
```
日志/span时间序列使用
```
makeTimeseries
```
，指标时间序列使用
```
timeseries
```
创建时的
```
version
```
字段警告是良性的，可以忽略
没有
```
id
```
字段→创建新资源；带
```
id
```
字段→更新现有资源

Common Issues

常见问题

Name resolution ambiguity:

If a name matches multiple resources, dtctl will fail
Solution: Use IDs instead of names

Find ID:

dtctl get <resource> -o json --plain | jq -r '.[] | "\(.id) | \(.name)"'

Permission denied:

Check token scopes: https://github.com/dynatrace-oss/dtctl/blob/main/docs/TOKEN_SCOPES.md
Verify permissions:
```
dtctl auth can-i <verb> <resource>
```

Check safety level:

dtctl config describe-context $(dtctl config current-context) --plain

Context/safety blocks:

Destructive operations may be blocked by safety level
Switch context:
```
dtctl config use-context <name>
```
Adjust safety level when creating context

名称解析歧义：

如果一个名称匹配多个资源，dtctl会执行失败
解决方案：使用ID而非名称操作

查找ID命令：

dtctl get <resource> -o json --plain | jq -r '.[] | "\(.id) | \(.name)"'

权限被拒绝：

检查Token作用域：https://github.com/dynatrace-oss/dtctl/blob/main/docs/TOKEN_SCOPES.md
验证权限：
```
dtctl auth can-i <verb> <resource>
```

检查安全级别：

dtctl config describe-context $(dtctl config current-context) --plain

上下文/安全拦截：

破坏性操作可能被安全级别拦截
切换上下文：
```
dtctl config use-context <name>
```
创建上下文时可以调整安全级别

Additional Resources

额外资源

Troubleshooting: references/troubleshooting.md
Multi-tenant setup: references/config-management.md
DQL syntax and templates: references/DQL-reference.md
Notebooks: references/resources/notebooks.md
Extensions: references/resources/extensions.md
CLI help:
```
dtctl --help
```
,
```
dtctl <command> --help
```

故障排查: references/troubleshooting.md
多租户配置: references/config-management.md
DQL语法与模板: references/DQL-reference.md
笔记本: references/resources/notebooks.md
扩展: references/resources/extensions.md
CLI帮助:
```
dtctl --help
```
,
```
dtctl <command> --help
```

Safety Reminders

安全提醒

Use
```
--plain
```
for machine/AI consumption
Confirm context + safety level before destructive ops; prefer
```
get/describe
```
first
Use
```
--mine
```
flag to filter resources you own
For multi-tenant work, see references/config-management.md

机器/AI消费场景使用
```
--plain
```
参数
执行破坏性操作前确认上下文和安全级别；优先执行
```
get/describe
```
确认资源
使用
```
--mine
```
参数过滤你拥有的资源
多租户场景操作请查看 references/config-management.md

dtctl

Original

Translation

Dynatrace Control with dtctl

使用 dtctl 管控 Dynatrace

Recommended Initialization

推荐初始化流程

Discover all available commands, flags, and resources

查看所有可用命令、参数和资源

Show current context

展示当前上下文

Show context details

展示上下文详情

Show authenticated user

展示已认证用户信息

DQL Reference Usage

DQL 参考使用规则

Prerequisites

前置条件

Resources & Commands

资源与命令

Available Resources

可用资源

Command Verbs

命令动词

Key Concepts for AI Agents

AI Agent 核心概念

Output Modes

输出模式

Agent envelope mode (auto-detected in AI environments)

Agent 封装模式（AI环境下自动检测）

Machine-readable formats (use these for AI agents)

机器可读格式（推荐AI Agent使用）

Human-readable formats

人类可读格式

Always use --plain flag for AI consumption (implied by --agent)

AI消费场景请始终使用--plain参数（--agent参数会自动启用该特性）

Template Variables

模板变量

workflow.yaml

workflow.yaml

query.dql

query.dql

Copilot, Functions, Analyzers

Copilot、函数、分析器

Copilot skills

Copilot技能

Functions

函数

Analyzers

分析器

Authentication & Permissions

认证与权限

Check current user and permissions

检查当前用户和权限

Quick Reference: DQL Queries

快速参考：DQL查询

Inline query

内联查询

Query from file with variables

带变量的文件查询

Wait for query results

等待查询结果

Query with chart output

图表格式输出查询结果

Dashboards

仪表板

YAML skeleton

YAML 结构框架

Tile types & visualizations

卡片类型与可视化配置

Gotchas

注意事项

Common Issues

常见问题

Additional Resources

额外资源

Safety Reminders

安全提醒