dtctl

使用 dtctl 控制 Dynatrace

使用 dtctl（Dynatrace 的 kubectl 风格 CLI）。格式：dtctl <verb> <resource> [flags]。

初始化

运行一次以建立上下文、权限和命令目录：

dtctl commands                          # compact overview: verbs, resources, subcommands (TOON default)
# dtctl commands --brief                 # + mutating/access/scopes + flag types
# dtctl commands --full                  # exhaustive catalog: descriptions, flag defaults, global flags
dtctl config current-context            # active context
dtctl config describe-context $(dtctl config current-context) --plain  # env URL + safety level
dtctl auth status --plain               # token type (OAuth vs API/platform) + safety level
dtctl inventory                         # what data exists HERE: fetchable objects, buckets, entity census, capabilities

安全级别：readonly、readwrite-mine、readwrite-all、dangerously-unrestricted。

dtctl commands 回答“我可以运行什么？”，dtctl inventory 回答“有哪些内容可供查询？”——开始探索性 DQL 前先运行它。它会将目录对象划分为可获取与仅可查询（切勿运行 fetch metrics 或 fetch smartscape.*），并报告功能状态为已具备、未具备（附已检查的证据——引用该证据即可，无需再次探查）或未知（没有结论；不能据此证明功能不存在）。组织专属的功能定义：--definitions file.yaml。

不要使用 dtctl auth whoami 测试连通性——它需要带有 app-engine:apps:run 权限的 OAuth 令牌；对于普通 API 令牌或仅具读取权限的令牌，即使读取操作正常，也会返回误导性的 403。请通过实际的 get/query 确认。

DQL（必读）

在编写、修改或运行任何 DQL（dtctl query、dtctl wait query、查询文件）之前，请查阅 references/DQL-reference.md，并以其中内容为准，不要依赖任何假设或记忆。

dtctl query "fetch logs | filter status='ERROR' | limit 100" -o json --plain
dtctl query -f query.dql --set host=h-123 --set timerange=2h -o json --plain   # Go-template vars
dtctl wait query "fetch spans | filter test_id='test-123'" --for=count=1 --timeout 5m
dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain

按扫描字节数计费的 fetch（日志、事件、业务事件、跨度）会产生费用；仪表板磁贴每次刷新都会重新计费——生成 DQL 前请阅读 references/DQL-reference.md 中的“扫描成本”，并将 PARTIAL 或采样结果视为不完整结果。

dtctl 未安装或无法正常运行？请参阅 references/troubleshooting.md。

配套技能（Dynatrace for AI）

此技能涵盖 dtctl 的操作。Dynatrace for AI 技能包提供领域知识：dt-dql-essentials（DQL 语法、易错点、查询优化）、dt-obs-*（日志、问题、服务、追踪、主机、kubernetes、前端、aws/azure/gcp）以及 dt-app-dashboards / dt-app-notebooks。加载这些技能后，用它们决定查询什么，并用 dtctl 执行。若未加载，请告知用户可以通过 npx skills add dynatrace/dynatrace-for-ai 添加；不要未经询问就安装。

资源与动词

可通过 dtctl commands（初始化时运行）发现资源及其别名。包括：analyzer、anomaly-detector、app、aws/azure/gcp connection & monitoring、bucket、copilot-skill、dashboard、document、edgeconnect、environment、extension、extension-config、function、group、intent、license、license-settings、lookup、notebook、notification、sdk-version、segment、settings、settings-schema、slo、slo-template、trash、user、workflow、workflow-execution。使用 ID，不要使用名称——名称可能有歧义并导致失败。

