查询诊断

查询诊断根据已有查询重新执行 EXPLAIN，将执行计划、规划信息、投影匹配日志及相关元数据打包，便于排查规划缓慢和投影未命中等问题。它不执行底层数据查询，也不能代替原查询运行时错误的完整复现。

前置条件与入口

进入“数据整合 → 查询记录”，打开需要诊断的查询详情，点击“收集并下载详细执行计划”。当前账号需能够访问原查询及相关资产。管理员应先完成本页的部署准备。

收集与下载

1. 核对原查询内容和任务 ID，点击收集按钮。
2. 等待收集完成，查看诊断状态，报告可用后下载 ZIP。
3. 暂时无法获取状态时，使用“继续查询诊断状态”查询原任务，避免反复新建。
4. 下载失败时重试下载已有报告；不需要因此重新执行 EXPLAIN。

同一用户对同一租户、集群及原查询的重复请求，会复用正在收集或已就绪的报告。不同用户不共享诊断任务。明确失败或过期后，新一次点击才可能创建后续任务；节点不可用或网络超时不会自动重新收集。

报告内容

内容	用途
原查询与本次 EXPLAIN 的任务信息	对照 SQL、配置、状态及规划阶段信息
explain.txt	查看重新生成的执行计划
规划及物化匹配日志	定位主要规划耗时和候选投影处理过程
表与候选投影元数据	核对原始对象、改写后访问的表和相关结构
manifest	检查未收集项、截断或其他报告限制

报告生成成功仅表示可以下载，不表示原查询或本次 EXPLAIN 成功。部分日志或元数据缺失时仍可能生成报告，应先检查缺失项。

部署准备

1. 已有 dwstardis 数据库执行版本附带的 start/src/main/resources/script/upgrade_query_diagnostics.sql，新建数据库的初始化脚本已包含相应表。
2. 为 Tardis 诊断目录提供写权限。报告保存在实际收集节点的本地磁盘，需保留足够空间。
3. 确认 dwstardis 可访问节点列表中的实际 HTTP 地址和端口。
4. 诊断日志收集跟随 etc/log.properties 的 log.output-dir；未设置时使用 ./var/log。如部署曾配置旧的 query.diagnostics.log-directory，升级时移除该项。

以下 Tardis 配置写入 etc/config.properties：

配置项	默认值	含义
query.diagnostics.directory	var/query-diagnostics	节点本地报告目录，相对路径按进程工作目录解析
query.diagnostics.timeout-seconds	300	单次 EXPLAIN 超时阈值，不是整份报告的总时长上限
query.diagnostics.retention-days	7	报告保留天数

注意事项与异常处理

• 报告反映收集时的当前元数据及重新规划结果，缓存、配置和元数据变化可能使其与原执行现场不同。
• 报告保存在指定节点，不使用共享存储。节点或本地目录不可用时，其他节点不能直接提供该报告。
• 当前最多同时执行两次诊断，等待队列最多 16 条；容量不足时应等待后重试。
• 超时会请求取消 EXPLAIN，未实际结束前可能继续显示运行中，不能把 300 秒当作报告必定完成时间。
• 诊断包会对凭据字段和显式凭据日志脱敏，但仍包含 SQL 及元数据；对外分享前核对业务信息的可分享范围。
• 原查询的执行错误可能仍需底层数据、数据源日志和外部服务信息才能定位。