Back to Details

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

推荐初始化流程

At the start of a task, run these checks to establish context and permissions:
bash
undefined
在任务开始时，运行以下检查以确认上下文和权限信息：
bash
undefined

Discover all available commands, flags, and resources

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

dtctl commands --brief -o json
dtctl commands --brief -o json

Show current context

展示当前上下文

dtctl config current-context
dtctl config current-context

Show context details

展示上下文详情

dtctl config describe-context $(dtctl config current-context) --plain
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
.
ResourceAliases
analyzeranalyzers
appapps
bucketbkt
copilot-skillcopilot-skills
dashboarddash
edgeconnectec
extensionext, extensions
extension-configextcfg, extension-configs
functionfn, func
groupgroups
intentintents
lookuplookups, lkup
notebooknb
notificationnotifications
sdk-versionsdk-versions
settingssetting
settings-schemaschema
slo-
slo-templateslo-templates
trashdeleted
userusers
workflowwf
workflow-executionwfe
Use IDs whenever possible instead of names to avoid ambiguity.
dtctl 对所有资源类型使用统一的操作模式。你可以通过 
dtctl describe <resource> <id> -o json --plain
命令的实际输出获取资源 schema。
资源别名
analyzeranalyzers
appapps
bucketbkt
copilot-skillcopilot-skills
dashboarddash
edgeconnectec
extensionext, extensions
extension-configextcfg, extension-configs
functionfn, func
groupgroups
intentintents
lookuplookups, lkup
notebooknb
notificationnotifications
sdk-versionsdk-versions
settingssetting
settings-schemaschema
slo-
slo-templateslo-templates
trashdeleted
userusers
workflowwf
workflow-executionwfe
为避免歧义，请优先使用ID而非名称操作资源。

Command Verbs

命令动词

VerbDescriptionExample
getList resources
dtctl get workflows --mine
describeShow resource details
dtctl describe workflow <id>
editEdit resource interactively
dtctl edit dashboard <id>
applyCreate/update from file
dtctl apply -f workflow.yaml --set env=prod
deleteDelete resource
dtctl delete workflow <id>
execExecute workflow/function/analyzer/copilot
dtctl exec workflow <id>
queryRun DQL query
dtctl query "fetch logs | limit 10"
logsPrint resource logs
dtctl logs workflow-execution <id>
waitWait for conditions
dtctl wait query "fetch logs" --for=any
historyShow document history
dtctl history dashboard <id>
restoreRestore document version
dtctl restore dashboard <id> --version 3
shareShare document
dtctl share dashboard <id> --user email@example.com
unshareRemove sharing
dtctl unshare dashboard <id> --user email@example.com
findDiscover resources
dtctl find intents --data trace.id=abc
openOpen in browser
dtctl open intent <app/intent> --data key=value
diffCompare resources
dtctl diff -f workflow.yaml
verifyValidate without executing
dtctl verify query 'fetch logs' --fail-on-warn
commandsList 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

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

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
dtctl get copilot-skills -o json --plain

Functions

函数

dtctl get functions -o json --plain dtctl exec function <id-or-name> --payload '{"key":"value"}' --plain
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:
  1. First consult 
    references/DQL-reference.md
  2. Build/validate the query using the documented patterns
  3. Execute with 
    dtctl query ... -o json --plain
    (or 
    dtctl wait query ...
    when waiting for results)
bash
undefined
DQL数据拉取必须遵循的流程：
  1. 首先查阅
    references/DQL-reference.md
  2. 参考文档中记录的模式构建/校验查询语句
  3. 使用
    dtctl query ... -o json --plain
    执行（等待结果时使用
    dtctl wait query ...
    ）
bash
undefined

Inline query

内联查询

dtctl query "fetch logs | filter status='ERROR' | limit 100" -o json --plain
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
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
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:
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)"'
权限被拒绝：
上下文/安全拦截：
  • 破坏性操作可能被安全级别拦截
  • 切换上下文：
    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