动词	示例
get / describe	dtctl get workflows --mine · dtctl describe workflow <id>
apply / edit / delete	dtctl apply -f wf.yaml --set env=prod · dtctl delete workflow <id>
exec	dtctl exec function <id> --payload '{...}' · dtctl exec analyzer <id> --input '{...}'（也支持 workflow、copilot）
query / wait	dtctl query "fetch logs | limit 10" · dtctl wait query ... --for=any
inspect	dtctl inspect <file> --head 20 · --tail、--page --offset N --limit M、--fields a,b、--schema、--stats、--sample N、--list（对溢出结果文件进行行访问——无需重新查询 Grail）
logs / history / restore	dtctl logs workflow-execution <id> · dtctl history dashboard <id> · dtctl restore dashboard <id> 3（版本为位置参数；只有更新时传入 --create-snapshot 才会创建快照）
share / unshare	dtctl share dashboard <id> --user [email protected]
find / open	dtctl find intents --data trace.id=abc · dtctl open intent <app/intent> --data k=v
diff / verify	dtctl diff -f wf.yaml · dtctl verify query 'fetch logs' --fail-on-warn · dtctl verify analyzer <id> -f in.json

Davis 分析器：运行前，dtctl describe analyzer <id> 会显示必需/可选输入及结果架构（添加 --doc 查看完整文档，添加 -o json 查看原始架构）；dtctl verify analyzer <id> -f in.json 可在不执行的情况下验证输入（有效时退出码为 0 / 无效时为 1）。

面向 Agent 的输出

在 AI 环境中会自动检测 --agent/-A（隐含 --plain；可通过 --no-agent 退出）。输出会包装为 {ok, result, context}（错误为 {ok:false, error:{code,message}}，其中 context 包含 total、has_more、suggestions）。

-o toon          # token-efficient structured output — prefer for agents
-o json|yaml|csv # other machine formats
-o jsonl|parquet # streaming / columnar export for large results (pipe to a file, query with DuckDB)
-o chart|sparkline|barchart   # time series
-o table|wide    # human-readable (table is the default)
--jq '.[].id'    # filter structured output (json|yaml|toon; other formats auto-promote to json)

建议使用 --agent 搭配 -o toon 和 --jq 来减少 token。Agent 模式下的 query 默认会将元数据精简为成本/采样字段；使用 -M=all 可获取完整内容块。

查询结果：根据 result.kind 分支处理

Agent 模式下，dtctl query 默认使用 --spill=auto：大型结果会溢出到本地文件，并返回摘要，而不是将行数据全部写入上下文。不要假设 result 是数组——应根据 result.kind 分支处理：

result.kind	含义 → 操作
records	行内数据位于 result.records 下 → 直接使用
result-file	已溢出：清单包含 path、format、rows、bytes、列统计信息和 sample_rows → 使用 dtctl inspect <path> 检查文件（见下文），不要重新查询
summary-only	无法写入行数据——清单中不含 path → 使用统计信息/样本，或根据原因遵循 context.suggestions（使用 --spill=never 并指定上限，或使用 --spill-to <path>）

将未知的 kind 视为不透明内容，并回退使用 context（decided、total、warnings、suggestions）。采样结果会将统计信息放在 sample_stats 块中（basis: "sample"）——这并不代表总体情况。

dtctl query "fetch logs | limit 1000000" --agent     # auto-spills if large
dtctl query "fetch logs" --spill=never               # force every row inline
dtctl query "fetch logs" --spill-to ./out.jsonl      # explicit path: jsonl|json|csv|parquet
dtctl query "fetch logs" --spill=auto --spill-threshold 100KB

行内结果同样有大小限制。字符串值默认会截断至 500 个字符，并以 …(+N chars) 结尾（--max-field-chars 0 可返回完整值；添加 | fields <col> 可仅获取该列）。--max-output-tokens N / --max-output-bytes SIZE 只会返回适合限制的行。当 context.truncated 为 true 时，结果不完整：truncated_fields 会列出被截断的字段，而 returned < total 表示有行被丢弃。此时运行 context.next（一条 dtctl inspect 命令），即可从 next_offset 继续，而无需重新查询。

检查溢出的文件（无需重新查询 Grail）

dtctl inspect <file> 会读取摘要中省略的行——有界、流式传输，适合 Agent 上下文——因此无需重新运行 Grail 扫描。每次调用只能选择一种基本操作：

dtctl inspect <path> --head 20                          # first N rows (the manifest never carried rows)
dtctl inspect <path> --tail 10                          # last N rows
dtctl inspect <path> --page --offset 1000 --limit 50    # a window deep in the result (file order)
dtctl inspect <path> --head 20 --fields timestamp,content  # project columns (composable)
dtctl inspect <path> --schema                           # re-derive columns + types + null counts
dtctl inspect <path> --stats                            # re-derive the per-column profile (or --stats=col,col)
dtctl inspect --list                                    # lost the path? enumerate spilled files in this context

