需要排查 Dynatrace 事件、性能…

在 Dynatrace 环境中使用 dtctl 进行事件调查、DQL 查询、日志模式分析、资源管理、工作流与仪表盘维护。

适用场景

解决思路

1. 以 `dtctl <verb> <resource> [flags]` 模式操作 Dynatrace。
2. 初始化时运行 `dtctl commands` 获取紧凑总览（verbs、resources、subcommands，默认 TOON）；`dtctl commands --brief` 增加 mutating/access/scopes 和 flag 类型；`dtctl commands --full` 获取详尽目录：描述、flag 默认值、全局 flag。
3. 运行 `dtctl config current-context` 查看当前上下文。
4. 运行 `dtctl config describe-context $(dtctl config current-context) --plain` 查看环境 URL 和安全级别。
5. 运行 `dtctl auth status --plain` 查看 token 类型（OAuth vs API/platform）和安全级别。
6. 运行 `dtctl inventory` 查看当前环境存在的数据：可 fetch 对象、buckets、实体普查、capabilities。
7. 识别安全级别：`readonly`、`readwrite-mine`、`readwrite-all`、`dangerously-unrestricted`。
8. 用 `dtctl commands` 回答“能运行什么”；用 `dtctl inventory` 回答“有什么可查询”；在探索性 DQL 前先运行 `dtctl inventory`。
9. `dtctl inventory` 会把目录对象分区为 fetchable 与 query-only（绝不 `fetch metrics` 或 `fetch smartscape.*`），并把 capabilities 报告为 present、absent（附已检查证据，引用它而不是重新探测）或 unknown（无结论，不等于不存在）；组织特定 capability 定义用 `--definitions file.yaml`。
10. 不要用 `dtctl auth whoami` 测试连通性：它需要带 `app-engine:apps:run` 的 OAuth token，对普通 API 或 read-scoped token 即使读取正常也会返回伪 403；应通过真实 `get`/`query` 确认。
11. 在编写、修改或运行任何 DQL（`dtctl query`、`dtctl wait query`、query 文件）前，查阅 `references/DQL-reference.md`，并遵循它而不是假设或记忆。
12. 运行 DQL 示例：`dtctl query "fetch logs | filter status='ERROR' | limit 100" -o json --plain`。
13. 运行带 Go-template 变量的 DQL：`dtctl query -f query.dql --set host=h-123 --set timerange=2h -o json --plain`。
14. 等待查询结果：`dtctl wait query "fetch spans | filter test_id='test-123'" --for=count=1 --timeout 5m`。
15. 查询时间序列并输出图表：`dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain`。
16. 计费 `fetch`（logs、events、bizevents、spans）按扫描字节计费，dashboard tiles 每次刷新都会重新计费；发出 DQL 前阅读 `references/DQL-reference.md` 中的 “Scan Cost”，并把 PARTIAL 或 sampled 结果视为不完整。
17. dtctl 未安装或不可用时，查看 `references/troubleshooting.md`。
18. 通过初始化时运行的 `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。
19. 使用 ID，不用名称：名称可能歧义并失败。
20. 使用 get / describe：`dtctl get workflows --mine`、`dtctl describe workflow <id>`。
21. 使用 apply / edit / delete：`dtctl apply -f wf.yaml --set env=prod`、`dtctl delete workflow <id>`。
22. 使用 exec：`dtctl exec function <id> --payload '{...}'`、`dtctl exec analyzer <id> --input '{...}'`（也适用于 workflow、copilot）。
23. 使用 query / wait：`dtctl query "fetch logs | limit 10"`、`dtctl wait query ... --for=any`。
24. 使用 inspect：`dtctl inspect <file> --head 20`，以及 `--tail`、`--page --offset N --limit M`、`--fields a,b`、`--schema`、`--stats`、`--sample N`、`--list`（对已 spill 的结果文件做行级访问，不重新查询 Grail）。
25. 使用 logs / history / restore：`dtctl logs workflow-execution <id>`、`dtctl history dashboard <id>`、`dtctl restore dashboard <id> 3`（version 是位置参数；仅当更新时传了 `--create-snapshot` 才存在快照）。
26. 使用 share / unshare：`dtctl share dashboard <id> --user a@example.com`。
27. 使用 find / open：`dtctl find intents --data trace.id=abc`、`dtctl open intent <app/intent> --data k=v`。
28. 使用 diff / verify：`dtctl diff -f wf.yaml`、`dtctl verify query 'fetch logs' --fail-on-warn`、`dtctl verify analyzer <id> -f in.json`。
29. 运行 Davis analyzer 前，用 `dtctl describe analyzer <id>` 查看必需/可选输入和结果 schema（加 `--doc` 看完整文档，`-o json` 看原始 schema）；用 `dtctl verify analyzer <id> -f in.json` 在不执行的情况下验证输入（exit 0 有效 / 1 无效）。
30. Agent 输出：`--agent`/`-A` 在 AI 环境中自动检测（隐含 `--plain`；用 `--no-agent` 退出）；它把输出包装为 `{ok, result, context}`（错误为 `{ok:false, error:{code,message}}`），其中 `context` 携带 `total`、`has_more`、`suggestions`。
31. 输出格式：`-o toon` 是 token 高效的结构化输出，agent 优先用；`-o json|yaml|csv` 其他机器格式；`-o jsonl|parquet` 用于大结果的流式/列式导出（管道到文件，用 DuckDB 查询）；`-o chart|sparkline|barchart` 用于时间序列；`-o table|wide` 人类可读（table 默认）；`--jq '.[].id'` 过滤结构化输出（json|yaml|toon；其他格式自动提升为 json）。
32. 优先使用 `--agent` 加 `-o toon` 和 `--jq` 来减少 token。
33. 在 agent 模式，`dtctl query` 默认 `--spill=auto`：大结果 spill 到本地文件并返回摘要，而不是把行倾倒进上下文；不要假设 `result` 是数组，按 `result.kind` 分支。
34. `result.kind` 为 `records`：行内联在 `result.records` 下，直接使用。
35. `result.kind` 为 `result-file`：已 spill，manifest 含 `path`、`format`、`rows`、`bytes`、列统计、`sample_rows`；用 `dtctl inspect <path>` 查询该文件，不要重新查询。
36. `result.kind` 为 `summary-only`：行无法写出，manifest 无 `path`；使用 stats/sample，或遵循带原因感知的 `context.suggestions`（`--spill=never` 加边界，或 `--spill-to <path>`）。
37. 把未知 `kind` 当作不透明，回退到 `context`（`decided`、`total`、`warnings`、`suggestions`）；sampled 结果把统计放在 `sample_stats` 块中（`basis: "sample"`），不是总体真相。
38. 控制 spill：`dtctl query "fetch logs | limit 1000000" --agent` 大时自动 spill；`dtctl query "fetch logs" --spill=never` 强制所有行内联；`dtctl query "fetch logs" --spill-to ./out.jsonl` 指定路径（jsonl|json|csv|parquet）；`dtctl query "fetch logs" --spill=auto --spill-threshold 100KB` 设置阈值。
39. 检查 spilled 文件且不重新查询 Grail：`dtctl inspect <file>` 读取摘要省略的行，有界、流式、适合 agent 上下文；每次调用只选一个 primitive。
40. 使用 inspect primitives：`dtctl inspect <path> --head 20` 前 N 行；`dtctl inspect <path> --tail 10` 后 N 行；`dtctl inspect <path> --page --offset 1000 --limit 50` 结果深处的窗口（文件顺序）；`dtctl inspect <path> --head 20 --fields timestamp,content` 投影列（可组合）；`dtctl inspect <path> --schema` 重新推导列、类型、null 计数；`dtctl inspect <path> --stats` 重新推导每列 profile（或 `--stats=col,col`）；`dtctl inspect --list` 丢失 path 时枚举当前上下文中的 spilled 文件。
41. `dtctl inspect` 不是查询引擎，不支持 filter/SQL/GROUP BY；聚合要把工作推回 DQL（`… | summarize …`）；复杂本地分析把文件交给偏好的本地分析工具；过大的 inspect 窗口会重新 spill 到新文件而不是淹没上下文，并拒绝来自其他 context/tenant 的文件。
42. 日志模式分析要 token frugal：不要倾倒原始 `content`，先服务端提取分类再下钻。
43. 第一步：`dtctl exec analyzer dt.statistics.clustering.LogPatternExtractor --input '{"logQuery":"<DQL>","numberOfExamples":2}'`，得到 DPL 模板和匹配计数；`logQuery` 是普通 DQL 字符串（不是对象），产出 `timestamp`+`content`；用 `--jq` 投影到 `{patternExpression, numberOfMatches}` 很合适。
44. 第二步：把 `patternExpression` 原样放进 `parse content, "..."`（重命名 captures `f_1` 为有意义名称），然后 `summarize … by:{field}` 在行规模上提取/计数；未匹配行产生 null captures。
45. 第三步：需要原始行时，用 `fetch … --agent` 下钻并让它 spill，然后用 `dtctl inspect <path> --head/--page` 读取。
46. `dtctl apply` 是幂等的：文件没有 `id` 时 POST，有 `id` 时 PUT；YAML/DQL 文件支持 Go templates，用 `--set` 填充。
47. Go-template 示例：`title: "{{.environment}} Deployment"`、`cron: "{{.schedule | default "0 0 * * *"}}"`；执行 `dtctl apply -f file.yaml --set environment=prod --set schedule="0 6 * * *"`。
48. 仪表盘创建/更新：`dtctl apply -f dashboard.yaml`；导出参考：`dtctl get dashboard <id> -o yaml --plain`；完整 schema 与 visualizationSettings 看 `references/resources/dashboards.md`。
49. 仪表盘 YAML 结构：`name`、`type: dashboard`、`content.settings.defaultTimeframe`（如 `{ enabled: true, value: { from: now()-2h, to: now() } }`）、`layouts` 用 24 列网格（full=24，`"1": { x: 0, "y": 0, w: 12, h: 6 }`，`"y"` 要加引号避免 YAML bool）、`tiles` 含 `title`、`type: data|markdown`、`query`、`visualization: lineChart`（单值/折线/面积/柱状/饼图/表格/honeycomb/散点）、`davis: { enabled: false, davisVisualization: { isAvailable: true } }`。
50. 仪表盘注意事项：data tiles 设置 `davis.enabled: false`；log/span series 用 `makeTimeseries`，metrics 用 `timeseries`；有 `id` 则更新，无 `id` 则创建；创建时的 `version` 警告无害。
51. 权限与安全：变更前验证 `dtctl auth can-i <verb> <resource>`；scope 看 `TOKEN_SCOPES.md`。
52. 破坏性操作可能被安全级别阻止；用 `dtctl config use-context <name>` 切换，或在创建 context 时提高级别。
53. 优先 `get`/`describe`；`--mine` 限定到自己拥有的资源；所有机器消费都用 `--plain`。
54. 凭据与清理：凭据由 dtctl 管理，只通过 dtctl 读取和删除。
55. 删除上下文及其凭据：`dtctl config delete-context <name> --delete-credentials`；单独删除凭据：`dtctl config delete-credentials <token-ref>`；存在性检查：`dtctl auth status --plain`（绝不打印 token）。
56. 绝不为了任何目的（包括清理）调用 OS keychain 工具：`security`（macOS）、`secret-tool`（Linux）、`cmdkey`（Windows）；它们的 delete verbs 会漏掉大部分凭据占用，read verbs 会打印 secret，`security dump-keychain` 覆盖机器上所有 keychain，而不只是 dtctl 的。
57. 绝不通过读回 secret 来验证删除；一个会打印 token 的清理步骤已经泄露了它被告知要销毁的东西。
58. 更多参考：`references/troubleshooting.md`、`references/config-management.md`、`references/DQL-reference.md`、`references/resources/notebooks.md`、`references/resources/extensions.md`、`dtctl --help`、`dtctl <command> --help`。

适用边界 · 注意事项

• 未安装 dtctl、没有可访问的 Dynatrace 环境或凭据时，先按 `references/troubleshooting.md` 排查，不要假装可操作。
• 不使用 Dynatrace 或需要操作其他可观测性/云平台时，不应套用 dtctl 工作流。
• 不要用 OS keychain 工具（security/secret-tool/cmdkey）或读回密钥来清理/验证凭据。