@fx-data/ai-diagnostics 0.1.20261027064707 → 0.1.20261109015953

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (254) hide show
  1. package/AGENT_SETUP.md +3 -3
  2. package/README.md +1 -1
  3. package/bin/core-ai.mjs +18 -18
  4. package/content/AGENTS.md +37 -59
  5. package/content/README.md +10 -43
  6. package/content/docs/architecture.md +45 -74
  7. package/content/docs/diagnostic-feedback.md +20 -38
  8. package/content/docs/diagnostic-report.md +19 -46
  9. package/content/docs/index.md +41 -129
  10. package/content/docs/scenario-guide.md +34 -52
  11. package/content/knowledge/README.md +49 -0
  12. package/content/knowledge/cases/README.md +60 -0
  13. package/content/knowledge/cases/dashboard-parameter-deep-binding.md +32 -0
  14. package/content/knowledge/common/README.md +31 -0
  15. package/content/knowledge/common/concepts.md +49 -0
  16. package/content/knowledge/common/{knowledge-applicability.md → conclusions.md} +10 -6
  17. package/content/knowledge/common/queries.md +98 -0
  18. package/content/knowledge/common/signals.md +58 -0
  19. package/content/knowledge/common/topics/baseline-comparison.md +23 -0
  20. package/content/knowledge/common/topics/large-results.md +12 -0
  21. package/content/knowledge/common/topics/linked-traces.md +11 -0
  22. package/content/knowledge/common/topics/query-budget.md +18 -0
  23. package/content/knowledge/common/topics/query-example.md +69 -0
  24. package/content/knowledge/common/topics/setup-signoz-mcp.md +102 -0
  25. package/content/knowledge/common/topics/start-and-anchors.md +19 -0
  26. package/content/knowledge/common/workflow.md +22 -0
  27. package/content/knowledge/component/README.md +26 -0
  28. package/content/knowledge/component/concepts.md +22 -0
  29. package/content/knowledge/component/conclusions.md +11 -0
  30. package/content/knowledge/component/queries.md +7 -0
  31. package/content/knowledge/component/signals.md +75 -0
  32. package/content/knowledge/component/workflow.md +23 -0
  33. package/content/knowledge/dashboard/README.md +31 -0
  34. package/content/knowledge/dashboard/concepts.md +26 -0
  35. package/content/knowledge/dashboard/conclusions.md +21 -0
  36. package/content/knowledge/dashboard/queries.md +69 -0
  37. package/content/knowledge/dashboard/signals.md +76 -0
  38. package/content/knowledge/dashboard/topics/component-comparison.md +9 -0
  39. package/content/knowledge/dashboard/topics/dynamic-fields.md +21 -0
  40. package/content/knowledge/dashboard/topics/filter-tree.md +35 -0
  41. package/content/knowledge/dashboard/topics/name-binding.md +9 -0
  42. package/content/knowledge/dashboard/workflow.md +45 -0
  43. package/content/knowledge/dataset/README.md +27 -0
  44. package/content/knowledge/dataset/concepts.md +30 -0
  45. package/content/knowledge/dataset/conclusions.md +11 -0
  46. package/content/knowledge/dataset/queries.md +7 -0
  47. package/content/knowledge/dataset/signals.md +61 -0
  48. package/content/knowledge/dataset/topics/steps.md +59 -0
  49. package/content/knowledge/dataset/workflow.md +27 -0
  50. package/content/knowledge/engine/README.md +27 -0
  51. package/content/knowledge/engine/concepts.md +80 -0
  52. package/content/knowledge/engine/conclusions.md +49 -0
  53. package/content/knowledge/engine/queries.md +119 -0
  54. package/content/knowledge/engine/signals.md +73 -0
  55. package/content/knowledge/engine/topics/metric-fields.md +104 -0
  56. package/content/knowledge/engine/topics/patterns.md +50 -0
  57. package/content/knowledge/engine/workflow.md +20 -0
  58. package/content/knowledge/signal-index.md +117 -0
  59. package/content/knowledge/update/README.md +39 -0
  60. package/content/knowledge/update/concepts.md +93 -0
  61. package/content/knowledge/update/conclusions.md +59 -0
  62. package/content/knowledge/update/queries.md +103 -0
  63. package/content/knowledge/update/signals.md +57 -0
  64. package/content/knowledge/update/topics/correlations.md +63 -0
  65. package/content/knowledge/update/topics/discover-executions.md +31 -0
  66. package/content/knowledge/update/topics/events-execution.md +136 -0
  67. package/content/knowledge/update/topics/events-intake.md +102 -0
  68. package/content/knowledge/update/topics/events-outcome.md +163 -0
  69. package/content/knowledge/update/topics/lifecycle.md +58 -0
  70. package/content/knowledge/update/topics/scene-producers.md +258 -0
  71. package/content/knowledge/update/workflow.md +29 -0
  72. package/content-manifest.json +73 -192
  73. package/package.json +2 -2
  74. package/content/.agents/skills/analyze-analysis-table-update-runtime/SKILL.md +0 -35
  75. package/content/.agents/skills/analyze-analysis-table-update-runtime/agents/openai.yaml +0 -7
  76. package/content/.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md +0 -34
  77. package/content/.agents/skills/analyze-analysis-table-update-runtime/references/update-diagnostic-contract.md +0 -101
  78. package/content/.agents/skills/analyze-engine-metric/SKILL.md +0 -76
  79. package/content/.agents/skills/analyze-engine-metric/agents/openai.yaml +0 -13
  80. package/content/.agents/skills/analyze-engine-metric/scripts/analyze_engine_metric.py +0 -270
  81. package/content/.agents/skills/analyze-engine-metric/scripts/engine_metric_analysis/__init__.py +0 -11
  82. package/content/.agents/skills/analyze-engine-metric/scripts/engine_metric_analysis/metric_analyzer.py +0 -791
  83. package/content/.agents/skills/analyze-engine-metric/scripts/engine_metric_analysis/signoz_extract.py +0 -278
  84. package/content/.agents/skills/diagnose-component-performance/SKILL.md +0 -52
  85. package/content/.agents/skills/diagnose-component-performance/agents/openai.yaml +0 -7
  86. package/content/.agents/skills/diagnose-component-performance/references/experience.md +0 -34
  87. package/content/.agents/skills/diagnose-dashboard-performance/SKILL.md +0 -92
  88. package/content/.agents/skills/diagnose-dashboard-performance/agents/openai.yaml +0 -7
  89. package/content/.agents/skills/diagnose-dashboard-performance/references/experience.md +0 -63
  90. package/content/.agents/skills/diagnose-dataset-performance/SKILL.md +0 -52
  91. package/content/.agents/skills/diagnose-dataset-performance/agents/openai.yaml +0 -7
  92. package/content/.agents/skills/diagnose-dataset-performance/references/experience.md +0 -33
  93. package/content/.agents/skills/diagnose-performance/SKILL.md +0 -77
  94. package/content/.agents/skills/diagnose-performance/agents/openai.yaml +0 -7
  95. package/content/.agents/skills/diagnose-update-performance/SKILL.md +0 -55
  96. package/content/.agents/skills/diagnose-update-performance/agents/openai.yaml +0 -7
  97. package/content/.agents/skills/diagnose-update-performance/references/experience.md +0 -47
  98. package/content/.agents/skills/setup-signoz-mcp/SKILL.md +0 -30
  99. package/content/.agents/skills/setup-signoz-mcp/agents/openai.yaml +0 -7
  100. package/content/.agents/skills/setup-signoz-mcp/references/installation.md +0 -75
  101. package/content/.agents/skills/setup-signoz-mcp/references/windows-artifact.md +0 -14
  102. package/content/docs/npm-cli.md +0 -200
  103. package/content/docs/roadmap.md +0 -44
  104. package/content/docs/skill-writing-guide.md +0 -65
  105. package/content/knowledge/common/signoz-environments.json +0 -52
  106. package/content/knowledge/common/signoz-environments.md +0 -55
  107. package/content/knowledge/common/signoz-query-example.md +0 -41
  108. package/content/knowledge/common/signoz-query-policy.md +0 -145
  109. package/content/knowledge/common/trace-routing.md +0 -63
  110. package/content/knowledge/component/observability.md +0 -60
  111. package/content/knowledge/dashboard/observability.md +0 -168
  112. package/content/knowledge/dashboard/query-examples.md +0 -63
  113. package/content/knowledge/dataset/observability.md +0 -68
  114. package/content/knowledge/engine/metric-artifacts.md +0 -25
  115. package/content/knowledge/engine/metric-retrieval.md +0 -107
  116. package/content/knowledge/engine/metric-semantics.md +0 -172
  117. package/content/knowledge/engine/performance-patterns.md +0 -86
  118. package/content/knowledge/update/diagnostic/manifest.json +0 -209
  119. package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-capacity-deferral.json +0 -17
  120. package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-lock-requeue.json +0 -18
  121. package/content/knowledge/update/diagnostic/observability/edges/edge-attempt-to-merge.json +0 -17
  122. package/content/knowledge/update/diagnostic/observability/edges/edge-candidate-to-effective-root.json +0 -16
  123. package/content/knowledge/update/diagnostic/observability/edges/edge-capacity-deferral-to-attempt.json +0 -16
  124. package/content/knowledge/update/diagnostic/observability/edges/edge-chain-node-to-execution-detail.json +0 -18
  125. package/content/knowledge/update/diagnostic/observability/edges/edge-dlx-recovery-to-attempt.json +0 -16
  126. package/content/knowledge/update/diagnostic/observability/edges/edge-effective-execution-to-listener-before.json +0 -21
  127. package/content/knowledge/update/diagnostic/observability/edges/edge-effective-root-to-chain.json +0 -17
  128. package/content/knowledge/update/diagnostic/observability/edges/edge-engine-task-to-primary-result.json +0 -17
  129. package/content/knowledge/update/diagnostic/observability/edges/edge-execution-detail-to-publication.json +0 -16
  130. package/content/knowledge/update/diagnostic/observability/edges/edge-init-recovery-to-publication.json +0 -16
  131. package/content/knowledge/update/diagnostic/observability/edges/edge-listener-complete-to-child-release.json +0 -21
  132. package/content/knowledge/update/diagnostic/observability/edges/edge-listener-to-derived-chain.json +0 -21
  133. package/content/knowledge/update/diagnostic/observability/edges/edge-load-decision-to-load-operation.json +0 -16
  134. package/content/knowledge/update/diagnostic/observability/edges/edge-load-operation-to-engine-task.json +0 -17
  135. package/content/knowledge/update/diagnostic/observability/edges/edge-lock-requeue-to-attempt.json +0 -16
  136. package/content/knowledge/update/diagnostic/observability/edges/edge-logical-parent-to-child.json +0 -18
  137. package/content/knowledge/update/diagnostic/observability/edges/edge-merge-member-to-effective-execution.json +0 -18
  138. package/content/knowledge/update/diagnostic/observability/edges/edge-merge-to-load-decision.json +0 -17
  139. package/content/knowledge/update/diagnostic/observability/edges/edge-no-load-to-primary-result.json +0 -16
  140. package/content/knowledge/update/diagnostic/observability/edges/edge-primary-result-to-child-frontier.json +0 -18
  141. package/content/knowledge/update/diagnostic/observability/edges/edge-primary-result-to-listener.json +0 -23
  142. package/content/knowledge/update/diagnostic/observability/edges/edge-publication-to-attempt.json +0 -16
  143. package/content/knowledge/update/diagnostic/observability/edges/edge-ready-recovery-to-publication.json +0 -16
  144. package/content/knowledge/update/diagnostic/observability/edges/edge-request-to-candidate-root.json +0 -16
  145. package/content/knowledge/update/diagnostic/observability/identity-units/candidate-root.json +0 -13
  146. package/content/knowledge/update/diagnostic/observability/identity-units/dag-node.json +0 -14
  147. package/content/knowledge/update/diagnostic/observability/identity-units/effective-root.json +0 -14
  148. package/content/knowledge/update/diagnostic/observability/identity-units/engine-task.json +0 -13
  149. package/content/knowledge/update/diagnostic/observability/identity-units/execution-attempt.json +0 -12
  150. package/content/knowledge/update/diagnostic/observability/identity-units/execution-detail.json +0 -13
  151. package/content/knowledge/update/diagnostic/observability/identity-units/listener-invocation.json +0 -11
  152. package/content/knowledge/update/diagnostic/observability/identity-units/load-decision.json +0 -12
  153. package/content/knowledge/update/diagnostic/observability/identity-units/load-operation.json +0 -11
  154. package/content/knowledge/update/diagnostic/observability/identity-units/logical-dag-edge.json +0 -11
  155. package/content/knowledge/update/diagnostic/observability/identity-units/merge-decision.json +0 -12
  156. package/content/knowledge/update/diagnostic/observability/identity-units/node-primary-result.json +0 -12
  157. package/content/knowledge/update/diagnostic/observability/identity-units/queue-publication.json +0 -11
  158. package/content/knowledge/update/diagnostic/observability/identity-units/requeue.json +0 -11
  159. package/content/knowledge/update/diagnostic/observability/identity-units/update-chain.json +0 -13
  160. package/content/knowledge/update/diagnostic/observability/identity-units/update-request.json +0 -12
  161. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-after-commit-delivery.json +0 -131
  162. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-attempt-consumed.json +0 -175
  163. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-candidate-root-filter.json +0 -119
  164. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-capacity-deferred.json +0 -121
  165. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-child-release.json +0 -146
  166. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-dlx-recovery.json +0 -100
  167. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-effective-root-selection.json +0 -111
  168. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-engine-handoff.json +0 -171
  169. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-execution-frontier-persisted.json +0 -115
  170. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-init-recovery.json +0 -93
  171. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-intent-accepted.json +0 -151
  172. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-listener-derived-chain.json +0 -112
  173. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-listener-invocation.json +0 -154
  174. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-load-decision.json +0 -155
  175. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-load-operation.json +0 -108
  176. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-lock-requeued.json +0 -108
  177. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-logical-dependency-expansion.json +0 -129
  178. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-merge-decision.json +0 -174
  179. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-primary-node-result.json +0 -318
  180. package/content/knowledge/update/diagnostic/observability/lookups/analysis-update-ready-recovery.json +0 -92
  181. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-business-attempt.json +0 -33
  182. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-capacity-cycle.json +0 -31
  183. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-child-release.json +0 -32
  184. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-commit-publication.json +0 -29
  185. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-control-planning.json +0 -30
  186. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-engine-task.json +0 -27
  187. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-listener-callback.json +0 -27
  188. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-load-operation.json +0 -27
  189. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-lock-cycle.json +0 -31
  190. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-main-queue-wait.json +0 -32
  191. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-merge-evaluation.json +0 -29
  192. package/content/knowledge/update/diagnostic/observability/performance-segments/analysis-update-segment-parent-dependency-wait.json +0 -31
  193. package/content/knowledge/update/diagnostic/observability-index.json +0 -558
  194. package/content/knowledge/update/diagnostic/recipe-index.json +0 -85
  195. package/content/knowledge/update/diagnostic/recipes/dag-chain.json +0 -676
  196. package/content/knowledge/update/diagnostic/recipes/performance-window.json +0 -1128
  197. package/content/knowledge/update/diagnostic/recipes/scene-origin-async-message-or-callback.json +0 -438
  198. package/content/knowledge/update/diagnostic/recipes/scene-origin-derived-update-chain.json +0 -510
  199. package/content/knowledge/update/diagnostic/recipes/scene-origin-direct-service-call.json +0 -438
  200. package/content/knowledge/update/diagnostic/recipes/scene-origin-http.json +0 -438
  201. package/content/knowledge/update/diagnostic/recipes/scene-origin-internal-event.json +0 -438
  202. package/content/knowledge/update/diagnostic/recipes/scene-origin-job.json +0 -438
  203. package/content/knowledge/update/diagnostic/recipes/scene-origin-recovery-or-migration.json +0 -438
  204. package/content/knowledge/update/diagnostic/recipes/table-history.json +0 -508
  205. package/content/knowledge/update/diagnostic/recipes/table-in-chain.json +0 -595
  206. package/content/knowledge/update/diagnostic/scene-index.json +0 -252
  207. package/content/knowledge/update/diagnostic/scenes/active.json +0 -47
  208. package/content/knowledge/update/diagnostic/scenes/add.json +0 -140
  209. package/content/knowledge/update/diagnostic/scenes/agent.json +0 -20
  210. package/content/knowledge/update/diagnostic/scenes/archive.json +0 -32
  211. package/content/knowledge/update/diagnostic/scenes/auth-change.json +0 -116
  212. package/content/knowledge/update/diagnostic/scenes/call-back.json +0 -32
  213. package/content/knowledge/update/diagnostic/scenes/case-install.json +0 -20
  214. package/content/knowledge/update/diagnostic/scenes/case-replace.json +0 -7
  215. package/content/knowledge/update/diagnostic/scenes/cdc-schedule.json +0 -20
  216. package/content/knowledge/update/diagnostic/scenes/compute-model.json +0 -20
  217. package/content/knowledge/update/diagnostic/scenes/copy-data.json +0 -32
  218. package/content/knowledge/update/diagnostic/scenes/corp-linked.json +0 -7
  219. package/content/knowledge/update/diagnostic/scenes/corp-member-add.json +0 -20
  220. package/content/knowledge/update/diagnostic/scenes/corp-member-del.json +0 -7
  221. package/content/knowledge/update/diagnostic/scenes/corp-member-modify.json +0 -32
  222. package/content/knowledge/update/diagnostic/scenes/corp-member-sync.json +0 -152
  223. package/content/knowledge/update/diagnostic/scenes/corp-setting-member-rename.json +0 -152
  224. package/content/knowledge/update/diagnostic/scenes/corp-setting.json +0 -20
  225. package/content/knowledge/update/diagnostic/scenes/cross-project-allow.json +0 -32
  226. package/content/knowledge/update/diagnostic/scenes/default.json +0 -32
  227. package/content/knowledge/update/diagnostic/scenes/del.json +0 -20
  228. package/content/knowledge/update/diagnostic/scenes/dynamic-time.json +0 -20
  229. package/content/knowledge/update/diagnostic/scenes/edit.json +0 -92
  230. package/content/knowledge/update/diagnostic/scenes/excel-append.json +0 -44
  231. package/content/knowledge/update/diagnostic/scenes/excel-save.json +0 -32
  232. package/content/knowledge/update/diagnostic/scenes/folder-copy.json +0 -32
  233. package/content/knowledge/update/diagnostic/scenes/global.json +0 -56
  234. package/content/knowledge/update/diagnostic/scenes/handover.json +0 -32
  235. package/content/knowledge/update/diagnostic/scenes/history-handle.json +0 -20
  236. package/content/knowledge/update/diagnostic/scenes/manual-update.json +0 -44
  237. package/content/knowledge/update/diagnostic/scenes/migration.json +0 -20
  238. package/content/knowledge/update/diagnostic/scenes/param-change.json +0 -20
  239. package/content/knowledge/update/diagnostic/scenes/polars-error.json +0 -32
  240. package/content/knowledge/update/diagnostic/scenes/preview-exception.json +0 -20
  241. package/content/knowledge/update/diagnostic/scenes/preview-invalid.json +0 -20
  242. package/content/knowledge/update/diagnostic/scenes/project-excel-move.json +0 -20
  243. package/content/knowledge/update/diagnostic/scenes/re-check.json +0 -7
  244. package/content/knowledge/update/diagnostic/scenes/replace.json +0 -20
  245. package/content/knowledge/update/diagnostic/scenes/rollback.json +0 -68
  246. package/content/knowledge/update/diagnostic/scenes/save-as.json +0 -44
  247. package/content/knowledge/update/diagnostic/scenes/schedu.json +0 -56
  248. package/content/knowledge/update/diagnostic/scenes/table-move-other-workspace.json +0 -20
  249. package/content/knowledge/update/diagnostic/scenes/user-holder-to-normal.json +0 -20
  250. package/content/knowledge/update/observability.md +0 -16
  251. package/content/knowledge/update/runtime-evidence.md +0 -32
  252. package/content/scripts/receive_tool_result.py +0 -57
  253. /package/content/{.agents/skills/setup-signoz-mcp/scripts → scripts}/install_signoz_mcp.ps1 +0 -0
  254. /package/content/{.agents/skills/setup-signoz-mcp/scripts → scripts}/install_signoz_mcp.py +0 -0
