当需要查询 Dynatrace…

通过 DQL 查询 Dynatrace smartscape 主机、进程、容器指标与清单，支持监控、故障排查、成本归因及异常检测/预测/季节性分析。

适用场景

解决思路

1. 使用 smartscapeNodes 查询实体：HOST、PROCESS、CONTAINER、NETWORK_INTERFACE、DISK。
2. 使用 timeseries 查询主机指标：dt.host.cpu.*、dt.host.memory.*、dt.host.disk.*、dt.host.net.*。
3. 使用 timeseries 查询进程指标：dt.process.cpu.*、dt.process.memory.*、dt.process.io.*、dt.process.network.*。
4. 使用清单字段：OS 类型、云厂商、技术栈、版本、成本（dt.cost.costcenter、dt.cost.product）、质量（元数据完整度、版本合规）。
5. 设置告警阈值：CPU/Memory/Disk 80% warning、90% critical；Network >70% high、>85% saturated；Disk Latency >20ms bottleneck；Network Errors drop rate >1%、error rate >0.1%；Swap >30% warning、>50% critical。
6. 主机发现与分类：执行 DQL `smartscapeNodes "HOST" | fieldsAdd os.type, cloud.provider, host.logical.cpu.cores, host.physical.memory | summarize host_count = count(), by: {os.type, cloud.provider} | sort host_count desc`；OS 类型包括 LINUX、WINDOWS、AIX、SOLARIS、ZOS。
7. 资源利用率监控：执行 DQL `timeseries { cpu = avg(dt.host.cpu.usage), memory = avg(dt.host.memory.usage), disk = avg(dt.host.disk.used.percent) }, by: {dt.smartscape.host} | fieldsAdd host_name = getNodeName(dt.smartscape.host) | filter arrayAvg(cpu) > 80 or arrayAvg(memory) > 80 | sort arrayAvg(cpu) desc`；高利用率阈值 80% warning、90% critical。
8. 关键 CPU 指标：dt.host.cpu.usage、dt.host.cpu.idle、dt.host.cpu.user、dt.host.cpu.system、dt.host.cpu.iowait（仅 Linux）。
9. 磁盘剩余空间：执行 DQL `timeseries disk_used_pct = avg(dt.host.disk.used.percent), by: {dt.smartscape.host} | fieldsAdd host_name = getNodeName(dt.smartscape.host) | fieldsAdd avg_disk_used = arrayAvg(disk_used_pct), free_pct = 100 - arrayAvg(disk_used_pct) | sort free_pct desc | limit 10`。
10. 进程资源分析：执行 DQL `timeseries { cpu = avg(dt.process.cpu.usage), memory = avg(dt.process.memory.usage) }, by: {dt.smartscape.process} | fieldsAdd process_name = getNodeName(dt.smartscape.process) | filter arrayAvg(cpu) > 50 | sort arrayAvg(cpu) desc | limit 20`。
11. 技术栈清单：执行 DQL `smartscapeNodes "PROCESS" | fieldsAdd process.software_technologies | expand tech = process.software_technologies | fieldsAdd tech_type = tech[type], tech_version = tech[version] | summarize process_count = count(), by: {tech_type, tech_version} | sort process_count desc`。
12. 通过端口发现服务：执行 DQL `smartscapeNodes "PROCESS" | fieldsAdd process.listen_ports, dt.process_group.detected_name | filter isNotNull(process.listen_ports) and arraySize(process.listen_ports) > 0 | expand listen_port = process.listen_ports | summarize process_count = count(), by: {listen_port, dt.process_group.detected_name} | sort toLong(listen_port) asc | limit 50`；常见端口 80 HTTP、443 HTTPS、22 SSH、3306 MySQL、5432 PostgreSQL。
13. 容器和 Kubernetes 监控：执行 DQL `smartscapeNodes "CONTAINER" | fieldsAdd k8s.cluster.name, k8s.namespace.name, k8s.workload.kind | summarize container_count = count(), by: {k8s.cluster.name, k8s.workload.kind} | sort k8s.cluster.name, container_count desc`；workload 类型 deployment、daemonset、statefulset、job、cronjob；注意容器镜像名/版本在 smartscape 中不可用。
14. 成本归因：执行 DQL `smartscapeNodes "HOST" | fieldsAdd dt.cost.costcenter, host.logical.cpu.cores, host.physical.memory | filter isNotNull(dt.cost.costcenter) | fieldsAdd memory_gb = toDouble(host.physical.memory) / 1024 / 1024 / 1024 | summarize host_count = count(), total_cores = sum(toLong(host.logical.cpu.cores)), total_memory_gb = sum(memory_gb), by: {dt.cost.costcenter} | sort total_cores desc`。
15. 基础设施健康关联：执行 DQL `timeseries { host_cpu = avg(dt.host.cpu.usage), host_memory = avg(dt.host.memory.usage), process_cpu = avg(dt.process.cpu.usage) }, by: {dt.smartscape.host, dt.smartscape.process} | fieldsAdd host_name = getNodeName(dt.smartscape.host), process_name = getNodeName(dt.smartscape.process) | filter arrayAvg(host_cpu) > 70 | sort arrayAvg(host_cpu) desc`；健康评分：任一资源 >90% critical，>80% warning。
16. OneAgent 清单：通过 `smartscapeNodes "HOST" | traverse edgeTypes: {monitors}, targetTypes: {ONEAGENT}, direction: backward` 访问 ONEAGENT；使用 dt.agent.monitoring_mode 字段（FULL_STACK/INFRASTRUCTURE/DISCOVERY），使用 dt.agent.module.version 字段。
17. 按监控模式统计主机：执行 DQL `smartscapeNodes "HOST" | traverse edgeTypes: {monitors}, targetTypes: {ONEAGENT}, direction: backward | fieldsAdd oa_mode = `dt.agent.monitoring_mode` | summarize host_count = count(), by: {oa_mode} | sort host_count desc`。
18. 按代理版本统计主机：执行 DQL `smartscapeNodes "HOST" | traverse edgeTypes: {monitors}, targetTypes: {ONEAGENT}, direction: backward | fieldsAdd oa_version = `dt.agent.module.version` | summarize host_count = count(), by: {oa_version} | sort host_count desc`。
19. 按模式+版本组合统计（用于升级规划）：执行 DQL `smartscapeNodes "HOST" | traverse edgeTypes: {monitors}, targetTypes: {ONEAGENT}, direction: backward | fieldsAdd oa_mode = `dt.agent.monitoring_mode`, oa_version = `dt.agent.module.version` | summarize host_count = count(), by: {oa_mode, oa_version} | sort host_count desc`。
20. 响应构建：数据检索时在响应中包含 DQL 查询和结果；分析时优先展示指标级发现，数据缺口仅作补充；包含主机名（getNodeName 或 get-entity-name）；说明分析的时间范围和工具/参数。
21. 异常检测工作流：构造 timeseries 查询，传给 adaptive-anomaly-detector 或 timeseries-novelty-detection；magnitude 问题（spikes、abrupt changes、values above normal、sudden jumps）用 adaptive-anomaly-detector；behavioral change 问题（unusual patterns、something changed、trends、new behavior）用 timeseries-novelty-detection。
22. 异常检测响应：包含主机名（getNodeName 或 get-entity-name）和实体 ID，以及时间戳和值。
23. 新颖性检测类型选择：默认只设 analysisNoveltyType 为 [SPIKE, CHANGE_IN_VALUES, TREND_IN_VALUES]；排除 GAP_WITH_MISSING_VALUES 和 CHANGE_IN_MISSING_VALUES，除非用户明确问数据缺口或监控覆盖。
24. 分析工具查询：使用简单 timeseries 格式，单个聚合指标，适当时间范围，例如 `timeseries avg(dt.host.cpu.idle), by: {dt.smartscape.host}` 或 `timeseries avg(dt.host.memory.usage), by: {dt.smartscape.host}`；避免添加会减少数据的过滤或字段转换。
25. 预测工作流：构造 timeseries 查询，历史数据至少 7d（短）或 30d（长），传给 forecasting 工具；预测 horizon 和历史窗口独立；无论 horizon 多短，至少用 7 天历史数据，否则模型可能失败回退到原始历史值。
26. 季节性检测：使用更长范围（周至少 14d，月 30d+），传给 seasonal baseline anomaly detector；响应包含是否检测到、时间范围和参数、受影响主机的名称、违规时间戳、违规次数、基线值 vs 实际值、上下界；按主机组织结果。
27. 范围边界：服务级指标（request rate、response time、error rate、service calls per minute、throughput）使用 dt-obs-services，即使涉及预测或异常检测。
28. 常见查询模式 Pattern 1：使用 `smartscapeNodes "HOST" | fieldsAdd <attributes> | filter <conditions> | summarize <aggregations>` 发现和分类实体。
29. Pattern 2：使用 `timeseries metric = avg(dt.host.<metric>), by: {dt.smartscape.host} | fieldsAdd <calculations> | filter <thresholds>` 分析时序性能。
30. Pattern 3：使用 `timeseries { host_cpu = avg(dt.host.cpu.usage), process_cpu = avg(dt.process.cpu.usage) }, by: {dt.smartscape.host, dt.smartscape.process}` 关联主机和进程指标。
31. Pattern 4：使用 `lookup` 丰富实体属性，lookup 后用 `lookup.` 前缀引用字段，例如 `timeseries cpu = avg(dt.host.cpu.usage), by: {dt.smartscape.host} | lookup [ smartscapeNodes HOST | fields id, cpuCores, memoryTotal ], sourceField:dt.smartscape.host, lookupField:id | fieldsAdd cores = lookup.cpuCores, mem_gb = lookup.memoryTotal / 1024 / 1024 / 1024`。
32. 标签和元数据：smartscape 查询中通用 `tags` 字段未填充；使用特定标签字段 `tags:azure[*]`、`tags:environment`；使用自定义元数据 `host.custom.metadata[*]`；可用 Azure 标签 `tags:azure[dt_owner_team]`、`tags:azure[dt_cloudcost_capability]`；自定义元数据 `host.custom.metadata[OperatorVersion]`、`host.custom.metadata[Cluster]`；成本 `dt.cost.costcenter`、`dt.cost.product`。
33. AWS 云特定属性：使用 `cloud.provider == "aws"`、`aws.region`、`aws.availability_zone`、`aws.account.id`、`aws.resource.id`、`aws.resource.name`、`aws.state`（running、stopped、terminated）。
34. Azure 云特定属性：使用 `cloud.provider == "azure"`、`azure.location`、`azure.subscription`、`azure.resource.group`、`azure.status`、`azure.provisioning_state`、`azure.resource.sku.name`（VM size）。
35. GCP 云特定属性：使用 `cloud.provider == "gcp"`、`gcp.region`、`gcp.zone`、`gcp.location`、`gcp.project.id`（注意两个点）、`gcp.resource.type`（如 `gce_instance`）、`gcp.asset.type`（如 `compute.googleapis.com/Instance`）。
36. Kubernetes 属性：使用 `k8s.cluster.name`、`k8s.cluster.uid`、`k8s.namespace.name`、`k8s.node.name`、`k8s.pod.name`、`k8s.workload.name`、`k8s.workload.kind`。
37. 最佳实践：延迟用百分位数 p95/p99；限制用 max()；趋势用 avg()；设置多级阈值（warning 80%、critical 90%）；在管道中尽早过滤；用 `| limit N` 限制结果；在 enrichment (lookup) 前先聚合；用 `getNodeName(dt.smartscape.host)` 获取主机名，用 `getNodeName(dt.smartscape.process)` 获取进程名；字节转 GB 用 `/ 1024 / 1024 / 1024`，用 `round(value, decimals: 1)` 取整。
38. 时间窗口：实时 5-15 分钟；趋势 1-7 天；容量规划 30-90 天。
39. 限制：`dt.host.cpu.iowait` 仅 Linux 可用；通用 `tags` 字段在 smartscape 中未填充；容器镜像名在 smartscape 中不可用。
40. 故障排除：`smartscapeNodes "HOST"` 无返回时，检查时间范围或 OneAgent 是否部署；验证 OneAgent 已安装；给查询添加时间范围。
41. 故障排除：`tags` 字段总是为空时，使用特定标签命名空间 `tags:azure[*]`、`tags:environment`、`dt.cost.costcenter`。
42. 故障排除：内存值字节不可读时，除以 `1024 / 1024 / 1024` 并用 `round(value, decimals: 1)`。
43. 故障排除：`dt.host.cpu.iowait` 无数据时，检查 `os.type`；iowait 在 Windows、AIX、Solaris 不可用。
44. 故障排除：容器镜像名缺失时，使用 `k8s.object` 解析镜像详情；参考 dt-obs-kubernetes 技能。
45. 故障排除：`process.software_technologies` 为空时，确认进程组是否启用 OneAgent deep monitoring。
46. 故障排除：`dt.agent.monitoring_mode` 总是 null 时，使用下划线字段 `dt.agent.monitoring_mode`；`dt.agent.monitoring.mode`（带点）总是返回 null。
47. 故障排除：`gcp.project.id` 总是 null 时，使用两个点的 `gcp.project.id`，不是下划线 `gcp.project_id`。
48. 加载参考文件：分析 CPU 组件（user、system、iowait、steal）、内存压力和 swap、磁盘 I/O 延迟、网络包丢失/错误时，加载 `host-metrics.md`。
49. 加载参考文件：分析进程级 I/O 模式、TCP 连接质量、资源耗尽（文件描述符、线程）、GC 暂停时间时，加载 `process-monitoring.md`。
50. 加载参考文件：分析容器生命周期和 churn、跟踪 Kubernetes 版本分布、管理 OneAgent operator 版本、规划 K8s 集群升级时，加载 `container-monitoring.md`。
51. 加载参考文件：通过端口发现进行安全审计、成本归因和 chargeback、验证数据质量和元数据完整度、管理多云基础设施、按 OneAgent 模式/版本列出或过滤主机时，加载 `inventory-discovery.md`。
52. 跨源 join：如果查询必须将主机数据与日志或其他遥测源结合，先读 `dt-dql-essentials/references/smartscape-topology-navigation.md` 再写查询。

适用边界 · 注意事项

• 不要用于解释已有查询或回答产品文档问题。
• 不要用于 Kubernetes pod/workload 查询，应使用 dt-obs-kubernetes；不要用于 AWS 云资源清单，应使用 dt-obs-aws。
• 不要用于服务级指标（请求率、响应时间、错误率、吞吐量），应使用 dt-obs-services。