它不是查询引擎——不支持筛选、SQL 或 GROUP BY。对于聚合，请将工作交回 DQL（… | summarize …）；对于复杂的本地分析，请将文件交给你偏好的本地分析工具。过大的 inspect 窗口会将内容重新溢出到新文件，而不是淹没上下文；同时会拒绝来自其他上下文/租户的文件。

日志模式分析（节省令牌）

对于自由文本日志排查，不要倾倒原始 content——先在服务端提取分类体系，再深入分析：

1. dtctl exec analyzer dt.statistics.clustering.LogPatternExtractor --input '{"logQuery":"<DQL>","numberOfExamples":2}' → DPL 模板 + 匹配计数。logQuery 是纯 DQL 字符串（不是对象），结果需包含 timestamp 和 content。搭配 --jq 投影为 {patternExpression, numberOfMatches} 效果很好。
2. 将 patternExpression 原样放入 parse content, "..."（将捕获字段 f_1 重命名为有意义的名称），然后使用 summarize … by:{field} 按行提取/计数。未匹配的行会产生空值捕获。
3. 需要原始行？使用 fetch … --agent 深入查询，让结果溢出到文件（见上文），然后用 dtctl inspect <path> --head/--page 读取（见上文）。

应用与模板

dtctl apply 是幂等的：新建时使用 POST，文件包含 id 时使用 PUT。YAML/DQL 文件支持通过 --set 填充的 Go 模板：

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

dtctl apply -f file.yaml --set environment=prod --set schedule="0 6 * * *"

仪表板

创建/更新：dtctl apply -f dashboard.yaml。导出以供参考：dtctl get dashboard <id> -o yaml --plain。完整架构和 visualizationSettings：references/resources/dashboards.md。

name: "Dashboard Name"
type: dashboard
content:
  settings:
    defaultTimeframe: { enabled: true, value: { from: now()-2h, to: now() } }
  layouts:
    "1": { x: 0, "y": 0, w: 12, h: 6 }    # 24-col grid (full=24); quote "y" (YAML bool)
  tiles:
    "1":
      title: "Tile"
      type: data                          # data | markdown
      query: "fetch logs | limit 10"
      visualization: lineChart            # singleValue|lineChart|areaChart|barChart|pieChart|table|honeycomb|scatterplot
      davis: { enabled: false, davisVisualization: { isAvailable: true } }

注意事项：在数据图块上设置 davis.enabled: false；日志/跨度序列使用 makeTimeseries，指标使用 timeseries；存在 id → 更新，不存在 → 创建；创建时出现的 version 警告可以忽略。

权限与安全

• 修改前先验证：dtctl auth can-i <verb> <resource>。作用域：TOKEN_SCOPES.md。
• 安全级别可能会阻止破坏性操作——使用 dtctl config use-context <name> 切换，或在创建上下文时提高安全级别。
• 优先使用 get/describe；--mine 将范围限定为你拥有的资源；所有机器消费场景都使用 --plain。

凭据与清理

凭据由 dtctl 管理：只能通过 dtctl 读取和移除凭据。

dtctl config delete-context <name> --delete-credentials  # context + its credential
dtctl config delete-credentials <token-ref>              # credential alone (shared, or context already gone)
dtctl auth status --plain                                # presence check — never prints the token

切勿调用操作系统密钥链工具——security（macOS）、secret-tool （Linux）、cmdkey（Windows）——无论出于何种目的，包括清理。这些工具的删除 命令无法清除凭据占用的大部分内容；读取命令会打印机密， 而 security dump-keychain 会涵盖机器上的所有密钥链，不只是 dtctl 的密钥链。切勿通过读回密钥来验证是否已删除——打印令牌的清理步骤，恰恰泄露了它本应销毁的内容。

更多内容

故障排查 · 多租户配置 · DQL · 笔记本 · 扩展 · dtctl --help、dtctl <command> --help