@@ -0,0 +1,35 @@
1
+ # 筛选树还原与交付
2
+
3
+ 组件计算存在多层、多分支过滤树,或判断依赖筛选器所在层级时,必须按本节校验并输出完整树结构。小而完整的树可直接解释;节点数、最大深度或筛选器数量不能代替树结构。
4
+
5
+ 筛选结构可记录 `filter_conditions.root_table_id`、`node_count`、`path_node_count`、`max_depth`、`table_ids`、`table_paths`、`tree_summary` 及各类过滤数量。筛选器候选值链路还可出现 `data.control.calculateOptions`、`data.control.engineExecute`,不能只按历史 `controlData` 查找。默认 trace 详情缺自定义属性时,使用同执行的定向查询补齐。
6
+
7
+ `node_count` 表示去重后的条件对象数量,`path_node_count` 表示沿不同路径访问对象的次数。共享对象可在多条路径上重复出现,对应 summary 保留五类过滤计数并标记 `shared=true`;同一个 tableId 不足以证明同一个条件对象,不能按表 ID 去重。展示时保留完整路径,在重复访问处标注共享,避免把多条路径当成多份独立业务对象。
8
+
9
+ `cycle_paths` / `cycle_path_count` 表示记录中的环路边界,summary 形式为 `{cycle=true}`。该末端不含五类筛选数量,也不计入 `path_node_count`,展示到环路末端即停止,不推导后续关系或断言计算一定死循环。完整性需要同时核对路径访问数、条件对象数、共享与环标记;旧记录缺少新增字段时,只有完整、可解析的路径及 summary 能支持相同核对时才继续确认。
10
+
11
+ `table_paths` 或 `tree_summary` 出现 `...(N)`、计数冲突或摘要缺失时,只恢复可见部分并保留缺口。不能把 `table_ids` 中的孤立 ID 拼回结构,也不能用 `max_depth` 猜测层级。字段缺失不能当成数值为零。
12
+
13
+ ## 选定结构与完整性
14
+
15
+ 先按当前组件、操作和请求父子范围选定树,再核对条件对象数、路径访问数及每条路径的 summary。绑定必须属于同请求父子范围,不能把同 trace 的另一组件条件挂到当前树。
16
+
17
+ 共享路径保留 `shared=true`,环路末端保留 `{cycle=true}`,`tree_summary` 必须覆盖每条已显示路径。出现 `...(N)`、计数冲突、缺失 summary 或其他完整性校验失败时,只输出可证明的局部树,说明能确认的缺失数量和缺失摘要的产物位置,并标为不完整。不得将截断后的孤立节点猜接回树,也不得声称已标注全部筛选器位置。
18
+
19
+ 助手从 `table_paths` 和 `tree_summary` 还原树,并依次核对:
20
+
21
+ 1. 逐条解析路径(如 `root->a->b`),按路径前缀建树。同一对象出现在多条路径中时,条件对象只计一次,路径访问按出现次数计。
22
+ 2. 每条可见路径都要在 `tree_summary` 中找到对应 summary;带 `shared=true` 的是共享对象的重复访问,带 `{cycle=true}` 的是环路末端,环末端不计入路径访问数。
23
+ 3. 用 `node_count` 核对条件对象数、`path_node_count` 核对路径访问数。
24
+ 4. 全部可见路径都有 summary、没有 `...(N)` 截断,且路径身份与环路标记均能核对时,缺失节点数按“声明的对象数减去已核对对象数”计算;其他情况写“缺失数量未知”。不能用声明的对象数减去可见路径数。尚未被有效 summary 核对的对象可能只是缺少摘要,不能直接当作缺失节点。
25
+ 5. 同一 trace 中有多棵树时,全部列出并注明来源 span。按当前组件和请求父子范围选定目标树,不默认选最大或最完整的一棵。
26
+
27
+ ## 名称、绑定与展示
28
+
29
+ 从同一 dashboard/report 的只读配置或资源元数据中,一次取得所选完整树所需的 tableId/fieldId 名称映射;只有筛选器 ID 时按[名称与请求上下文的关联取证](name-binding.md#名称与请求上下文的关联取证)核对已有关系请求。每个 ID 只查询一次,将名称补入树中,不根据 ID 形态猜名称。
30
+
31
+ 每个节点标注“表名(tableId)”及字段筛选、组件筛选、参数、动态字段、联动筛选五类 summary 是否存在;明确零条件时写“筛选:无”,缺失字段保持未知。筛选器字段筛选和绑定显示“字段名(fieldId)”,有依据时补充“绑定候选筛选器 + 绑定字段名(fieldId)”。名称不足时保留 ID,并列出缺少名称的表 ID 和字段绑定,不为补名称阻塞已成立的性能结论。
32
+
33
+ `controls.binding_info` 与节点表匹配,只能建立绑定候选关系,不能证明筛选器产生了该节点的条件或实际生效。来源与生效范围须有明确的条件关联和执行记录。入口级权限信号没有节点位置时,作为树外上下文说明,不随意挂到表节点。
34
+
35
+ 完整性只证明所选结构已覆盖,不证明配置合理、交互影响唯一或筛选器导致耗时增加;这些判断仍需业务配置、执行和必要对照。
@@ -0,0 +1,9 @@
1
+ # 名称与请求上下文的关联取证
2
+
3
+ 默认 trace 详情未展示名称或请求内容时,先定向补属性,再读取当前请求日志;默认详情、索引字段清单和计数摘要都不能代表完整可查询内容。日志先查 `body`,结构化请求字段仅在实际 schema 存在时读取;不要把未索引的 `widgetId` 等请求 JSON 键直接写成顶层查询字段。
4
+
5
+ 筛选器或动态字段名称可由 `POST /v1/conf/widget/relations` 的已有请求日志补齐。该请求用于分析仪表板筛选器关系,可记录 `widgets` 和 `controls`,动态字段位置 `controls[].fieldPosition` 包含 `id/name/operatorId/tableId/widgetId`。请求日志可能截断、脱敏或未采集;只提取命中的位置对象和组件标识,不输出完整业务载荷、用户身份或会话信息。
6
+
7
+ 从 `controls.ids` 的键提取候选字段 ID 后,仍按完整 ID 比较。关系请求必须核对当前租户/用户或会话范围、组件列表包含目标组件,以及字段的表、算子、分支标识与本次绑定是否一致;能取得 report 时同时核对。不是同一执行的关系请求只提供名称与绑定元数据,不可冒充失败 trace 的直接属性、当时的选择值或默认值,也不能证明两次请求由同一次交互触发。
8
+
9
+ 查询范围与预算见[仪表板内外组件对照](../../common/topics/baseline-comparison.md#仪表板内外组件对照),取字段与过滤例子见[筛选器名称与动态字段](../queries.md#筛选器名称与动态字段)。一次补齐当前相关 ID,命中后按关联 trace 精确读取;同字段 ID 但表、算子或分支不同,名称冲突、配置可能已变时保留歧义。元数据只能支持“该次关联请求上报的字段名”,不能确认当前权威名称时说明限制;确无可用材料时再报告名称缺口,不能从表达式、截图结论或相似 ID 猜名称。
@@ -0,0 +1,45 @@
1
+ # 仪表板 · 排查入口
2
+
3
+ 仪表板 2.0 的筛选器候选值或组件取数慢时从这里下手,旧版仪表板不在范围内。只有两类取数:筛选器自身取候选值,和组件取数。首次加载、筛选值变化、参数变化和联动只是组件取数的触发上下文,不算单独的场景。仪表板组件预览入口先按[来源判定](../common/signals.md#仪表板组件预览入口)确认;概念、信号、结论、查询分别见本域的 [concepts](concepts.md)、[signals](signals.md)、[conclusions](conclusions.md)、[queries.md](queries.md)。
4
+
5
+ ## 入手
6
+
7
+ - 报错落在引擎里(超时、内存超限)时,引擎只说明撞了什么线,原因回到下面还原的业务计算里找。
8
+ - **先分清是哪类取数**:筛选器取候选值只看它怎么算候选值、别的筛选器带来什么影响;组件取数看组件自己的查询。组件请求里带着筛选条件,不代表是筛选器自身取数。
9
+ - **组件最终只显示少量数据,不代表只计算这些数据**:筛选器、参数、动态字段和行列权限都可能改变本次计算,使组件不能直接读取已有结果,而要展开来源表、关联、汇总等上游计算。重点看条件作用在哪张表、涉及哪些路径、实际多算了什么,不只看组件绑定表的大小或条件个数,见下面的[计算范围为何变大](#计算范围为何变大)。
10
+ - **优先用 trace 的 span attribute 还原本次具体业务计算**:组件算哪些查询、用了哪些字段、聚合和排序;根表、绑定表、筛选字段所在表及它们之间的完整路径;筛选、参数、权限、自动联动、组件间联动各加了什么;数据范围有没有被父表路径、无关字段、重复分支或不合理的绑定放大。先据此判断计算复杂度,再看引擎,别一上来就按慢 span 找 Metric。
11
+ - 筛选树多层或多分支时还原成完整的树,见[筛选树还原与交付](topics/filter-tree.md);筛选器或动态字段只剩 ID 时见[名称关联取证](topics/name-binding.md);怀疑上游被重算见[动态字段覆盖](topics/dynamic-fields.md);默认详情缺业务 attribute 时按[取证例子](queries.md)定向补。
12
+ - **筛选值变化后变慢**:能看出属于同一次筛选、或落在可靠时间边界内的组件请求,算这次受影响的集合;全部受影响组件刷新完成才是用户感觉的“好了”。分清是“影响范围大”还是“某一个算得慢”。没看到其他组件请求,不等于配置上绝对没有其他目标,要确认按[核对配置影响范围](conclusions.md#核对配置影响范围)读 targets。
13
+ - 选定慢或失败的引擎执行后,进入[引擎排查](../engine/workflow.md),按[Metric 获取要求](../engine/queries.md)补齐执行分析,再结合业务计算解释原因。关键组件、绑定表或更新状态可疑时转[分析表](../dataset/workflow.md)或[更新](../update/workflow.md)。
14
+
15
+ ## 组件取数先做对照
16
+
17
+ 认出是仪表板里的组件计算后,主动去找这个组件单独预览的记录,不用等用户说“单独看是好的”。查找范围见[仪表板内外组件对照](../common/topics/baseline-comparison.md#仪表板内外组件对照),可比性和成功判定见[组件计算对照怎么判断](topics/component-comparison.md#组件计算对照怎么判断)。
18
+
19
+ - 单独预览成功、仪表板里失败或变慢:逐项核对下面四类条件和联动,比较两侧直接读已有结果还是展开了上游计算;只因入口不同不能下结论。
20
+ - 两边都异常:先查共同部分,即组件查询、输入数据和计算链。
21
+ - 没找到对照:照样分析手上的异常 trace,同时提醒用户看看单独预览时是否也异常。仪表板里很快成功的请求只说明有另一条计算路径,不能当单独预览。
22
+
23
+ ## 计算范围为何变大
24
+
25
+ 筛选器、参数、动态字段、行列权限都要核对,不能看到其中一项就停止检查其他项。它们可能同时作用,也可能不增加计算;按本次请求、条件所在表和实际计划判断。
26
+
27
+ - **筛选器**:筛选条件绑在较上层父表,或经多条路径影响组件时,可能需要展开来源表、关联和汇总,带来额外计算。看筛选绑定和最终条件树,核对条件所在表到组件查询表的完整路径;联动带来的条件也要计入。不能因筛选后返回更少,就认定计算一定更少。判断与展示见[筛选树](topics/filter-tree.md),绑定调整的前提见[配置影响范围](conclusions.md#核对配置影响范围)。
28
+ - **参数**:参数改变上游计算的输入或表达式,可能使已有结果无法直接复用;绑定越靠上游,受影响的计算链可能越长。核对本次参数、页面上的绑定表和实际展开的路径;筛选树为空也不能排除参数影响。深层绑定的候选现象与建议前提见[参数案例](../cases/dashboard-parameter-deep-binding.md)。
29
+ - **动态字段**:替换上游计算字段后,下游可能需要按新字段重新展开计算。先确认本次是否有覆盖、覆盖在哪条表路径上,再核对实际计划;普通参数统计为空不能排除动态字段。取证与停止边界见[动态字段覆盖](topics/dynamic-fields.md)。
30
+ - **行列权限**:权限条件及可见字段可能改变本次可读取的数据和查询计划;权限作用于上游表时,也可能带入额外的计算路径。核对本次权限上下文、作用表和实际计划,不把“有权限条件”直接当作重算原因。入口只有权限标记、没有作用位置时,保留为上下文,不猜挂到某张表,见[筛选树中的权限边界](topics/filter-tree.md#名称绑定与展示)。
31
+
32
+ 把条件带来的计算变化与资源压力对上:先看两侧直接读已有结果还是展开了上游,再看查询长度、涉及的表路径和对应 Metric 中的计划、数据规模、耗时及内存。查询变长、路径变深只是线索,不能单独证明是哪项条件导致超时或内存超限。建议落到已核实的绑定或计算上;调整筛选、参数、动态字段或权限前,都要确认结果口径和权限语义。
33
+
34
+ ## 常见现象与候选假设
35
+
36
+ - **筛选器自身取数慢**:来源表或绑定字段多、自动解析读的范围大;别的筛选器带进的条件让查询变大;来源表的上游状态成了关键路径。对比读进来的数据量和最后的候选值数量。配了多个字段不一定慢,“按钮组绑了几个大字段又是自动解析”只是假设,不直接建议改手动解析。
37
+ - **组件取数慢**:先区分组件自身查询重,还是上述条件扩大了计算范围;一次动作触发多个组件时,再分清影响范围与关键慢组件,不把请求数直接当作计算复杂度。
38
+ - **查询语句很长、优化器超时或内存超限**:按[查询规模信号](../engine/signals.md#查询规模信号)看 `dax length`、上游查找和实际计划,再沿四类条件核对触发因素,不只查参数。优化器超时看对应错误中的 limit;内存超限看同 task 错误,不仅凭查询长度或内存峰值判定。
39
+
40
+ ## 易错点
41
+
42
+ - 没有共同的交互 ID 或可靠时间窗时,不把挨着的 trace 拼在一起。请求多不代表关键路径慢,最慢的组件也不一定解释整体完成时间。
43
+ - 仪表板只是调查起点,不代表问题就在仪表板。Metric 也不是仪表板排查的起点,替代不了对业务计算的还原。
44
+ - 不用 `valueLinkageMap` 解释仪表板 2.0 的自定义联动。`control` 里的 `type=81` 只说明是 `ComponentControl` 组件间过滤,是否跨源要结合绑定表、`value.tableId`、`filterCols` 和生成的过滤条件看。
45
+ - 不覆盖并发容量、并发退化或压测问题;同一筛选影响的多个组件只用来确认影响范围、绑定是否合理和关键路径。
@@ -0,0 +1,27 @@
1
+ # 分析表知识
2
+
3
+ 分析表的前台预览和步骤计算,以及预览所依赖的上游更新结果。只说明可能的链路与信号含义,本次事实以执行记录为准。
4
+
5
+ ## 槽位
6
+
7
+ 每个知识域都按同样的槽位组织。按要做的事选槽位,只读命中的章节。
8
+
9
+ | 要做什么 | 读 | 包含 |
10
+ |---|---|---|
11
+ | 这类问题从哪里入手 | [workflow.md](workflow.md) | 分析表排查入口:入手提示、常见现象的候选假设、易错点 |
12
+ | 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 分析表与步骤的业务概念;预览请求、步骤、上游更新、engine 之间的调查关系 |
13
+ | 认出入口,看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出分析表入口:接口、span、attribute 的含义,历史入口与当前入口的区别 |
14
+ | 看完日志和 trace,能下什么结论 | [conclusions.md](conclusions.md) | 配置、trace/log、Metric 各自能说明什么;调查时要保留的信息 |
15
+ | 写查询、选取证路径 | [queries.md](queries.md) | 在 SigNoZ 中怎样组合入口、span 与 `tableId` 取证 |
16
+
17
+ ## 展开明细
18
+
19
+ | 文件 | 何时读 | 内容 |
20
+ |---|---|---|
21
+ | [topics/steps.md](topics/steps.md) | 问题和某个步骤有关(加了某一步变慢、预览到某一步超时或内存超限),或要解释 `operatorType` 时 | 预览算到哪一步;步骤类型对照;哪些步骤容易慢或爆内存;怎么拿到步骤配置 |
22
+
23
+ ## 关联
24
+
25
+ - 相关知识域:[更新](../update/README.md):预览读取上一次更新产物时
26
+ - 相关知识域:[引擎](../engine/README.md):进入计算后的 Metric
27
+ - 相关知识域:[通用](../common/README.md):环境、trace 路由和查询规则
@@ -0,0 +1,30 @@
1
+ # 分析表 · 概念与关联
2
+
3
+ 回答“这是什么、彼此怎么关联”。
4
+
5
+ ## 业务概念
6
+
7
+ - 分析表由表配置和有序操作步骤构成,每一步拿上一步的结果继续算;预览只算到选中的那一步。步骤类型和各自的计算特点见[分析步骤](topics/steps.md)。
8
+ - 用户常见锚点包括 `tableId`、分析表预览请求、选中步骤和预览页。
9
+ - 分析表的前台预览与后台更新可能共享计算语义,但不是同一次执行。
10
+
11
+ ## 调查关系
12
+
13
+ ```text
14
+ tableId / preview request
15
+ → 分析表配置与选中步骤
16
+ → 本次预览执行
17
+ → Query
18
+ → engine task
19
+ ```
20
+
21
+ 如果预览读取的是上次更新产物,还需要保留:
22
+
23
+ ```text
24
+ analysis table
25
+ → update run
26
+ → upstream dependency
27
+ → engine write
28
+ ```
29
+
30
+ 本次预览使用的配置版本和更新结果,需要资源元数据和运行记录确认。指南只说明可能的链路。
@@ -0,0 +1,11 @@
1
+ # 分析表 · 能下什么结论
2
+
3
+ 回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么,结论能下到哪一步”。
4
+
5
+ ## 各类材料能说明什么
6
+
7
+ 配置说明分析表可能如何计算,trace/log 说明本次实际执行,Metric 说明进入计算后的执行行为。引擎的物理计算阶段不能写成 server 保存的步骤。
8
+
9
+ ## 调查时保留
10
+
11
+ 优先保留 route、入口 span、table ID、选中步骤、trace ID、耗时、错误、Query 关联和资源版本。
@@ -0,0 +1,7 @@
1
+ # 分析表 · 查询方法
2
+
3
+ 回答“怎样取证、怎样查询”。
4
+
5
+ ## SigNoZ 查询线索
6
+
7
+ 遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间,在业务 server 的 `service.name` 下组合分析表入口 route 或 `operatorsPage*` span 与 `tableId`;不要仅凭 tableId 跨环境或扫描天级时间窗。用户明确描述报错、内存超限或 OOM 时,失败信号优先于入口类型:先在相同约束内按 `tableId + 失败签名` 查询 ERROR 日志,收集全部精确命中的 trace 或 engine task,再标注它属于前台预览还是后台更新。预览与更新可能共享计算语义但不是同一次执行;相同失败签名和计算链路可以联合解释,其中的 trace、task 和 Metric 仍按执行隔离。只有不同执行指向不同原因且无法从用户现象判断目标时才请求消歧。用户只描述慢时再以入口 trace 为先。
@@ -0,0 +1,61 @@
1
+ # 分析表 · 入口与信号
2
+
3
+ 回答“怎样认出入口,各个 span、attribute、日志和字段是什么意思”。
4
+
5
+ ## 场景识别
6
+
7
+ 可用于识别操作的入口。route 是去掉部署上下文路径后的写法;SigNoZ 里的 HTTP span 名和 `http.route` 都带上下文路径,测试环境是 `/decision`,例如 `POST /decision/v1/conf/analysis/operators/page`,筛选时按实际环境的前缀匹配。
8
+
9
+ | route | 业务 span | 含义 |
10
+ |---|---|---|
11
+ | `POST /v1/conf/analysis/operators/page` | `operatorsPage` | 编辑步骤分页预览 |
12
+ | `POST /v1/conf/analysis/operators/fields` | `analysis.operatorsFields` | 当前步骤字段 |
13
+ | `POST /v1/conf/analysis/operators/count` | `analysis.operatorsPageCount` | 当前步骤行数 |
14
+ | `POST /v1/conf/analysis/step/page` | `stepPage.stepDataPreview` | 将稳定 stepId 转换为预览请求后取数 |
15
+
16
+ 业务 span 名称由控制器方法声明。统计用户操作次数时以 HTTP route 为准,不要拿业务 span 条数直接当请求数。
17
+
18
+ 历史 `POST /v1/conf/analysis/operators/page/v2` 和 `operatorsPageV2` 属于历史预览入口。历史 trace 中出现它们仍可识别当时的分析表预览,但不能作为当前环境的发现入口,也不能据此决定当前请求使用 V1 或 V2 引擎。
19
+
20
+ `stepPage.stepDataPreview` 请求也可能包含 `reportId`;脱离仪表板组件预览入口链路的 reportId 不能单独证明 仪表板 2.0 场景。
21
+
22
+ 预览入口可以记录 `tableId`、`tableName`、`selectIndex`、`subselectIndex` 和 `operatorType`。接口缺失时,入口 span 与这些 attribute 的组合仍可支持从分析表开始调查。
23
+
24
+ ## 信号含义
25
+
26
+ - `tableId`、`tableName`:标识本次预览关联的分析表;
27
+ - `selectIndex` 是请求 selected + 1(从 1 开始);`subselectIndex` 保留请求 subSelected(从 0 开始)。两者不等同于稳定业务 stepId;
28
+ - `operatorType`:当前步骤的类型(如 `Join`、`Group`、`AddNewColumn`),各类型的含义和计算特点见[分析步骤](topics/steps.md#步骤类型对照);
29
+ - Query、engine span:说明已经进入共享计算链路,不能单独证明分析表入口。
30
+
31
+ `tableId` 也可能出现在组件绑定和更新链路中。缺少入口 span、route 或其他分析语义时,不应仅凭 `tableId` 判断为分析表场景。
32
+
33
+ ## 预览的阶段
34
+
35
+ 一次分析表预览(`operatorsPage`)里的 span 结构,用来判断时间花在哪一段:
36
+
37
+ ```text
38
+ POST /v1/conf/analysis/operators/page
39
+ └─ operatorsPage
40
+ ├─ batchGetEntryInfo、batchGetTableConf 取表信息与配置
41
+ ├─ grammarCheck 逐步骤语法检查
42
+ ├─ dataModel 取数的主体
43
+ │ ├─ optimizeUsingCache 判断能否复用已缓存的步骤结果
44
+ │ ├─ createCacheTable 把某一步的结果写成缓存表,供后续步骤复用
45
+ │ │ └─ DataFlowExecutor → execute 引擎写入
46
+ │ └─ QueryExecutor → execute 引擎查询:query 提交任务,fetchBlock 轮询取结果
47
+ └─ tryGetRowCount 取行数
48
+ ```
49
+
50
+ - `dataModel` 一般占 `operatorsPage` 的大头,其中 `QueryExecutor` 是引擎查询;`grammarCheck`、`optimizeUsingCache` 一般很短。`createCacheTable` 可能比它的父 span 还长(写缓存可以在预览返回后继续),它的耗时不一定计入这次预览的响应时间,判断预览慢在哪,以 `dataModel` 和 `QueryExecutor` 为准。
51
+ - 取行数(`tryGetRowCount`)先用已有缓存的行数和步骤推算总行数,推不出来时才另发一次引擎计数查询。
52
+ - 写缓存(`createCacheTable`)和预览查询(`QueryExecutor`)可能同时在跑、读同一张来源表,会争引擎资源和内存。两者各自记开始时间和耗时,重叠多时可以作为“预览变慢”的一个候选原因,但要有资源记录才能确认。
53
+ - `optimizeUsingCache` 上有 `hit_operator_type`(命中缓存的步骤类型,如 `join`、`filter`、`group`)、`hit_operator_index`(第几步)和 `used_cache_table`:有值表示复用了缓存,没有值表示没命中。
54
+ - `QueryExecutor` 和 `DataFlowExecutor` 以下是引擎执行,进入后按[引擎知识](../engine/README.md)解读。
55
+
56
+ ## 活跃检查
57
+
58
+ 引擎查询前会对涉及的表做活跃检查,在组件计算和筛选器候选值的 trace 里都能看到,span 是 `checkUpdatePolars`,里面有 `markActive`。它把这张表和它的所有父表标记为活跃,必要时对 `updateRoots` 触发一次更新,更新场景是 `ACTIVE`(见[更新场景](../update/concepts.md#更新场景updatescene))。所以前台操作后出现的 `ACTIVE` 更新,可以从这里反查。
59
+
60
+ `checkUpdatePolars` 带 `tableId`、`tenantId`,以及 `activeScene`(触发检查的操作):`WIDGET_PREVIEW` 和 `HOME_PREVIEW` 是预览,`TABLE_EDIT` 是编辑表,`TABLE_EDIT_RED` 是编辑表时取标红信息,`TABLE_EDIT_SELECT` 是选表预览,`EXPORT` 是导出。
61
+
@@ -0,0 +1,59 @@
1
+ # 分析步骤
2
+
3
+ 分析表由一串有序的步骤组成,每一步拿上一步的结果继续算。用户说“加了某一步之后变慢”“预览到某一步就超时”时,先弄清那一步是什么类型、它在引擎里会变成什么计算,再结合这次的数据量判断。
4
+
5
+ ## 目录
6
+
7
+ - [预览算到哪一步](#预览算到哪一步)
8
+ - [步骤类型对照](#步骤类型对照)
9
+ - [哪些步骤容易慢或爆内存](#哪些步骤容易慢或爆内存)
10
+ - [怎么拿到步骤配置](#怎么拿到步骤配置)
11
+
12
+ ## 预览算到哪一步
13
+
14
+ - 预览只算到用户选中的那一步,后面的步骤不参与。trace 上的 `selectIndex` 是选中第几步(从 1 开始),`operatorType` 是这一步的类型;左右合并、上下合并里面还有子步骤时,`subselectIndex` 是子步骤的位置(从 0 开始),`operatorType` 取子步骤的类型。
15
+ - 页面上只显示前一页(Metric 计划里是 `LimitNode`),但排序、分类汇总、排名、累计这类步骤要先对全部数据算完才能截取。所以“只返回 100 行”说明不了算得少,要看引擎读了多少行、中间结果有多大,见[Metric 里常见的名字](../../engine/concepts.md#metric-里常见的名字)。
16
+ - 前面的步骤可能命中缓存(`optimizeUsingCache` 上的 `hit_operator_index`),命中时只从那一步往后算,见[预览的阶段](../signals.md#预览的阶段)。
17
+
18
+ ## 步骤类型对照
19
+
20
+ 跟用户说步骤时,用页面上的中文名和位置,比如“第 53 步:新增字段”;trace 里的类型名和 Metric 里的算子名只用来自己对照,不写进答复。
21
+
22
+ | 步骤(页面上叫) | trace 上的 `operatorType` | Metric 里大致对应 | 性能上要留意 |
23
+ |---|---|---|---|
24
+ | 选字段(选来源表和字段) | `SelectTable` | `DataSourceNode`,执行时是 `LakeConnectorSource` | 来源表的行数、列数;选的字段越多读得越多。来源表找不到时日志是 `select operator not found parentTable`,按原字段名当文本字段继续 |
25
+ | 筛选 | `FilterOperator` | `FilterNode` | 本身很轻;放得越靠前,后面算得越少 |
26
+ | 配置权限 | `PermissionSetting` | `FilterNode` | 同筛选 |
27
+ | 左右合并 | `Join` | `JoinNode`,执行时是 `ParallelHashJoinSink`(建表)+ `ParallelHashJoin`(探测);没有等值连接键时是 `CrossJoin` | 右表大小、连接键重复值。两边都有重复值时行数成倍放大,超过行数上限(物理计划里的 `rowRestrict`,按企业配置)报行数超限;两边数据量都很大又是多对多时,引擎会提前中断,报多对多关联 |
28
+ | 上下合并 | `Union` | `UnionNode` | 行数是几张表相加 |
29
+ | 分类汇总(含去重) | `Group` | `AggregateNode`,执行时是 `FinalPreHashAggregate` + `FinalMergeHashAggregate` | 分组字段组合越多,越吃内存 |
30
+ | 排序 | `Sort` | `SortNode`,后面接取一页时常合成 `TopN` | 要保存全部行再排;数据大时吃内存 |
31
+ | 新增字段:公式、分类赋值、条件赋值 | `AddNewColumn` | `ProjectNode` 里的表达式;分类赋值用了“前 N 名”这类条件时会多一个窗口计算 | 一般很轻 |
32
+ | 新增字段:累积值、排名、占比、汇总值 | `AddNewColumn` | 窗口计算,`WindowNode` 或 `WindowBINode` 都可能(不排序、整组算的多是后者) | 要按分组和排序把整组数据攒齐;不分组或分组很少时最重 |
33
+ | 新增字段:同环比、同环期 | `AddNewColumn` | `JoinNode`:上游结果当成 CTE 引用两次,再按日期错位 LEFT JOIN 自关联 | 相当于上游数据复制一份再合并,耗时和内存接近翻倍;分组字段加日期不唯一时会多对多放大 |
34
+ | 组合步骤:同环比、排名、占比、拆分到列 | `CompositiveOperate` | 同环比是 `JoinNode` 自关联,排名、占比是窗口计算(`WindowNode` / `WindowBINode`),拆分到列是 `ProjectNode` | 按里面的具体计算看,同上面对应的新增字段 |
35
+ | 行转列 | `Row2Column` | `AggregateNode`(按分组汇总出每个新列) | 输出列数由数据里的取值决定,取值多时列会很多 |
36
+ | 列转行 | `Column2Row` | `UnnestNode` | 行数约等于原行数乘以转换的列数 |
37
+ | 拆分到行 | `Unnest` | `UnnestNode` | 行数放大,倍数取决于拆出来的个数 |
38
+ | 补全缺失行 | `Complete` | 几个 `AggregateNode`(取值去重)加 `JoinNode`(补全取值和原表 FULL 合并) | 补全字段取值多、分组多时行数会暴涨 |
39
+ | 字段设置(重命名、删字段、改类型) | `FieldSet` | `ProjectNode` | 很轻 |
40
+ | 数据脱敏 | `DataMasking` | `ProjectNode` 里的表达式 | 一般很轻 |
41
+ | 动态字段 | `DynamicFieldConfig` | 没有专门的节点 | 仪表板里替换后可能让上游重算,见[动态字段覆盖](../../dashboard/topics/dynamic-fields.md) |
42
+ | 计算模型 | `ModelOperator` | 没有专门的节点,模型里的步骤各自展开 | 看模型内部的步骤 |
43
+ | 分组步骤 | `StepGroup` | 没有专门的节点,组内步骤各自展开 | 看组内步骤 |
44
+
45
+ “Metric 里大致对应”列的是逻辑计划(`analyzed info`)里的节点名,节点名和执行层的算子名都在线上 MPP Metric 和编译代码里核对过;优化器会改写合并节点,物理计划和执行层不一定一一对应。判断时以这次 Metric 里对应节点和算子的行数、内存和耗时为准,各层名字见[Metric 里常见的名字](../../engine/concepts.md#metric-里常见的名字)。新增字段在 trace 上都是同一个类型,分不出是哪一种:Metric 里出现 `WindowNode` 或 `WindowBINode` 是累积值、排名、占比这类窗口计算,出现同一张表和自己 `JoinNode` 合并多半是同环比,都没有就是公式、赋值类;拿不准时请用户看这一步的设置。
46
+
47
+ ## 哪些步骤容易慢或爆内存
48
+
49
+ - **会让行数变多的**:左右合并出现多对多、同环比自关联时日期不唯一、列转行、拆分到行、补全缺失行。看这一步前后的行数,倍数大就是放大的来源。
50
+ - **要把整批数据攒齐的**:排序、分类汇总(分组很多时)、累积值、排名、占比。数据量不变也可能吃很多内存。同环比走自关联,等于把上游再算一遍合并进来,也很重。
51
+ - **本身很轻的**:筛选、字段设置、公式、数据脱敏。这类步骤慢,多半是前面的步骤或来源表大,不是它自己。
52
+
53
+ 判断某一步是不是慢因:把选中步骤和前一步分别预览的耗时对比(用户可以直接在页面上切换选中步骤),或者在 Metric 里找这一步对应的 Operator,看它的输入输出和耗时。只凭步骤类型“看起来重”不能下结论。
54
+
55
+ 给建议时落在步骤上,比如把筛选挪到合并之前、检查连接键是否有重复、给窗口计算加上分区字段、减少补全字段的取值范围。改步骤会改变结果,要提醒用户确认业务口径。
56
+
57
+ ## 怎么拿到步骤配置
58
+
59
+ trace 上只有选中步骤的类型和位置。请求日志 `After request [POST .../operators/page ...]` 里带了请求内容,但会被截断,通常只能看到开头一两个步骤。完整的步骤列表和每一步的设置,直接请用户在分析表页面上看,或者截图给你。
@@ -0,0 +1,27 @@
1
+ # 分析表 · 排查入口
2
+
3
+ 分析表预览或步骤计算慢、失败时从这里下手。要判断的是:问题出在这次预览或步骤计算本身、依赖的资源、上游更新,还是引擎执行。概念看[概念](concepts.md),入口和信号看[信号](signals.md),能下什么结论看[结论](conclusions.md),写查询看[查询](queries.md)。
4
+
5
+ ## 入手
6
+
7
+ - 先分清编辑预览、查看结果和后台更新,这三种不是同一次执行。用户已经说了 OOM、内存超限或失败,先按同一张表、同一时间窗和失败签名把精确命中的执行都找出来,再标是哪一种;不因执行类型不同而请求消歧。
8
+ - 记下表、选中的步骤、环境、时间窗和配置版本。手上有精确的 trace 或请求,就围绕它分析。
9
+ - 现象比较笼统时,把候选执行按类型和成功、失败粗分一下。不要从最慢的成功预览直接推断用户目标。
10
+ - 报错落在引擎里(内存超限、行数超限、超时)时,引擎只说明撞了什么线,原因要回到步骤里找:哪一步把数据放大了,或者要攒齐整批数据,见[分析步骤](topics/steps.md#哪些步骤容易慢或爆内存)。
11
+ - 选定慢或失败的引擎执行后,进入[引擎排查](../engine/workflow.md),按[Metric 获取要求](../engine/queries.md)解释物理上怎么算的;线索指向后台更新或组件、仪表板,就转到[更新](../update/workflow.md)或对应的域。
12
+
13
+ ## 常见现象与候选假设
14
+
15
+ 下面这些经验用来提假设,根因还得靠这次的日志和 trace 确认。
16
+
17
+ - **预览里某个步骤突然变慢**:先按 `operatorType` 在[分析步骤](topics/steps.md)里看这一步是什么类型、会不会放大行数或要攒齐整批数据。可能是加了分组很多的分类汇总、排序、左右合并,或累积值、排名这类新增字段;可能预览用的配置版本和用户说的不一样;也可能是引擎阶段占了大头。对比一下相邻步骤的耗时,再确认真正选中的步骤和配置版本。
18
+ - **预览或更新报内存超限、行数超限**:多半是某一步把数据放大了。在 Metric 计划树里从读表往下看各节点的输出行数,行数突然变多的 `JoinNode`(左右合并、同环比)、`UnnestNode`(拆分到行、列转行),或者内存很大的窗口、汇总节点,就是放大点,再对回页面上的第几步。建议落在这一步上,比如检查连接键是否有重复、把筛选挪到前面。
19
+ - **整张分析表一直很慢**:慢点可能在基础数据读取或共享上游,而不在最后一个操作;可能上游更新没完成、失败了或者产物是旧的;也可能同一个 tableId 在问题时间窗里有好几次执行。先分清前台预览和后台更新,再看依赖表的状态和资源版本。
20
+
21
+ ## 易错点
22
+
23
+ - 静态配置只能说明可能怎么算,说明不了这一次怎么算的。
24
+ - 前台预览和后台更新可能共享计算逻辑,但不是同一次运行。失败签名和计算链路一样时可以放在一起分析,但每条记录要带着自己的执行类型、trace 和 task,避免串线。
25
+ - 时间挨着的成功 trace 不能拿来替用户报告的那次问题执行。
26
+ - 资源链接只能确定调查对象,判断不了用户关心的是预览慢、更新失败还是资源超限。
27
+ - 表状态异常时,要有对应的更新运行记录,才能说更新是根因。
@@ -0,0 +1,27 @@
1
+ # 引擎知识
2
+
3
+ 引擎执行统计(Metric):怎样定位执行并取得正文,字段含义,以及怎样解读耗时、内存和数据规模。
4
+
5
+ ## 槽位
6
+
7
+ 每个知识域都按同样的槽位组织。按要做的事选槽位,只读命中的章节。
8
+
9
+ | 要做什么 | 读 | 包含 |
10
+ |---|---|---|
11
+ | 拿到一次引擎执行,从哪里入手 | [workflow.md](workflow.md) | 引擎排查入口:获取、读取 Metric 正文、解释时的提示 |
12
+ | 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | Metric 的适用范围与执行结构(Pipeline、Operator 及其关系) |
13
+ | 认出入口,看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 时间、内存、数据规模与 Operator 信号的含义 |
14
+ | 看完日志和 trace,能下什么结论 | [conclusions.md](conclusions.md) | 变化原因与失败原因怎样判断;推荐分析顺序;怎样读取和引用原文 |
15
+ | 写查询、选取证路径 | [queries.md](queries.md) | 由问题选择执行、关联 trace 与 task、获取 Metric 正文、处理响应 |
16
+
17
+ ## 展开明细
18
+
19
+ | 文件 | 何时读 | 内容 |
20
+ |---|---|---|
21
+ | [topics/metric-fields.md](topics/metric-fields.md) | 拿到 Metric 正文、不知道某个字段什么意思或该先看哪层时 | Metric 正文结构;任务、Pipeline、算子、读表和输出各层字段及诊断用法 |
22
+ | [topics/patterns.md](topics/patterns.md) | 按现象判断引擎机制时(扫描、Join、聚合、排序窗口、Spill、Exchange、编译等) | 常见引擎性能问题与反证 |
23
+
24
+ ## 关联
25
+
26
+ - 相关知识域:[分析表](../dataset/README.md)、[组件](../component/README.md)、[仪表板](../dashboard/README.md)、[更新](../update/README.md):从各场景进入引擎排查
27
+ - 相关知识域:[通用](../common/README.md):MetricOuts 的服务过滤与查询规则
@@ -0,0 +1,80 @@
1
+ # 引擎 · 概念与关联
2
+
3
+ 回答“这是什么、彼此怎么关联”。
4
+
5
+ ## 作用与适用范围
6
+
7
+ 说明 MPP 节点 Metric 里执行结构、耗时、内存和数据规模的含义。怎么取 Metric 见[获取方法](queries.md);具体异常查[常见性能问题](topics/patterns.md);引用口径见[能下什么结论](conclusions.md#读取与引用原文的口径)。只解释这次 Metric 里出现的字段,不补造数值或执行关系;没有执行明细(`stage_infos`)的 Metric 不套用 Pipeline/Operator 规则。
8
+
9
+ ## 执行结构
10
+
11
+ ```text
12
+ analyzed info(逻辑计划)
13
+ -> SubPlans(物理计划,按片段分)
14
+ -> stage_infos -> task@...(本次运行实例)
15
+ -> pipeline@N
16
+ -> Operator(<scan> / <proc> / <sink>)
17
+ ```
18
+
19
+ - Operator 名字后的 `[编号]` 对应物理计划节点的 `nodeId`,不是页面上的步骤编号。
20
+ - 同一物理节点常拆成多条 Pipeline(如关联的建表和探测),不同 Task 也可能执行同一节点。先按 Stage、Task、Pipeline 分清运行实例;名字或编号相同、文本相邻都证明不了是同一实例或数据直连。
21
+ - 跨片段的数据交换看 `sourceFragmentId`、`sinkFragmentId` 和明确的 remote input,SubPlan 的层级本身说明不了输入来源。
22
+ - 并行 Pipeline 的时间会重叠,没有时间线时不能把耗时排名当成串行关键路径。
23
+
24
+ ### Metric 里常见的名字
25
+
26
+ 线上查询和更新都跑在 MPP 节点上。一个任务的 Metric 是一条日志,从上到下依次是任务摘要、逻辑计划、物理计划、查询汇总,耗时或内存超过门槛的任务后面还有 `stage_infos` 执行明细(结构和字段见[Metric 字段速查](topics/metric-fields.md))。名字分三层,按层看:
27
+
28
+ 1. **逻辑计划**(`analyzed info:` 下面,名字以 `Node` 结尾,缩进越深越靠近读表):
29
+
30
+ | 节点 | 大致是什么 |
31
+ |---|---|
32
+ | `DataSourceNode [dataSource=PolarsLakeTableDataSource[<表>]]` | 读一张表;`dataSource=CTE_1` 表示读的是复用的中间结果 |
33
+ | `ProjectNode` | 选列、改名、算表达式(公式类新增字段、字段设置、脱敏大多在这) |
34
+ | `FilterNode` | 筛选 |
35
+ | `JoinNode [type=LEFT on=[...]]` | 关联,`type` 是合并方式,`on` 是连接键 |
36
+ | `AggregateNode [group=[...] agg=[...]]` | 分组汇总 |
37
+ | `UnionNode` | 上下合并 |
38
+ | `SortNode` | 排序 |
39
+ | `UnnestNode` | 一行拆成多行(拆分到行、列转行) |
40
+ | `WindowNode` | 窗口计算,带 `over(partition by ... order by ...)`,比如累计 |
41
+ | `WindowBINode` | 窗口计算,`groupingKeys`、`orders` 指定分组和排序,常见的是整组汇总 |
42
+ | `LimitNode [limit: ..., offset: ...]` | 截取行数,预览、组件只取一页就在这里 |
43
+ | `OutputNode` / `Destination Node [...(WRITE)]` | 返回结果 / 写入目标表(更新任务) |
44
+
45
+ 同一份中间结果被引用多次时,计划里会多出一段 `CTE [CTE_1]`,后面的 `DataSourceNode [dataSource=CTE_1]` 读它。
46
+
47
+ 2. **物理计划**(`SubPlans:` 下面,名字是 `PHYSICAL_*`,按片段 `SubPlan: [Id: F00]` 分):优化器会改写、合并逻辑节点,个数对不上是正常的。每个节点带 `nodeId`,和下面 Operator 名字后方括号里的编号对应(如 `LakeConnectorSource@... [30]` 就是 `nodeId: 30` 那个读表节点)。
48
+
49
+ | 节点 | 大致是什么 |
50
+ |---|---|
51
+ | `PHYSICAL_TABLE_SCAN` | 读表,`predicate` 是下推到读表时的条件 |
52
+ | `PHYSICAL_FILTER`、`PHYSICAL_PROJECT` | 过滤、算表达式 |
53
+ | `PHYSICAL_HASH_JOIN` | 等值关联,`joinType`、`eqOnPredicate` 是方式和连接键 |
54
+ | `PHYSICAL_NEST_LOOP_JOIN` | 按名字看是逐行比对的关联,一般出现在没有等值连接键时;数据大时很重 |
55
+ | `PHYSICAL_HASH_AGGREGATE` | 分组汇总 |
56
+ | `PHYSICAL_AGGREGATE_TOPN`、`PHYSICAL_TOPN` | 汇总后排序取前 N 合成一步 / 排序取前 N |
57
+ | `PHYSICAL_UNION`、`PHYSICAL_UNNEST` | 上下合并、拆行 |
58
+ | `PHYSICAL_UNSORTED_WINDOW` | 不排序的窗口计算 |
59
+ | `PHYSICAL_CTE_PRODUCE` / `PHYSICAL_CTE_CONSUME` / `PHYSICAL_CTE_ANCHOR` | 中间结果算一次、多处读取 |
60
+ | `PHYSICAL_ROW_RESTRICT [rowRestrict: N]` | 行数上限保护:优化器插在读表、合并、汇总、关联等节点后面,中间结果超过 N 行就失败。N 按企业配置,以计划里写的为准;不是预览分页 |
61
+ | `PHYSICAL_LIMIT`、`PHYSICAL_OUTPUT`、`PHYSICAL_DESTINATION` | 截取、返回结果、写表 |
62
+
63
+ 3. **Pipeline 里的 Operator**(`<scan>`、`<proc>`、`<sink>` 开头,下面带 `output_rows_num`、内存等指标;只有记录了执行明细的任务才有)。一个物理节点常拆成 sink 和 scan 两端,分在前后两条 Pipeline 里:
64
+
65
+ | Operator | 大致是什么 |
66
+ |---|---|
67
+ | `LakeConnectorSource` | 读表数据 |
68
+ | `Filter`、`Project`、`RowRestrict`、`Union`、`Unnest`、`Limit` | 同名的物理节点 |
69
+ | `ParallelHashJoinSink` → `ParallelHashJoin` | 关联:前者把一边建成哈希表(看 `hash_table_size`),后者拿另一边去探测并输出 |
70
+ | `CrossJoin` | 没有等值键的关联 |
71
+ | `FinalPreHashAggregate` → `FinalMergeHashAggregate` | 汇总:先在各线程局部汇总,再合并成最终结果 |
72
+ | `AggregateTopNSink` → `AggregateTopNMerge`、`TopNSink` → `TopNMerge`、`ParallelSortSink` → `ParallelSortPreSort` | 汇总取前 N、取前 N、排序 |
73
+ | `WindowBiAggregateUnnest` | 不排序的窗口计算 |
74
+ | `Cte` | 中间结果复用:sink 端写、scan 端读,`temp_table_*_allocated` 是它占的内存 |
75
+ | `BlockOutput`、`BlockOutputFlush` | 查询结果输出 |
76
+ | `LakeConnectorSink`、`ConnectorSinkFlush` | 更新任务写表 |
77
+
78
+ 上面是按名字和线上 MPP Metric 的大致理解,没列出的名字按字面理解即可;判断时以这个节点或 Operator 自己的行数、内存和耗时为准。
79
+
80
+ 先定位异常任务和 Pipeline,再查看其中的 Operator、物理节点和数据条件。不要因为某个 Operator 名称看起来昂贵,就跳过本次运行指标直接判定根因。
@@ -0,0 +1,49 @@
1
+ # 引擎 · 能下什么结论
2
+
3
+ 回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么,结论能下到哪一步”。
4
+
5
+ ## 变化原因与失败原因
6
+
7
+ 用户问“为什么这次失败、之前却成功”时,分五层说:
8
+
9
+ 1. 本次变化:和成功执行或基线比,进入某个 Operator 的数据或输出规模变了多少;
10
+ 2. 膨胀位置:哪个 Operator 把输入放大成更大的中间结果;
11
+ 3. 资源压力位置:哪些 Pipeline 或 Operator 的状态承接了这份工作量;
12
+ 4. 直接失败条件:同 task 错误确认的内存上限、超时、行数上限等;
13
+ 5. 根因层次:只到执行层,还是已经对上了具体业务计算(哪个步骤、哪个绑定)。
14
+
15
+ 单份失败 Metric 只能说明第 2~4 层,证明不了第 1 层。两侧 Metric 都完整、同一 Operator 能稳定对齐时,输入输出的变化才能当作这次的触发因素。资源上限是原因链末端,Operator 放大是执行机制,都不单独叫根因。
16
+
17
+ | Operator 类别 | 常见候选机制 | 这次至少要看到什么 |
18
+ |---|---|---|
19
+ | 读表 | IO 慢、文件多、读得多 | 扫描行列和字节、读取耗时、任务分布 |
20
+ | 筛选 / 表达式 | 表达式计算量大、列宽、没有下推 | 输入输出规模、物理计划里的表达式、CPU |
21
+ | 汇总 | 分组多、状态大、落盘 | 输入输出行数、哈希表、内存或 spill |
22
+ | 关联 | 建表侧过大、输出放大、分支不均 | 两侧规模、哈希表、输出规模、连接方式 |
23
+ | 排序 / TopN / 窗口 | 状态随数据增长 | 输入规模、排序或窗口配置、内存 |
24
+ | 上下合并 / 交换 / 输出 | 某个分支慢、交换等待、下游背压 | 所有输入分支、blocked、输出信号 |
25
+
26
+ 表里的机制只用来选方向,不能按 Operator 名字直接认定根因。
27
+
28
+ ## 推荐分析顺序
29
+
30
+ 1. 确认是完整明细还是只有摘要,先报任务状态和阶段耗时;
31
+ 2. 找出少量异常 Pipeline,分清 wall、blocked、内存各是什么口径;
32
+ 3. 读 Pipeline 里 Operator 的数据规模和专项指标;
33
+ 4. 用 Operator 后面的编号对上物理计划节点,说明是什么计算;
34
+ 5. 把热点和这次的数据条件、资源上限、用户现象连起来;
35
+ 6. 分开写“看到的事实”“关联判断”“待验证的候选机制”。
36
+
37
+ 排名靠前只决定先查谁,不等于已经证明是根因。
38
+
39
+ ## 读取与引用原文的口径
40
+
41
+ Metric 是缩进的 `key=value` 文本,先看任务状态,再沿 Pipeline 找相关 Operator,不要整份通读。引用数字保留原值、单位和所在的 Task、Pipeline、Operator。
42
+
43
+ - **展示范围**:只看了前几名时要说明范围有限,没进前几名的节点也可能放大数据或占内存。
44
+ - **排名和合计**:不同字段、单位、口径的值不合计,也不直接当根因或同时驻留量。同名算子出现多次,不等于有多少次独立的关联或扫描。
45
+ - **输入输出比例**:只有同一个 Operator 明确给出输入和输出、单位和口径一致、没有 `-1` 时才算差值或倍数;缺输入、单位不明、负值、零分母各自说明,不用相邻节点的输出代替输入,也不跨关联、汇总、上下合并、交换手算放大率。
46
+ - **内存字段**:Pipeline 关闭快照、内存上限、`astSizeBytes`、IO 字节都不是算子内存;各类 arena、allocated、deallocated、peak、current 分开记来源,不相加。
47
+ - **单位**:`TaskStateTime` 是毫秒;别处没写单位的值保留原样,不自行当毫秒。
48
+ - **快照**:任务摘要和执行明细是不同时刻的快照,不拼成最终值;`RUNNING` 的摘要只是当时的状态。
49
+ - **两次执行的比较**:先配对唯一同名的 task(用户各给一份时可以配不同名的),Operator 优先按编号对齐;对不上的标成未匹配或有歧义,不取第一条或最后一条。缺失、`-1`、单位不同的不算差值。配对只确认材料对应,业务条件是否可比另外核对。