@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,102 @@
1
+ # 配置 SigNoZ MCP
2
+
3
+ 为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ,但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读;已有可用的 SigNoZ 工具或只有离线材料时不需要。正常首次配置只向用户请求缺少的 API Key,安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力,不分析业务问题;完成后回到原调查继续。
4
+
5
+ ## 目录
6
+
7
+ - [默认流程](#默认流程)
8
+ - [交互与结果](#交互与结果)
9
+ - [安装 MCP Server](#安装-mcp-server)
10
+ - [接入当前客户端](#接入当前客户端)
11
+ - [重载与恢复](#重载与恢复)
12
+ - [Windows 构建说明](#windows-构建说明)
13
+
14
+ ## 默认流程
15
+
16
+ 1. 确认目标环境:用户输入、现有配置或[环境知识](../concepts.md),没指定就用 work,不让用户先选。`work` 是正式环境,`prod` 不是;不按工具顺序或 `service.environment` 猜实例。URL 和口头说法冲突时只让用户确认“测试环境”还是“正式环境”,确认前不写配置。默认连接不可用就修它,不改用测试环境。
17
+ 2. 当前客户端已有能确认目标 URL 的 SigNoZ 工具,就跳过安装配置(推荐名称不同不重配),做一次最小只读验证就回原任务;本轮已有成功查询直接复用。
18
+ 3. MCP Server 缺失或损坏时,简短告知尚未安装,按“安装 MCP Server”默认安装适配当前系统和 CPU 的产物,不让用户确认版本、下载源或路径。
19
+ 4. 没有目标环境的有效凭据时只请求一次 API Key,环境能唯一确定就一并说明,不再问 URL 或 MCP 名称。用户提供 API Key 就表示同意写入本次目标环境的配置,不再追加配置确认,直接按“接入当前客户端”配好。
20
+ 5. 重载并做最小只读验证;客户端必须由用户 Trust、启用或重启时,只提示这一步。成功后立即回到原调查,不把安装变成独立任务。
21
+
22
+ 只配置当前正在运行的 Agent 客户端,不要因为发现 Cursor、Codex、WorkBuddy 等其他客户端的配置文件就切换目标。只有环境确定不了、平台不支持、同名配置冲突或配置方式确实判断不了时,才请用户补最小的信息。
23
+
24
+ ## 交互与结果
25
+
26
+ - 正常成功路径只说明 MCP 已准备好并继续原任务;不主动展示 checksum、压缩包、安装目录、完整配置或排障过程。
27
+ - 安装后等待 Key 时,直接说明“当前没有可用的 SigNoZ MCP,已经完成安装,请提供 `<环境>` 的 API Key 以继续配置和诊断”。
28
+ - 不回显用户提供的 API Key,也不把它写入仓库、知识、fixture 或报告;只写入当前客户端支持的本机配置。
29
+ - 失败时说明准确阻断和下一项最小动作,不用重装掩盖环境、凭据、权限或网络问题。
30
+
31
+ ## 安装 MCP Server
32
+
33
+ 仅在 MCP Server 或客户端配置缺失、损坏时执行。安装程序不接收 SigNoZ URL 和 API Key,也不修改客户端配置。
34
+
35
+ macOS 和 Linux 优先执行包内的 Python 脚本;npm 安装副本经 CLI 的 `python` 命令运行(见[安装副本的助手规则](../../../AGENTS.md#安装副本的助手规则)):
36
+
37
+ ```bash
38
+ python3 scripts/install_signoz_mcp.py
39
+ ```
40
+
41
+ Windows 使用系统自带 PowerShell,不依赖 Python:
42
+
43
+ ```powershell
44
+ powershell.exe -File scripts\install_signoz_mcp.ps1
45
+ ```
46
+
47
+ 当前工作目录不是内容根目录时使用脚本的绝对路径。只有需要改变默认用户级安装目录时才传入 `--install-dir <absolute-directory>`(PowerShell 为 `-InstallDir <absolute-directory>`)。
48
+
49
+ 脚本会自动:
50
+
51
+ 1. 识别 macOS、Linux 或 Windows 及 CPU 架构;
52
+ 2. 从组织 OSS 下载固定的 checksum 清单和对应压缩包;
53
+ 3. 校验 SHA-256 后安全解压;
54
+ 4. 返回供客户端配置使用的绝对 `command` 路径。
55
+
56
+ 支持 macOS 和 Linux 的 amd64、arm64,以及 Windows amd64;不受支持的平台应明确停止,不要改用名称相近的产物。
57
+
58
+ 脚本不可用时,可用系统原生工具完成同等步骤,但必须同时满足:只访问 `https://signoz-mcp.oss-cn-beijing.aliyuncs.com/`、先读取 `signoz-mcp-server_0.10.0_checksums.txt`、精确匹配当前平台文件名、SHA-256 一致后才解压。不要跳过校验,也不要把二进制或 checksum 复制进本仓库。
59
+
60
+ ## 接入当前客户端
61
+
62
+ 用当前客户端公开支持的 MCP 管理命令、界面或用户级配置接入。最小配置语义:
63
+
64
+ ```text
65
+ server name -> 目标环境对应的稳定名称
66
+ command -> 安装脚本返回的绝对路径
67
+ SIGNOZ_URL -> 已确认的 SigNoZ 地址
68
+ SIGNOZ_API_KEY -> 使用者提供的该环境凭据
69
+ ```
70
+
71
+ - Key 用客户端支持的本机持久方式保存,不回显,不写进仓库、项目配置、知识、fixture 或报告。
72
+ - 测试和正式环境分别配置,不复用或覆盖凭据;默认连接缺凭据时只要该环境的 Key,不改用已可用的其他环境。
73
+ - 增量修改已有配置,保留无关的 server 和字段;支持工具 allowlist 时只启用诊断需要的只读工具。
74
+
75
+ ## 重载与恢复
76
+
77
+ 配置完成后按客户端支持的方式重载;无法自动完成 Trust、启用或重启时,只把这一项动作交给用户。随后依次验证:客户端发现 server、command 可以启动、最小只读请求成功(例如 `signoz_list_services` 取 1 条服务,时间范围 1 小时,参数以当前工具声明为准)、精确 ID 能在目标环境查询。成功后直接回到原任务,不向用户展开安装和配置明细。
78
+
79
+ | 现象 | 优先检查 |
80
+ |---|---|
81
+ | 客户端看不到工具 | 配置是否加载、server 是否启用、是否需要重载 |
82
+ | server 启动失败 | command、文件存在性、平台架构、执行权限 |
83
+ | 401 | 没有凭据或凭据无效;URL 与凭据是否属于同一环境,只请求目标环境的 Key,不换用其他环境的 Key |
84
+ | 403 | 凭据有效但角色不够,只读查询至少需要 Viewer 级别;请使用者换用有读取权限的 Key |
85
+ | 工具存在但报字段 / schema 错误 | 工具版本与说明不一致;重新读取当前工具声明或修复 MCP 版本,不沿用旧参数硬试 |
86
+ | 查询不到目标数据 | 精确 ID、时间与环境是否正确 |
87
+ | 网络失败 | DNS、代理、OSS 或 SigNoZ 服务状态 |
88
+
89
+ 只重做失败层及其后续验证,不重复已通过的步骤。
90
+
91
+ ## Windows 构建说明
92
+
93
+ Windows amd64 压缩包由组织维护并托管于 `signoz-mcp.oss-cn-beijing.aliyuncs.com`,用于补足当前上游发行版没有 Windows 原生产物的情况。
94
+
95
+ - 文件名:`signoz-mcp-server_windows_amd64.zip`,内容为 `signoz-mcp-server.exe`。
96
+ - 上游:[SigNoZ MCP Server](https://github.com/SigNoz/signoz-mcp-server),Apache-2.0 License。
97
+ - 构建:Go Windows amd64、`CGO_ENABLED=0`,内嵌版本为 `v0.0.6-0.20260224044326-53d3bdfb5af6+dirty`;是组织构建,不是上游官方 v0.10.0 Windows Release。
98
+ - 签名:当前 PE 文件没有数字签名,不应通过关闭系统安全策略绕过拦截。
99
+ - 校验:安装时以同一 OSS 上的 `signoz-mcp-server_0.10.0_checksums.txt` 为准;仓库不保存二进制或 checksum 副本。
100
+ - 验证范围:来源、架构和 hash;真实 Windows 客户端启动与最小只读查询尚未验证。
101
+
102
+ 产物来源、构建方式或发布责任变化时,先更新并审核本说明,再调整安装入口。
@@ -0,0 +1,19 @@
1
+ # 从现象或截图开始
2
+
3
+ 还没有可信的执行锚点时读:怎样判断 ID 能不能直接用,以及按用户描述的现象决定先查什么。与[查询方法](../queries.md)配套。
4
+
5
+ ## 锚点可信度
6
+
7
+ - 用户直接粘贴的 URL、ID 文本以及工具返回的结构化字段可以作为精确锚点。
8
+ - 截图、OCR 和人工转抄得到的值只作为候选。先逐字符核对原始材料;`g/q`、`0/o`、`1/l` 等字符无法可靠区分时,向用户展示识别结果并请求确认或粘贴原始文本。
9
+ - 截图候选第一次精确查询为零时,零结果不能证明没有执行。先复核锚点;锚点未确认前,不得通过扩大时间、切换环境或移除 `service.name` 来补偿可能的字符错误。
10
+ - 确认锚点后再进入场景域,避免下游在错误 ID 上生成更完整但无关的分析。
11
+
12
+ ## 按现象决定先查什么
13
+
14
+ - 用户明确描述报错、更新失败、内存超限、OOM 或 `MemoryLimitExceeded` 时,先在已确认的环境、时间、`service.name` 和资源锚点内查询 ERROR 日志,收集全部精确命中的执行,从结果提取 traceId、chainId、taskId、执行类型或其他执行 ID,再精确读取 trace。第一次没有命中时,只在同一环境、时间、服务和资源锚点内去掉 severity 限制查一次;不能先做全局错误搜索,也不能先挑最慢的成功 trace。
15
+ - 上述错误首查顺序用于尚未锁定执行的资源发现。已有精确失败 trace/task 或直接错误记录时,复用现有记录,只补尚未确认的提交、阶段或失败条件;不为重复确认报错先查 ERROR、再查同 span 的全级别业务日志。需要生命周期记录时,一次精确查询所需记录。
16
+ - 预览、查看、更新、ETL 等执行类型用于防止不同运行的 trace、log 和 Metric 串线,是执行记录的上下文,不是用户必须预先选择的调查分支。同一资源和时间窗内的多个执行如果具有相同失败签名和计算链路,可以联合解释;不能仅因执行类型不同就请求用户消歧。只有不同执行指向不同原因且用户目标无法推断时,才展示差异并询问。
17
+ - 用户明确描述慢、卡顿或耗时回归,且没有失败信号时,优先按入口、资源锚点和时间寻找 trace,再沿关键路径读取关联日志或 Metric。
18
+ - 用户只说“性能问题”时,在受控范围内浅分型成功慢执行与失败执行,展示仍然可信的候选差异;不要替用户默认选择最慢或最新的一类。
19
+ - engine Metric 用来解释已经锁定的执行,不是发现业务执行的第一入口。只有已经取得 taskName、Metric 链接或精确 trace 关联时才查询 MetricOuts。
@@ -0,0 +1,22 @@
1
+ # 通用 · 性能排查入口
2
+
3
+ 用户说慢、超时、内存超限、OOM、资源消耗异常或性能回归时,从这里找方向。这里只是提示和容易踩的坑,没有必须按顺序走完的步骤,材料够了就直接回答。
4
+
5
+ ## 从哪里开始
6
+
7
+ - 环境、时间、历史对比的默认值见[公共查询规则](queries.md)的“默认值速查”。用户说“之前没超限”“最近变慢”,就已经是在要历史对比,不用等他再说一句“帮我对比”。
8
+ - 场景清楚就直接进对应的域:[分析表](../dataset/workflow.md)、[组件](../component/workflow.md)、[仪表板](../dashboard/workflow.md)、[更新](../update/workflow.md#更新性能排查)。给的是企业 ID 或 dagId,就从更新进。
9
+ - 只有 trace、执行链接,或者看不出是哪个场景,先读[场景识别](signals.md)。仪表板组件预览入口要按[来源判定](signals.md#仪表板组件预览入口)分流,光看最外层 HTTP span 或 `previewComponent` 这个 span 名分不出来。
10
+ - 用户只给了资源,或者只说“有性能问题”,先挑几条候选执行看看:属于哪个场景、成功还是失败、是 OOM 还是 timeout。不要直接深挖最慢的成功执行。用户已经说了内存超限、OOM、保存失败,就用失败签名作为第一次检索条件,执行类型只当背景信息。
11
+ - 只想拿到或看懂一份 Metric,直接看[引擎知识](../engine/workflow.md)。
12
+ - 实时查询被工具、连接或鉴权挡住了,看[配置 SigNoZ MCP](topics/setup-signoz-mcp.md),弄好再继续。
13
+
14
+ ## 易错点
15
+
16
+ - OOM、超时、行数上限是直接失败条件,不是根因。报错位置多半在引擎,原因多半在业务场景:在引擎里看清撞了什么线以后,回到场景域找是什么让计算变得这么大:分析表是哪个步骤放大了数据,更新是哪个节点或哪个上游,组件和仪表板是查询、筛选、参数或绑定。建议也要落在这一层。
17
+ - 已取消或没提交的执行(比如日志里有 `not submitted, skip finish`)根本没开始计算,有 task ID、Metric 链接或一个整数超时时长都证明不了算过。这时该解释的是取消链、等待或准入,没必要再去找计算统计。
18
+ - 选定慢或失败的引擎执行后,按[Metric 获取要求](../engine/queries.md)主动取数并分析。如果只看到业务层的 `polars query timeout`,先补读这次执行的属性,或者从同一个 trace 的提交日志里找回 task,别急着认定 Metric 拿不到。
19
+ - 用户说“之前没超限”“以前正常”,但近几天找不到这个对象成功的记录时,就直接告诉用户:近 N 天没找到成功记录,和“之前正常”对不上,请他确认是哪张表、什么时候开始异常。不要顺着用户的说法去解释“为什么这次变了”。
20
+ - 单次失败不需要成功样本。用户要求对比,或者手上正好有可比的成功执行,再去对比,目标和基线各自固定自己的范围。
21
+ - 业务解释和 Metric 谁也替代不了谁:慢 span 只告诉你慢在哪一段,Metric 只解释进入引擎以后的事。
22
+ - 别的执行类型只是错误签名相同、没有自己的计算记录时,只能当旁证,不要并进同一条原因链。
@@ -0,0 +1,26 @@
1
+ # 组件知识
2
+
3
+ 组件(图表)的数据请求:图表编辑时的查询,以及走仪表板组件预览入口的仪表板以外的图表预览。来自仪表板的组件预览归仪表板域。
4
+
5
+ ## 槽位
6
+
7
+ 每个知识域都按同样的槽位组织。按要做的事选槽位,只读命中的章节。
8
+
9
+ | 要做什么 | 读 | 包含 |
10
+ |---|---|---|
11
+ | 这类问题从哪里入手 | [workflow.md](workflow.md) | 组件取数排查入口:入手提示、常见现象的候选假设、易错点 |
12
+ | 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 组件、数据绑定与关联分析表的业务概念;调查关系 |
13
+ | 认出入口,看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出组件入口:接口、span、attribute、`reportId` 与请求上下文的含义 |
14
+ | 看完日志和 trace,能下什么结论 | [conclusions.md](conclusions.md) | 什么情况下不能由 span 或字段直接下结论;调查时要保留的信息 |
15
+ | 写查询、选取证路径 | [queries.md](queries.md) | 在 SigNoZ 中怎样组合组件入口与资源标识取证 |
16
+
17
+ ## 展开明细
18
+
19
+ 本域没有展开明细,所有内容都在上面的槽位里。
20
+
21
+ ## 关联
22
+
23
+ - 相关知识域:[仪表板](../dashboard/README.md):仪表板组件预览入口来自仪表板时(占绝大多数)
24
+ - 相关知识域:[分析表](../dataset/README.md):组件关联的查询表
25
+ - 相关知识域:[引擎](../engine/README.md):进入计算后的 Metric
26
+ - 相关知识域:[通用](../common/README.md):仪表板组件预览入口的来源判定
@@ -0,0 +1,22 @@
1
+ # 组件 · 概念与关联
2
+
3
+ 回答“这是什么、彼此怎么关联”。
4
+
5
+ ## 业务概念
6
+
7
+ - 组件以 `widgetId` 或 `component.id` 为主要锚点,并绑定一个或多个查询表。
8
+ - 组件查询可能携带筛选、联动、权限、聚合、排序和分页上下文。
9
+ - 组件慢既可能来自本次查询,也可能来自所依赖分析表的状态或更新。
10
+
11
+ ## 调查关系
12
+
13
+ ```text
14
+ widgetId / component.id
15
+ → 数据绑定与查询上下文
16
+ → component query execution
17
+ → analysis table
18
+ → Query
19
+ → engine task
20
+ ```
21
+
22
+ 不能因为 trace 中出现组件 span 就排除 dashboard 入口,也不能因为底层表正在更新就直接判定更新是根因。
@@ -0,0 +1,11 @@
1
+ # 组件 · 能下什么结论
2
+
3
+ 回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么,结论能下到哪一步”。
4
+
5
+ ## 各类材料能说明什么
6
+
7
+ 组件配置说明可能发起哪些查询,trace/log 记录本次发起的查询,Metric 展示计算过程。按 ID、时间窗和执行关联核对这些材料后,再合在一起解释。
8
+
9
+ ## 调查时保留
10
+
11
+ 优先保留入口 route、请求上下文、组件 ID、绑定表、report ID、筛选/联动摘要、关键 span、耗时、错误和 Query 关联。
@@ -0,0 +1,7 @@
1
+ # 组件 · 查询方法
2
+
3
+ 回答“怎样取证、怎样查询”。
4
+
5
+ ## SigNoZ 查询线索
6
+
7
+ 遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间,在业务 server 的 `service.name` 下组合组件入口 route、`editComponent`/`previewComponent`/`queryData` 与 `component.id` 或 widgetId。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)定向补取父子链中的上下文属性,不只读取 HTTP 根 span。
@@ -0,0 +1,75 @@
1
+ # 组件 · 入口与信号
2
+
3
+ 回答“怎样认出入口,各个 span、attribute、日志和字段是什么意思”。
4
+
5
+ ## 场景识别
6
+
7
+ 已确认的入口包括:
8
+
9
+ - `POST /v2/design/widget/data`:图表编辑时的取数;
10
+ - `POST /v2/external/widget/data`:仪表板组件预览入口(代码里叫外部组件取数),绝大多数来自仪表板,少数是仪表板以外的图表预览,需要结合请求上下文区分;
11
+ - `POST /v2/query/data`:`queryData` 通用组件查询入口,不能仅凭 span 名补全画布或筛选器上下文。
12
+
13
+ 已确认的特征 span 包括 `editComponent`、`previewComponent` 和 `queryData`。组件计算链路还可能出现 `getComponentMatrixData`。route 在 SigNoZ 里带部署上下文路径,见[识别方法](../common/signals.md#识别方法)。
14
+
15
+ 仪表板组件预览入口的关键 attribute:
16
+
17
+ - `data.endpoint=external_component_data`;
18
+ - `data.request_context=component_preview`:从组件场景开始;
19
+ - `data.request_context=dashboard`:完全交给仪表板场景;
20
+ - `component.id`、`component.type`、`component.query.table_id`:组件和绑定表锚点。
21
+
22
+ ## 信号含义
23
+
24
+ - `component.id` 或用户提供的 `widgetId` 用于关联组件资源;
25
+ - `component.query.table_id` 表示组件查询绑定表,可用于进入分析表调查;
26
+ - 仪表板组件预览入口的 `reportId` 与 request context 按[来源判定](../common/signals.md#仪表板组件预览入口)解释,不能把关联字段直接当作场景结论;
27
+ - 筛选器、筛选、联动和权限 attribute 描述本次请求上下文,不直接证明它们造成性能问题。
28
+
29
+ 只有通用 Query 或 engine span,或者只有共享的 `tableId`,都不足以确认组件场景。
30
+
31
+ ## 组件计算的阶段
32
+
33
+ 仪表板组件预览入口(仪表板以外的图表预览也走这里)里,`previewComponent` 之下按顺序是这些阶段:
34
+
35
+ ```text
36
+ POST /v2/external/widget/data
37
+ └─ previewComponent
38
+ ├─ data.component.resolvePublishedTable 取已发布表
39
+ ├─ data.component.checkPublishedTableStatus 检查已发布表的状态
40
+ ├─ data.component.buildControlContext 把筛选器、联动整理成过滤条件
41
+ ├─ data.component.checkTableStatus 检查表是否可读
42
+ ├─ data.component.analyzeControlContext 把过滤条件应用到输入表
43
+ └─ data.component.executeRequest 执行查询
44
+ └─ data.component.executeSingleQuery
45
+ └─ QueryExecutor → execute 引擎查询:query 提交任务,fetchBlock 轮询取结果
46
+ ```
47
+
48
+ 这是主干,实际 trace 里每段下面还会嵌套不少 span,比如活跃检查 `checkUpdatePolars` 通常挂在 `analyzeControlContext` 之下。用它判断时间花在哪一段:`executeRequest` 一般占 `previewComponent` 的大头,其次是 `analyzeControlContext`,其余几段很短。`executeRequest` 占大头说明时间在引擎。`QueryExecutor` 下的 `query` 只是把任务交给引擎,通常很短;之后反复 `fetchBlock` 取结果,引擎没算完时取到的是空块(`rowCount=0`),所以引擎计算的时间主要落在这些 `fetchBlock` 里,不是传数据慢。具体算在哪,按 `taskName` 取 Metric,见[引擎知识](../engine/README.md)。引擎之前的活跃检查 `checkUpdatePolars` 见[分析表 · 活跃检查](../dataset/signals.md#活跃检查)。
49
+
50
+ ## 取数结果与失败
51
+
52
+ `previewComponent` 上的 `result.status` 是本次取数的结果。图表编辑时(`editComponent`,路径是 `editComponent → data.component.executeSingleQuery → QueryExecutor`)没有 `result.status` 和 `error.class`,错误原文看出错 span 的 `status_message` 和同一 trace 的日志。
53
+
54
+ | 取值 | 含义 |
55
+ |---|---|
56
+ | `success` | 取到数据 |
57
+ | `empty` | 成功,但结果为空 |
58
+ | `updating` | 底层表正在更新,没有返回结果 |
59
+ | `error` | 失败,原因看 `error.class` |
60
+
61
+ 失败时 `error.class` 是根因异常的类名,常见的有:
62
+
63
+ | `error.class` | 一般表示 |
64
+ |---|---|
65
+ | `TaskCancelledException` | 任务被取消,不是计算失败 |
66
+ | `TableInvalidException` | 表当前不可用(默认消息是所在文件夹正在同步) |
67
+ | `NoSuchEntryInfoException` | 引用的表不存在 |
68
+ | `NoFieldFoundException`、`NoParameterFoundException` | 引用的字段或参数已不存在 |
69
+ | `IllegalTableMarkedException` | 表被标红 |
70
+ | `QueryTimeOutException` | 引擎查询超时 |
71
+ | `MemInsufficientException` | 引擎内存不足 |
72
+ | `JoinN2NException` | 关联出现多对多 |
73
+
74
+ 遇到未列出的类名,照错误消息原文说明,只凭类名猜出的含义要标明是推测。`result.status=error` 不一定是性能问题,`TaskCancelledException` 和 `TableInvalidException` 都与计算快慢无关。
75
+
@@ -0,0 +1,23 @@
1
+ # 组件 · 排查入口
2
+
3
+ 组件(图表)取数慢或失败时从这里下手。要判断的是:问题出在请求上下文、数据绑定、组件查询、关联的分析表、上游更新,还是引擎执行。概念看[概念](concepts.md),入口和信号看[信号](signals.md),能下什么结论看[结论](conclusions.md),写查询看[查询](queries.md)。
4
+
5
+ ## 入手
6
+
7
+ - 先分清是图表编辑时的预览、仪表板里的组件请求,还是仪表板以外的图表预览。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)确认;来自仪表板的,直接转到[仪表板知识](../dashboard/workflow.md)。用户只说“图表慢、超时”时,第一步就是做这个区分。
8
+ - 记下组件、绑定表、筛选、联动和权限上下文、环境、时间窗,以及用户感觉到的耗时。用精确 ID、请求上下文和时间窗缩小候选执行,不要按最慢的 span 挑。
9
+ - 主要看三件事:一次是不是触发了多个查询,或者带了复杂的筛选、联动、聚合、排序;trace 里耗时集中在哪个阶段;绑定分析表的资源版本或更新状态和这次有没有关系。
10
+ - 选定慢或失败的引擎执行后,进入[引擎排查](../engine/workflow.md),按[Metric 获取要求](../engine/queries.md)补齐执行分析;线索指向分析表或更新时,转到对应的域。
11
+
12
+ ## 常见现象与候选假设
13
+
14
+ - **请求数量或计算量太大**:一个组件实际发了好几个查询;筛选、联动、权限上下文把查询放大了;高基数聚合、排序或 TopN 占了主要时间。数一下同一次动作发了多少查询,看看这次请求带了哪些筛选器和联动上下文。
15
+ - **慢在绑定的分析表**:绑定表还在更新、更新失败或者结果是旧的;组件查询本身很轻,慢在读表或算表。用 `component.query.table_id` 或资源配置确认真实绑定,再核对更新时间、版本和当前 trace 的关系;对不上时间或版本,只能说相关或推测。
16
+
17
+ ## 易错点
18
+
19
+ - 配置说明组件可能发起什么查询,trace 才说明这一次实际发了什么。
20
+ - 仪表板 trace 里出现组件 span,不代表业务入口是组件预览,也不代表问题在组件配置。
21
+ - 底层表正在更新、组件恰好变慢,这只是时间上相关,不够确认因果。
22
+ - 只看到通用的引擎 span,确认不了是组件场景。
23
+ - 没有完整的仪表板交互记录时,不要说已经还原了全部请求扩散。
@@ -0,0 +1,31 @@
1
+ # 仪表板知识
2
+
3
+ 仪表板 2.0的筛选器候选值取数与组件计算。旧版仪表板不在覆盖范围内。
4
+
5
+ ## 槽位
6
+
7
+ 每个知识域都按同样的槽位组织。按要做的事选槽位,只读命中的章节。
8
+
9
+ | 要做什么 | 读 | 包含 |
10
+ |---|---|---|
11
+ | 这类问题从哪里入手 | [workflow.md](workflow.md) | 仪表板排查入口:入手提示、组件取数先做对照、常见现象的候选假设、易错点 |
12
+ | 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 仪表板、筛选器、组件、筛选与联动的业务概念;调查关系 |
13
+ | 认出入口,看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出仪表板入口与来源:接口、attribute、筛选器与联动观测字段的含义 |
14
+ | 看完日志和 trace,能下什么结论 | [conclusions.md](conclusions.md) | 各类材料能说明什么;调查时要记下的信息 |
15
+ | 写查询、选取证路径 | [queries.md](queries.md) | SigNoZ 查询线索,以及按问题组织的取证例子(已有 trace、单独预览对照、筛选器名称与动态字段、资源发现、筛选树) |
16
+
17
+ ## 展开明细
18
+
19
+ | 文件 | 何时读 | 内容 |
20
+ |---|---|---|
21
+ | [topics/component-comparison.md](topics/component-comparison.md) | 需要判断仪表板内组件和单独预览是否可比、成功是否成立时 | 组件计算对照怎么判断 |
22
+ | [topics/dynamic-fields.md](topics/dynamic-fields.md) | 筛选器里有动态字段或参数、怀疑上游被重算时 | 动态字段覆盖与上游展开 |
23
+ | [topics/name-binding.md](topics/name-binding.md) | 只有筛选器或字段 ID、需要还原名称和绑定关系时 | 名称与请求上下文的关联取证 |
24
+ | [topics/filter-tree.md](topics/filter-tree.md) | 组件计算有多层过滤树、需要还原并展示完整树时 | 筛选树还原与交付 |
25
+
26
+ ## 关联
27
+
28
+ - 相关知识域:[组件](../component/README.md):图表编辑,以及仪表板以外的图表预览
29
+ - 相关知识域:[分析表](../dataset/README.md):组件绑定的查询表
30
+ - 相关知识域:[引擎](../engine/README.md):进入计算后的 Metric
31
+ - 相关知识域:[通用](../common/README.md):仪表板组件预览入口的来源判定
@@ -0,0 +1,26 @@
1
+ # 仪表板 · 概念与关联
2
+
3
+ 回答“这是什么、彼此怎么关联”。
4
+
5
+ ## 业务概念
6
+
7
+ - 仪表板包含组件和筛选器。
8
+ - 仪表板性能调查只有两个一级取数场景:筛选器自身候选值取数、组件取数。首次加载、筛选值变化、参数变化和联动是触发组件取数的动作,不是第三类取数场景。
9
+ - 筛选器取数用于计算当前筛选器有哪些候选值,只可能受其他筛选器的筛选影响。
10
+ - 组件取数用于执行当前组件计算。影响因素不限于筛选器,至少包括组件自身的查询配置、绑定表与算子、普通筛选器条件、参数、权限、自动联动和组件间自定义联动。
11
+ - 仪表板 2.0 不再使用 `valueLinkageMap` 表达联动。
12
+ - `control` 是组件取数请求 payload 的字段。其中 `type=81` 映射为 `ComponentControl`,表示组件间过滤;它不能单独证明跨源。跨源需要比较当前组件绑定表、`value.tableId`、`filterCols` 和实际生成的过滤条件。
13
+ - 用户选择筛选值后可能触发多个受影响组件重新取数。用户感知完成点是全部受影响组件刷新完成;筛选器自身的候选值取数不属于该计算集合,应作为独立筛选器取数问题分析。
14
+
15
+ ## 调查关系
16
+
17
+ ```text
18
+ dashboard / reportId
19
+ → control option query, or component calculation
20
+ → component trigger: load / filter change / parameter change / linkage / refresh
21
+ → optionally related component calculations
22
+ → bound analysis tables
23
+ → current query or upstream update
24
+ ```
25
+
26
+ 调查应区分请求扩散、关键组件慢、筛选器候选值计算、上游表状态和 engine 执行,不能把“仪表板慢”当作单一后端请求。
@@ -0,0 +1,21 @@
1
+ # 仪表板 · 能下什么结论
2
+
3
+ 回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么,结论能下到哪一步”。组件对照、动态字段、筛选器名称和筛选树等展开主题见 README 的“展开明细”。
4
+
5
+ ## 各类材料能说明什么
6
+
7
+ 默认先解释当前筛选器或组件计算,不把组件取数预设为筛选触发。只有明确存在同一筛选时,才在能对上同一筛选或可靠时间窗的范围内观察全部受影响组件,以验证筛选绑定位置、影响范围和用户感知完成点;只看到单个组件 trace 时,仍应说明无法证明完整 dashboard fan-out。
8
+
9
+ 本域不覆盖并发容量、并发退化或压测问题。这里的多个相关组件计算属于一次业务交互的影响集合,不等同于并发性能诊断。
10
+
11
+ ## 调查时保留
12
+
13
+ 优先保留用户现象、入口 route、request context、report/dashboard、筛选器和组件 ID、查询字段与计算类型、绑定表和完整关系路径、候选值来源表、筛选树、参数、权限、`linkage`、`ComponentControl`、关联请求、耗时和错误。先用这些信息形成“具体算了什么、复杂在哪里、哪里扩大了范围”的业务解释。默认按单个筛选器或组件请求解释;只有明确是筛选值变化后多个组件刷新时,才组织全部受影响组件,筛选器自身的候选值取数仍单独分析。
14
+
15
+ 对筛选绑定影响,优先寻找同组件、同查询形态、同一短时间窗内不携带目标筛选器的基线,比较请求耗时、`node_count`、`max_depth` 和 `table_paths`。只有耗时而输入或查询形态不可比时,不宣称差异全部由筛选器导致。
16
+
17
+ ### 核对配置影响范围
18
+
19
+ “可靠交互窗内没有观察到其他组件请求”只限定本次观测范围。要确认配置上没有其他组件受影响,必须读取 仪表板 2.0 `relatedFields`/targets,并按目标画布 `instanceId` 判断;`componentRef`/组件资产 ID 可被多个实例复用,不能替代按实例确认的目标。Trace 当前也不直接记录 `MAIN/COMPONENT` 筛选阶段或完整 `controlId → target instanceId` 映射,因此仅凭 Trace 可以确认上游绑定造成额外路径,但“可下移到哪个阶段”仍需配置验证。
20
+
21
+ 配置读取配方仅适用于已经提供的脱敏配置或当前可用的只读配置能力:从 control 的 `relatedFields`/targets 建立 `controlId → target instanceId` 集合,分别记录 instanceId 与 componentRef,再解析每个目标的绑定字段和阶段。普通 tableId 对应 MAIN,组件目标绑定对应 COMPONENT;只有 targets 唯一且目标字段在 COMPONENT 阶段存在时,才能把“只影响当前组件”和具体下移位置写成已验证的配置建议。缺少任一关联时保持未知,不用运行时“没看到请求”补成配置事实,也不虚构读取接口。
@@ -0,0 +1,69 @@
1
+ # 仪表板 · 查询方法
2
+
3
+ 回答“怎样取证、怎样查询”。环境、时间、服务、上限和结果复用遵守[公共查询规则](../common/queries.md);下面的例子说明查询意图,不规定命令顺序。
4
+
5
+ ## SigNoZ 查询线索
6
+
7
+ - 从资源出发:在业务 `service.name` 下,用用户动作的时间,组合筛选器或组件入口、`reportId`、control/component ID 和 request context,只找触发动作附近的候选请求;没有共同交互 ID 或可靠时间边界时,不扩成整天的扫描。
8
+ - 已有精确 trace 但默认详情缺业务 attribute 或被截断:复用 traceId、业务服务和时间窗,按下面的字段清单定向补缺的字段,结果按父子 span 合并,不要求属性都在 HTTP 根 span 上。
9
+ - `reportId`/dashboardId 先找筛选器或仪表板组件预览入口,组件 ID 先找 `component.id`。用户给的是组件资产 ID 时,还要确认它和画布 `instanceId`/widgetId 的对应,一个资产可能在多个仪表板实例里。
10
+
11
+ ## 已有精确 trace
12
+
13
+ 按 `trace_id` 和已确认业务 `service.name` 取得本次入口、组件/筛选器和筛选树记录。必要业务记录包括 `previewComponent`、`FilterConditionsBuilder.build`、`data.component.buildControlContext`、`data.control.calculateOptions`、`data.control.engineExecute`,以及 `data.endpoint=design_control_data` 或有关筛选器/仪表板组件预览入口的 `http.route`。不要求每条记录同时有所有属性。
14
+
15
+ ```text
16
+ trace_id = '<已确认trace>' AND service.name = '<业务服务>'
17
+ ```
18
+
19
+ 只选择当前判断需要的字段:
20
+
21
+ - 关联和时间:`name`、`trace_id`、`span_id`、`parent_span_id`、`timestamp`、`duration_nano`;
22
+ - 本次计算:`reportId`、`data.request_context`、`data.endpoint`、`http.route`、`component.id/type/query.table_id`;
23
+ - 筛选器影响:`controls.ids/names/binding_info/raw_binding.table_ids/raw_binding.field_ids`、`controls.effect_count/input_count/effect_type_counts/valued_effect_count`,涉及参数时加 `controls.has_parameter/parameter_effect_count/parameter_ids/parameter_names/parameter_bindings`;
24
+ - 筛选器自身:`control.id/name/type`、`control.option_source.table_ids/binding_info`、`control.context.ids/binding_info`;
25
+ - 筛选树:`filter_conditions.root_table_id/node_count/path_node_count/max_depth/table_paths/tree_summary`,需要环路或共享校验时加 `cycle_path_count/cycle_paths`,动态字段问题加 `dynamic_field_count`;
26
+ - 其他计算上下文:只有判断涉及联动、参数或权限时补对应 observation 字段。
27
+
28
+ `/` 表示同一前缀下的多个字段。计数和深度是数值字段,`calculation_context.has_*` 是布尔字段,`fieldDataType` 按工具声明(如 `number`、`bool`)。节点多不代表过滤条件多,effect 数也不等于最终生效的筛选数。
29
+
30
+ ## 组件单独预览对照
31
+
32
+ 时间与查询预算只按[仪表板内外组件对照](../common/topics/baseline-comparison.md#仪表板内外组件对照),候选与成功判定按[组件计算对照怎么判断](topics/component-comparison.md#组件计算对照怎么判断)。先确认当前记录形态再构造过滤,不将跨入口对照限制在同 `reportId`。
33
+
34
+ | 当前材料 | 查询选择 | 需要拿回的记录 |
35
+ |---|---|---|
36
+ | 已有单独预览 trace | 直接复用其时间、业务服务和入口 | 请求身份、业务结果、task 与 Metric |
37
+ | 组件身份可在 span 属性中识别 | 同服务、组件 ID 与单独预览的入口 | `name/trace_id/span_id`、请求上下文、查询表、结果状态及耗时 |
38
+ | 图表编辑时未记录组件属性,首查为空 | 同窗口、服务与图表编辑入口,在 `body` 或已声明的请求属性中精确匹配组件 ID;必要时用查询表和用户/查询配置确认候选 | 从有限日志提取 `trace_id`、入口、请求中的组件/表和查询字段,再按 trace 精确读取 |
39
+
40
+ 请求 JSON 中的 `tableBean.id`、`componentId` 等不是天然可查询的顶层字段。已有日志响应中恢复这些键即可,不猜 `widgetId` attribute;数据表 ID 命中不能直接认定同组件。返回 `result.status`、任务终态或明确业务响应确认成功,不使用 HTTP 状态码代替。
41
+
42
+ ## 筛选器名称与动态字段
43
+
44
+ 先复用当前 trace 的属性和请求材料;名称尚缺而已有字段 ID 时,按[名称关联规则](topics/name-binding.md#名称与请求上下文的关联取证)搜索已有筛选器关系请求。下面是日志正文查询意图,不是新增业务调用:
45
+
46
+ ```text
47
+ service.name = '<业务服务>'
48
+ AND body CONTAINS '/v1/conf/widget/relations'
49
+ AND body CONTAINS '<精确字段ID>'
50
+ ```
51
+
52
+ 在已确认的元数据窗口只取有限 `timestamp/body/trace_id/span_id`;如已给关系请求 trace,直接按该 trace 查,不再做正文发现。命中后从保存结果中提取 `controls[].fieldPosition` 的身份与名称,并核对 `widgets` 包含目标组件。多个字段尽量合并在同次查询;正文或请求属性中没有关联线索时保留缺口,不盲扫所有服务、所有字段或循环试探关键词。
53
+
54
+ 动态字段选项值、默认值和名称是不同信息。关系请求上报的 `name` 只补名称,`controls.names` 也可能只是筛选器键;不得由二者推断选择值。确认覆盖需要哪些记录、什么时候停止补查,以及 `type=73`、`unbound`、普通参数统计和正数才写入的计数字段,统一按[动态字段覆盖与上游展开](topics/dynamic-fields.md#动态字段覆盖与上游展开)处理。
55
+
56
+ ## 资源发现与影响范围
57
+
58
+ | 当前缺口 | 查询范围与条件 | 如何继续 |
59
+ |---|---|---|
60
+ | 只有 report/dashboard | 已确认时间、服务与 report,有限候选业务入口 | 按操作选 trace,补该 trace 的业务记录 |
61
+ | 只有 component/widget | 已确认时间、服务、组件 observation | 核对资产 ID 与画布实例,不能自动互换 |
62
+ | 某筛选器影响哪些请求 | 短交互窗、service、report、`controls.ids` 和组件 observation | 提取有关 traceId,再读取各 trace 的筛选树 |
63
+ | 精确筛选器条件为空,或仍缺同窗影响范围/对照 | 同 report 同服务同短窗降级一次 | 不同时扩大时间和移除服务,不要求筛选树 span 自带筛选器字段 |
64
+
65
+ 只有同 report、同组件、同查询表、在可靠短交互窗里、不带目标筛选器的请求才有较强的对照价值;查询指纹没核对时,参数、排序、聚合或数据范围的差异不能靠时间和身份匹配消掉。不默认拿最短的无筛选器请求和最长的有筛选器请求做原因对照。
66
+
67
+ ## 筛选树
68
+
69
+ 需要树结构时,按上方字段清单取得当前组件或操作的完整路径与 summary,不要求筛选树 span 自带筛选器字段。还原、校验、名称补齐和展示统一按[筛选树还原与交付](topics/filter-tree.md#筛选树还原与交付)执行;沿用本次请求父子范围,不再为展示重复取证。
@@ -0,0 +1,76 @@
1
+ # 仪表板 · 入口与信号
2
+
3
+ 回答“怎样认出入口,各个 span、attribute、日志和字段是什么意思”。
4
+
5
+ ## 场景识别
6
+
7
+ 已确认的入口和直接信号包括:
8
+
9
+ - `POST /v1/design/control/data`:仪表板筛选器候选值取数;
10
+ - `data.endpoint=design_control_data`;
11
+ - `data.request_context=dashboard`;
12
+ - `sense=dashboard-controlData`。
13
+
14
+ 筛选器候选值请求的 span 结构:
15
+
16
+ ```text
17
+ POST /v1/design/control/data
18
+ └─ dashboard.controlData
19
+ ├─ data.control.validateSourceTables 先校验来源表是否被标红
20
+ └─ data.control.calculateOptions 候选值计算
21
+ ├─ FilterConditionsBuilder.build 把其他筛选器带来的条件构建成筛选条件树
22
+ └─ data.control.engineExecute 引擎查询:QueryExecutor → execute
23
+ ```
24
+
25
+ 时间主要花在 `data.control.engineExecute`(引擎),它之前是准备输入表和筛选条件;进入引擎后按[引擎知识](../engine/README.md)解读。仪表板内组件计算的阶段 span 见[组件 · 组件计算的阶段](../component/signals.md#组件计算的阶段),结果状态和失败类名见[取数结果与失败](../component/signals.md#取数结果与失败)。route 在 SigNoZ 里带部署上下文路径,见[识别方法](../common/signals.md#识别方法)。
26
+
27
+ 共享的 `POST /v2/external/widget/data` 按[仪表板组件预览的来源判定](../common/signals.md#仪表板组件预览入口)识别。确认属于仪表板后,组件计算全部由本场景调查。
28
+
29
+ ## 信号含义
30
+
31
+ - `reportId`、`reportName`:仪表板或报表资源锚点;
32
+ - `control.id`、`control.type`、筛选器上下文 attribute:标识本次候选值或筛选请求;
33
+ - `control.option_source.table_ids`:候选值可能读取的表,可用于发现分析表关联;
34
+ - `component.id`:仪表板内组件锚点,用于在仪表板模块内定位具体组件计算。
35
+
36
+ 仪表板内组件计算的 `previewComponent` 上,下面几个属性用来看这次请求带入了多少上下文:
37
+
38
+ | 属性 | 含义 |
39
+ |---|---|
40
+ | `controls.effect_count`、`controls.valued_effect_count` | 本次请求带入的筛选器影响数,以及其中有取值的个数 |
41
+ | `calculation_context.has_auto_linkage`、`has_custom_linkage`、`has_permission_context` | 是否带入自动联动、组件间自定义联动、数据权限 |
42
+ | `component.linkage.depth` | 联动的层数 |
43
+ | `component.query_count` | 这个组件一次请求里的查询个数 |
44
+
45
+ 筛选器数多不等于慢,要结合筛选树和引擎耗时判断。`controls.*`、`filter_conditions.*` 的完整字段和读法见[查询方法](queries.md)与[筛选树](topics/filter-tree.md)。
46
+
47
+ ### 筛选器候选值请求的属性
48
+
49
+ `POST /v1/design/control/data` 的文本筛选器候选值请求,会在 span 上记录下面这些属性。
50
+
51
+ | 属性 | 含义 |
52
+ |---|---|
53
+ | `control.query.mode` | 本次取候选值的方式:`page` 翻页(默认)、`keyword_search` 带关键字搜索、`select_all` 全选、`search_select_all` 搜索后全选 |
54
+ | `control.query.unbounded` | 取数有没有上限;全选(`select_all`)没有上限 |
55
+ | `control.query.fetch_limit` | 有上限时的取数上限;没有上限时不写 |
56
+ | `control.query.output_rows` | 引擎实际返回的行数(含已选值);等于 `fetch_limit` 时,候选值可能被上限截断 |
57
+ | `control.option_source.distinct_count`、`used_count`、`truncated` | 候选值来源去重后的个数、实际使用的个数;`truncated=true` 表示来源个数超过了使用上限,只读了其中一部分 |
58
+ | `control.options.page`、`pageSize`、`keywords.size`、`selectedValues.size` | 请求的页码、页大小、关键字个数、已选值个数 |
59
+ | `control.result.candidate_size` | 去掉已选值之后的候选总数(翻页之前) |
60
+ | `control.result.row_size`、`value_size`、`has_next` | 本页返回的行数、值个数,以及是否还有下一页 |
61
+ | `control.result.empty`、`option_count` | 结果是否为空,以及返回的选项数(只针对文本筛选器) |
62
+ | `control.context.*` | 本次请求带上的其他筛选器的筛选上下文,例如 `input_count` 个数、`ids` / `names`、`value_present_count`、`has_parameter`、`has_control_linkage` |
63
+
64
+ 读法:候选值慢时,先看 `control.query.mode` 和 `control.query.unbounded`(全选没有取数上限,最容易慢),再看 `control.option_source.truncated` 和 `distinct_count`(来源很多时会被截断),最后看 `control.query.output_rows` 与 `candidate_size` 判断返回量。
65
+
66
+ ### 怎么读这些属性
67
+
68
+ 除了入口 attribute,请求内容里的筛选树和计算上下文也能用。按请求类型读:
69
+
70
+ - 筛选器候选值请求只受其他筛选器的影响;组件请求的影响因素不限于筛选器,查询、绑定表、`control`、参数、权限、`linkage` 都要保留。
71
+ - `linkage` 是自动联动(`has_auto_linkage` 可作入口信号)。组件间自定义联动从 `control` 里的 `ComponentControl` 认:`type=81` 稳定对应 `ComponentControl`,但是否跨源要比较组件绑定表、`value.tableId`、`filterCols.field/source` 和生成的过滤条件,不能单独证明跨源。仪表板 2.0 不再产生 `valueLinkageMap`,而 `has_custom_linkage` 仍依据它,所以都不能用来判断自定义联动。
72
+ - `controls.binding_info` 形如 `名称(id){type=N}->[analysis_table:tableId.fieldId]`,也可能是 `advanced_component:`、`parameter:` 或 `unbound`(旧版没有类型前缀);它和 raw binding 只是摘要,完整关系以筛选树和请求内容为准,组件目标不能按 ID 巧合挂到分析表节点。表名、字段名要从同一仪表板的只读配置或资源元数据补,不从 ID 推断。
73
+ - `controls.effect_count` 是这次请求 control Map 的条目数,不是画布上的筛选器数(一个筛选器可能产生多个 effect);`controls.input_count` 是旧字段。两者都没有时记为未知,不能按 0 当“无筛选器”基线;ID 按完整值匹配,不用前缀。
74
+ - `component.linkage.depth`、`control_context_count`、`source_component_ids`、`edges` 描述计算拓扑,是摘要,替代不了画布的完整实例配置。部署较早或版本未知时,字段缺失不能反证没有筛选器、联动或深层路径(见[知识适用性](../common/conclusions.md#知识适用性))。
75
+
76
+ 用这些还原业务计算:组件查询字段和计算类型、表关系路径、最终筛选树、筛选器、参数、权限、联动,说明这次算了什么、有多复杂。来源判定替代不了筛选树、组件集合和可靠时间边界组成的交互记录。业务解释通了,选定的慢或失败引擎执行也照样按[引擎知识](../engine/workflow.md)看 Metric。
@@ -0,0 +1,9 @@
1
+ # 组件计算对照怎么判断
2
+
3
+ 仪表板内组件可以正常直接读取分析表已有结果,也可能因附加条件展开上游计算;单独预览使用同一查询表,不代表两侧算了同样的内容。调查顺序见[组件取数先做对照](../workflow.md#组件取数先做对照),本节只规定可比性。
4
+
5
+ - 图表编辑时的预览可见 `POST /v2/design/widget/data`、`editComponent`;仪表板以外的图表预览(同样走仪表板组件预览入口)须按[来源判定](../../common/signals.md#仪表板组件预览入口)确认。`/v2/query/data` 只是通用查询,必须核对请求和组件关联。仪表板内的另一次成功请求仍是仪表板请求。
6
+ - 图表编辑时不保证有仪表板组件预览入口的 `component.id`、`component.query.table_id` 和请求上下文属性。可以从请求日志恢复组件和 `tableBean.id`、查询字段及操作,再关联其 trace/task;不能过滤这些缺失属性后把零结果当成“没有单独预览”。
7
+ - 有相同组件 ID 时仍需核对查询表、字段、聚合、排序、分页、配置版本和数据版本。ID 未记录时,同用户、同查询表与完整查询配置可作为对应组件的候选依据;同表、同用户或时间接近单独不足以确认身份。差异本身可作为调查对象,字段不全时标为相关对照,不强称严格等价。
8
+ - 成功须有业务结果或任务最终完成的记录,例如 `result.status=success/empty`、明确成功响应或同 task 的 `FINISHED`,并核对是否真实执行。HTTP 200、耗时短、没有 ERROR 不足以证明成功;`updating`、取消、失败重试或返回旧结果也不能当成已完成同样计算。正常空结果可保留,但不能冒充同数据范围的非空结果。
9
+ - 对照重点包括请求额外条件及实际计划:直接扫描目标表,还是展开来源表、关联、聚合和中间缓存。分别报告两侧输入、输出和失败边界,不将成功返回的汇总行与失败处理中间明细行直接计算放大倍数;Metric 比较口径沿用引擎知识。
@@ -0,0 +1,21 @@
1
+ # 动态字段覆盖与上游展开
2
+
3
+ 动态字段是一种可选择替代计算字段的业务配置,不等于任意运行时表达式,也不能从“日期”一词猜它的名称。仪表板 2.0 取数路径中,`control.type=73` 是动态字段下拉筛选器。绑定使用动态字段位置,包含 `id`、`name`、`operatorId`、`tableId`,组件分支还可带 `widgetId`;请求材料中的位置对象可称 `dynamicField`,筛选器关系请求中称 `fieldPosition`。
4
+
5
+ 有值且能匹配到有效动态字段配置时,所选计算字段与默认计算字段不同会产生动态字段覆盖;相同选择不产生该项覆盖。覆盖或参数作用于上游表时,下游可能不能直接读取原来已经保存的计算结果,而需沿依赖展开上游计算。普通字段过滤、联动及其他执行条件也可能改变计划,不能仅凭“仪表板入口”或一个筛选器存在就确定重算原因。
6
+
7
+ 核对时区分三层事实:
8
+
9
+ | 记录 | 能确认什么 | 还需核对什么 |
10
+ |---|---|---|
11
+ | `controls.ids`、`controls.effect_type_counts`、有值计数 | 请求带入了哪类筛选器项 | 最终是否生成覆盖;需要定位时核对绑定与树中位置 |
12
+ | `filter_conditions.dynamic_field_count>0`、节点 `dynamic=N` 且 `N>0` | 最终条件树包含动态字段覆盖;节点摘要还可定位所在表路径 | 实际计划是否展开上游,以及对应计算和资源压力 |
13
+ | 对应执行计划展开来源表,并有任务与 Metric | 本次实际发生了哪些上游计算及资源压力 | 结合覆盖、筛选和其他条件区分触发因素 |
14
+
15
+ 性能诊断中,动态字段这一项默认取证到“是否存在覆盖”,无需具体选择值和默认计算字段。当前执行的最终条件树已有上述正数记录时,直接确认覆盖,继续沿实际计划和 Metric 分析上游计算、中间结果及资源压力;不为再次证明覆盖而补查这两个值,也不因缺少它们列出诊断缺口、阻塞交付或建议新增服务端埋点。只有用户明确询问具体替换内容或选项语义时,才定向补取这些值;没有取得就保持未知。覆盖存在不等于它导致了全部额外计算或内存超限,因果判断仍需同次执行的计算路径和资源记录。原因分析的展开程度及排查方向按[诊断结果交付](../../../docs/diagnostic-report.md)处理。
16
+
17
+ `controls.ids` 中的 `parameter:<id>` 可能只是请求 Map 的键,不能据前缀认定普通参数。`controls.has_parameter`、`controls.parameter_*` 只统计普通参数筛选器,不覆盖动态字段筛选器;它们为 false/零不能排除动态字段影响。`controls.binding_info` 的 `unbound` 也可能只是普通字段绑定摘要为空,不能反证动态字段没有绑定或生效。筛选器名称缺失时,名称摘要可能退回到这个键。
18
+
19
+ `filter_conditions.*_count` 的部分字段只在正数时写入;工具投影的零或 false 可能是缺字段默认值。优先用完整 `tree_summary` 中明确的五类计数核对零值,不由投影零值构造“无条件”对照。`dynamic_field_count` 为 0、`tree_summary` 也为空时,对用户说“这次没看到动态字段覆盖”就够了,不用列成缺口。计数摘要没有选项值和字段名,不意味着请求或关联日志也没有。
20
+
21
+ 不能把本地行为直接当成目标环境已部署事实;版本未知时保留依赖版本的判断。线上已有计数和计划可以直接说明观测事实,无需使用者准备产品代码。