@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,60 @@
1
+ # 诊断案例库
2
+
3
+ 收录经过核实的诊断案例:现象、区分过哪些候选原因、最后的原因和处理,以及适用限制。案例只用于**提出和排序假设**,不是系统事实,也不能代替本次记录确认根因;这与各域 `workflow.md` 中“常见现象与候选假设”只排序假设的定位一致。
4
+
5
+ ## 目录
6
+
7
+ - 什么时候读
8
+ - 收录门槛
9
+ - 条目格式
10
+ - 案例索引
11
+
12
+ ## 什么时候读
13
+
14
+ 提出候选原因前,按场景在下方索引里找相近现象。命中时把它当作一个候选方向:说明来自哪个案例、其状态和适用限制,再用这次的日志和 trace 验证,不直接套用结论。没有命中不影响正常排查。
15
+
16
+ ## 收录门槛
17
+
18
+ - 有依据:原因必须有支持它的记录,并写出被排除的候选和反证。只有猜测的原因不收录,留在反馈草稿里。
19
+ - 单个案例先记为 `observed`;被第二个独立案例,或研发复核证实后升为 `confirmed`。单次相似现象不足以形成通用原因。
20
+ - 已收录同类问题时更新原条目的依据和适用范围,不重复新建。
21
+ - 按脱敏要求写:不放 32 位十六进制 ID、`agp` 开头的标识、租户名、企业 ID、完整业务载荷或凭据。
22
+ - 持续被新案例推翻的条目改回 `observed` 或删除,不保留过期的结论。
23
+
24
+ 收录由维护者审核后合入,助手在诊断中不自动写入本目录;诊断后的草稿按[需求反馈](../../docs/diagnostic-feedback.md)提出。
25
+
26
+ ## 条目格式
27
+
28
+ 每个案例一个文件,文件名 `<场景>-<短名>.md`,场景取 `dataset`、`component`、`dashboard`、`update`、`engine`、`other`。
29
+
30
+ ```markdown
31
+ ---
32
+ scene: update
33
+ status: observed # observed | confirmed
34
+ recorded: 2026-11-07
35
+ ---
36
+
37
+ # 一句话标题(现象,不是结论)
38
+
39
+ ## 现象
40
+ 用户看到什么、在什么操作后、影响范围;只写可观察的事实。
41
+
42
+ ## 区分过的候选原因
43
+ | 候选 | 支持或反对它的记录 | 结论 |
44
+ |---|---|---|
45
+
46
+ ## 原因
47
+ 最终原因,以及它由哪些记录证明。
48
+
49
+ ## 处理与结果
50
+ 采取了什么、结果如何;没有处理则写明。
51
+
52
+ ## 适用与限制
53
+ 版本、环境、数据条件;哪些情形下这个案例不适用。
54
+ ```
55
+
56
+ ## 案例索引
57
+
58
+ | 场景 | 案例 | 状态 | 一句话 |
59
+ |---|---|---|---|
60
+ | 仪表板 | [仪表板图表报 polars query timeout,引擎优化器超时](dashboard-parameter-deep-binding.md) | confirmed | 只带日期参数、查询语句约 24 万字符:参数绑在很深的上游表,整条上游链被实时展开 |
@@ -0,0 +1,32 @@
1
+ ---
2
+ scene: dashboard
3
+ status: confirmed
4
+ recorded: 2026-11-07
5
+ ---
6
+
7
+ # 仪表板图表报 polars query timeout,引擎优化器超时
8
+
9
+ ## 现象
10
+
11
+ 仪表板里一个图表取数失败,页面报错。整个请求约 3.4 秒,HTTP 返回 200,但 span 标了错误。引擎 `query` span 上的报错是 `Task execution timeout after 2003 ms (limit: 2000 ms)`,往上被包装成 `QueryTimeOutException` / `polars query timeout`。
12
+
13
+ ## 区分过的候选原因
14
+
15
+ | 候选 | 支持或反对它的记录 | 结论 |
16
+ |---|---|---|
17
+ | 引擎资源不足或排队 | 引擎排队和计划生成都很快,失败在优化阶段的计时保护上,没有内存超限 | 排除 |
18
+ | 图表自身查询太重 | 组件本身只有一个查询;请求里除了参数没有别的条件 | 不是主因 |
19
+ | 筛选或动态字段扩大了计算 | `previewComponent` 上筛选树为空,动态字段计数为 0 | 排除 |
20
+ | 参数绑在很深的上游表,触发整条上游链实时展开 | 请求只带了两个日期参数(`controls.parameter_names`);日志 `dax parse too slow, dax length = 239934`,查询语句约 24 万字符;`begin get allParent` / `end get parent` 成对出现约 30 次 | 成立 |
21
+
22
+ ## 原因
23
+
24
+ 两个日期参数绑在离图表很远的上游父表上。参数值一变,上游已经存好的结果都用不了,只能把整条上游链一起实时展开,生成的查询语句膨胀到约 24 万字符,引擎优化器在 2 秒预算内处理不完而超时。引擎超时只是表象,原因在仪表板的参数绑定层级。研发已复核。
25
+
26
+ ## 处理与结果
27
+
28
+ 建议把参数绑定挪到靠近图表的表上,挪之前和用户确认业务口径。调大优化器超时预算只是让它多算一会儿,解决不了查询太大的问题,不作为首选。
29
+
30
+ ## 适用与限制
31
+
32
+ 适用于仪表板内组件取数报引擎超时或内存超限、请求只带参数、查询语句异常长的情况。参数具体绑在哪张表 trace 里看不到,要请用户在仪表板的参数设置里核对。查询语句长度要和同一组件平时或单独预览时比,不能只看绝对值。
@@ -0,0 +1,31 @@
1
+ # 通用知识
2
+
3
+ 跨场景共用的规则:性能排查入口、SigNoZ 环境、trace 场景路由、公共查询规则、知识适用性。
4
+
5
+ ## 槽位
6
+
7
+ 每个知识域都按同样的槽位组织。按要做的事选槽位,只读命中的章节。
8
+
9
+ | 要做什么 | 读 | 包含 |
10
+ |---|---|---|
11
+ | 性能问题从哪里入手 | [workflow.md](workflow.md) | 性能排查入口:选场景域的提示、易错点 |
12
+ | 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | SigNoZ 环境、URL 与后端 `service.name` 的映射和选择顺序 |
13
+ | 认出入口,看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 只有 trace 或场景不明时怎样识别入口场景;仪表板组件预览入口的来源判定 |
14
+ | 看完日志和 trace,能下什么结论 | [conclusions.md](conclusions.md) | 知识与本次记录的适用核对 |
15
+ | 写查询、选取证路径 | [queries.md](queries.md) | 公共查询规则的必读部分:默认值速查、工具调用、调查起点、查询约束 |
16
+
17
+ ## 展开明细
18
+
19
+ | 文件 | 何时读 | 内容 |
20
+ |---|---|---|
21
+ | [topics/query-example.md](topics/query-example.md) | 工具说明不可读、需要 Query Builder 原始结构时 | 原始查询结构例子 |
22
+ | [topics/start-and-anchors.md](topics/start-and-anchors.md) | 从现象、截图或转抄的 ID 开始,还没有可信的执行锚点时 | 锚点可信度;按现象决定先查什么 |
23
+ | [topics/linked-traces.md](topics/linked-traces.md) | 从原 trace 找后台独立执行 trace(`linked`),或反过来时 | 独立 trace 的显式链接 |
24
+ | [topics/query-budget.md](topics/query-budget.md) | 判断还能再查几次、已有结果能否复用时 | 查询预算与结果复用 |
25
+ | [topics/baseline-comparison.md](topics/baseline-comparison.md) | 用户表达“之前正常”“最近变慢”,或仪表板内组件异常需要单独预览对照时 | 主动对比与基线;仪表板内外组件对照 |
26
+ | [topics/large-results.md](topics/large-results.md) | 响应很大、需要落盘读取,或用户要求线上取样评测时 | 大结果、临时文件与取样 |
27
+ | [topics/setup-signoz-mcp.md](topics/setup-signoz-mcp.md) | 需要安装、配置或恢复 SigNoZ MCP,或实时查询因工具、连接、鉴权问题被阻断时 | 配置 SigNoZ MCP:流程、安装、客户端接入、恢复 |
28
+
29
+ ## 关联
30
+
31
+ - 相关知识域:[案例库](../cases/README.md):已核实案例,只用于提出假设
@@ -0,0 +1,49 @@
1
+ # 通用 · 概念与关联
2
+
3
+ 各域共用的 SigNoZ 环境和后端服务映射,用来确定这次查哪个环境、过滤哪个 `service.name`。这里不放 API Key,也不规定具体客户端怎么配置。按下表直接确认,不用跑脚本。
4
+
5
+ ## 环境映射
6
+
7
+ | 对用户名称 | 可识别别名 | SigNoZ URL | 推荐 MCP 名称 |
8
+ |---|---|---|---|
9
+ | 测试 | 测试、test | `https://signoz.jsydevelop.com` | `signoz_test` |
10
+ | 正式 | 正式、work | `https://signoz.work.jsydevelop.com` | `signoz_work` |
11
+
12
+ 对用户只有“测试环境”和“正式环境”两个选项。团队口头说的 `work 环境` 就是正式环境,问用户时也只说“正式环境”,不要多出一个“工作环境”。
13
+
14
+ `prod` 和 `production` 不是正式环境的别名。`prod` 在后端语境里是测试 SigNoZ 实例下的一个服务子环境;`production` 目前没有确认过的含义,不参与自动识别。
15
+
16
+ 有的客户端只连一个 SigNoZ MCP,靠工具的 `env` 参数切环境:正式环境传 `work`,测试环境按下面后端子环境的名字传;`env=prod` 查的是测试实例,不是正式环境。
17
+
18
+ 推荐 MCP 名称只是为了各客户端叫法一致。客户端已有别的稳定名称就保留,以连接信息里的 URL 为准;调用方式和参数以当前客户端实际提供的工具为准。已经确认的环境和本轮成功的查询直接复用,不因为工具前缀不同就重新安装或验证。
19
+
20
+ ## fx-data-server 后端子环境
21
+
22
+ SigNoZ 实例和后端 `service.name` 是两层信息。查后端请求时两者都要定下来,并把 `service.name` 放进查询过滤。
23
+
24
+ | 用户或部署表达 | SigNoZ 实例 | 后端 `service.name` |
25
+ |---|---|---|
26
+ | `test` | 测试 | `hihidata-jsy-test` |
27
+ | `dev` | 测试 | `hihidata-jsy-dev` |
28
+ | `prod` | 测试 | `hihidata-jsy-prod` |
29
+ | `perftest` | 测试 | `hihidata-jsy-perftest` |
30
+ | `work` / `default` | 正式 | `hihidata-jsy-default` |
31
+
32
+ 例如“`work` 环境”连正式 URL、过滤 `service.name=hihidata-jsy-default`;“`prod` 环境”连测试 URL、过滤 `service.name=hihidata-jsy-prod`。几个子环境共用一个实例,连上以后仍要按服务过滤。不要凭 `service.environment=prod` 选实例,这个字段两个实例里都可能出现,后端样本也可能不填。
33
+
34
+ ## 选择顺序
35
+
36
+ 1. 用户给了 SigNoZ URL 或链接,以它为准。URL 和口头说的环境对不上时,查询前请用户确认是“测试环境”还是“正式环境”。
37
+ 2. 没有 URL,就用用户明确说的环境。
38
+ 3. 这次调查已经确认过环境,直接沿用,用户后面没再提也不切换。
39
+ 4. 新调查什么都没说,默认使用 work(正式环境),后端查询同时用正式环境的服务过滤。不再让用户选,也不去多个环境里探测。
40
+ 5. 从现有 MCP 连接信息核对目标 URL。已有本轮成功查询就不再额外验证。默认的 work 连不上就去恢复这个连接,不改用测试环境。用户给的名称或 URL 认不出来、或者互相矛盾时,只处理这一处歧义,不拿默认值盖过去。
41
+
42
+ ## 使用边界
43
+
44
+ - 只有用户明确要求跨环境核对某个精确 ID 时,才去多个环境查;平时默认 work,不跨环境扫描。
45
+ - 缺时间时不顺带让用户选环境。时间等入口默认值见[公共查询规则](queries.md)的“默认值速查”。
46
+ - 环境一旦确认,这次诊断的 trace、日志和 metric 都只查这个环境,不混用别的环境的数据。
47
+ - `service.environment` 这类 attribute 只能在当前实例里过滤,代替不了选实例。
48
+ - MCP 能读某个环境的 SigNoZ,不代表业务页面链接也有同样的权限。
49
+ - 测试和正式环境的 API Key 分开维护,不能混用或互相覆盖。
@@ -1,10 +1,14 @@
1
- # 怎样使用本指南中的知识
1
+ # 通用 · 能下什么结论
2
2
 
3
- 指南中的业务关系和字段说明用于解释实际记录,不能代替本次问题的证据。排查从手上已有材料开始,不要求取得产品代码。
3
+ 回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么,结论能下到哪一步”。
4
4
 
5
- 同一调查已经读过且适用范围未变化的知识直接复用。操作、版本、配置、字段或来源发生变化时,只重新核对受影响的部分;新的执行仍需自己的运行证据。更新 analyzer 的知识适用性、身份和关联核对继续按其契约执行,不能用“已读过”代替本次证据核对。
5
+ ## 知识适用性
6
6
 
7
- ## 核对适用条件
7
+ 指南中的业务关系和字段说明用于解释实际记录,不能代替这次问题的日志和 trace。排查从手上已有材料开始,不要求取得产品代码。
8
+
9
+ 同一调查已经读过且适用范围未变化的知识直接复用。操作、版本、配置、字段或来源发生变化时,只重新核对受影响的部分;新的执行仍要看它自己的运行记录。更新域的知识适用性、身份和关联核对继续按[更新 · 能下什么结论](../update/conclusions.md)执行,不能用“已读过”代替对这次记录的核对。
10
+
11
+ ### 核对适用条件
8
12
 
9
13
  1. 先确认实际操作。接口版本号或通用计算记录不能单独说明业务场景。
10
14
  2. 核对页面、请求和日志中实际出现的字段及含义。没有某个字段,不代表对应筛选、联动或处理过程不存在。
@@ -12,11 +16,11 @@
12
16
  4. 历史记录可以帮助理解当时发生的操作,但历史入口不应成为寻找当前问题的默认条件。
13
17
  5. 更新记录之间需要明确关联;无法关联的部分保留未知。已经明确属于某次引擎任务的统计仍可单独分析,但不能用它补造缺失的更新关系。
14
18
 
15
- ## 出现不一致时
19
+ ### 出现不一致时
16
20
 
17
21
  记录实际看到的字段、业务现象和与指南不同之处。说明哪些判断受影响,再选择补充对应执行记录、核对可取得的产品版本或交接研发;不要要求使用者查找提交号或产品实现。
18
22
 
19
- 本轮交付时,将有依据的差异按[诊断后的需求反馈](../../docs/diagnostic-feedback.md)反馈给使用者。区分适用范围内的已确认不一致与范围未知的待核实差异;空结果、字段缺失或截断不能单独证明文档错误。
23
+ 有依据的差异按[诊断后的需求反馈](../../docs/diagnostic-feedback.md)反馈,区分适用范围内的已确认不一致与范围未知的待核实差异;空结果、字段缺失或截断不能单独证明文档错误。
20
24
 
21
25
  知识校验用于确定结论的适用范围。信息不足时,向使用者说明哪一段还不能确认,无需让客户理解内部文件、校验格式或工具名称。
22
26
 
@@ -0,0 +1,98 @@
1
+ # 通用 · 查询方法
2
+
3
+ 查 SigNoZ 时,先用环境、时间、服务和业务 ID 把范围缩小,再读 trace 或日志。日志和 trace 同样是一手记录,查法见[查日志](#查日志)。要查之前先看“默认值速查”,其余章节用到再看。各场景的接口清单在各域 `queries.md`,MCP 安装见[配置 SigNoZ MCP](topics/setup-signoz-mcp.md)。
4
+
5
+ ## 目录
6
+
7
+ - [默认值速查](#默认值速查)
8
+ - [选择和调用工具](#选择和调用工具)
9
+ - [调查起点](#调查起点)
10
+ - [查询约束](#查询约束)
11
+ - [查日志](#查日志)
12
+ - [按需展开](#按需展开)
13
+
14
+ ## 默认值速查
15
+
16
+ | 情况 | 默认处理 |
17
+ |---|---|
18
+ | 未指定环境 | 默认 work(正式环境),显式环境、URL 和已确认范围优先;映射见[环境选择规则](concepts.md)。SigNoZ 工具带 `env` 参数时,正式环境传 `work`;`prod` 是测试实例下的子环境,不是正式环境 |
19
+ | 普通对象(tableId、widgetId、reportId 等)没有时间 | 完全缺少时间时合并询问一次时间,不同时要求选择环境,不要默认最近 7 天 |
20
+ | 企业更新没有时间或只说“最近” | 企业更新无时间默认最近 24 小时,告知后直接查询,优先核对异常 |
21
+ | 只有 dagId | dagId 不先追问时间,由助手管理检索窗口,命中后按实际记录恢复链范围 |
22
+ | 用户说“之前没超限”“以前正常”“最近变慢” | 已经是历史对比目标;先定位目标执行,再主动查找目标执行前 24 小时的可比基线 |
23
+ | 只有单次失败 | 单次失败诊断不要求发现或补充成功执行 |
24
+ | 仪表板内组件计算异常 | 优先有界查找组件单独预览记录;未找到仍继续分析本次异常,见[仪表板内外组件对照](topics/baseline-comparison.md#仪表板内外组件对照) |
25
+
26
+ ## 选择和调用工具
27
+
28
+ - 先列出已连接 SigNoZ 的工具名,只读这次要用的那个工具的说明;读过一次就复用,不要把全部工具说明都输出一遍。调用方式以客户端实际的工具声明为准,按[环境选择规则](concepts.md)核对目标 URL,工具前缀和推荐名称不一样不用重配。
29
+ - **已有 traceId 时**,便捷的 span 搜索和详情工具只返回 span 名、耗时、错误这些基本列,不带 `taskName`、`metric`、`data.request_context` 这类自定义 attribute。按这个顺序取:
30
+ 1. 日志按 `trace_id` 查一次,常常就能拿到报错原文、引擎任务 ID 和请求结束时间,比翻 trace 便宜。
31
+ 2. span 搜索按 `trace_id` 加 `has_error = true`、span 名或 `duration_nano` 取关键的几条 span,看时间线和错误。
32
+ 3. 要业务 attribute 时,用 Query Builder(如 `signoz_execute_builder_query`)按 `trace_id` 加 span 名过滤,在 `selectFields` 里点名要的 attribute,写法见[原始查询例子](topics/query-example.md)。
33
+ 4. 详情工具一次最多 1000 行,线上常有几十万到上百万字符,只在要看父子结构时用,输出存临时文件再用 shell 按需读(客户端自动落盘的文件常是 `[{type, text}]`,真正的 JSON 在 `text` 里,先取出来再解析);超过 1000 行时用 span 搜索按 `trace_id` 加 offset 翻页。这和工具自带说明的建议不同,以这里为准。
34
+ - 工具参数和查询字段名不一样:详情工具的参数是 `traceId`,查询表达式里写 `trace_id`。收到字段错误时只改报错的那个字段。
35
+ - 客户端读不到 Query Builder 的说明资源时,直接照[原始查询例子](topics/query-example.md)写,不要反复枚举资源或猜结构;说明读不到不等于 SigNoZ 查不了。
36
+ - 结果只把这次需要的字段和摘要放进上下文,大响应直接存临时文件,再用 shell 按需读。命中条数到了 limit,就算没有 nextCursor 也不能说已经查全;需要完整时,按同一个执行缩到必要的 span 或字段再核对。
37
+
38
+ 一条 trace 可能包含好几次工作区操作或好几个计算。已经有目标 span 和时间,就拿它们当条件;结果到了上限,先收到目标 span 及其父子范围,不重复取整条 trace,也不要拿整条 trace 里最慢的任务顶替目标。入口不属于已有场景时,保留入口名,用通用时间线和明确绑定的任务解释,不要硬归到分析表或仪表板。
39
+
40
+ ## 调查起点
41
+
42
+ | 已有输入 | 首次动作 |
43
+ |---|---|
44
+ | SigNoZ trace 链接 | 从 URL 确认环境和 traceId,精确读取 trace,再使用 trace 时间与 `service.name`。链接里没有时间时,工具的默认窗口(1~6 小时)常常查不到:先用 span 搜索按 `trace_id` 在 7 天内查 1 条拿到时间,或者直接用 SigNoZ 报错提示里给出的 trace 时间窗 |
45
+ | 精确 traceId 或执行 ID | 复用已确认环境;未指定时默认 work,精确查询并恢复执行时间 |
46
+ | tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间,使用场景入口、服务和资源 attribute 寻找候选执行 |
47
+ | 企业 ID(更新查询) | 复用已有时间;未提供时告知默认最近 24 小时后直接查询,先给更新概况并优先核对异常 |
48
+ | dagId | 按更新链标识精确发现提交与节点,不要求用户先补时间或 trace;检索时间见[更新发现指引](../update/topics/discover-executions.md#检索时间) |
49
+ | 截图或 OCR 提取的 ID | 先核对字符并确认锚点可信度;存在相似字符歧义时请用户确认或粘贴原始文本 |
50
+ | 只有现象 | 补充能够确定场景或资源、发生时间的最小信息;未指定环境默认 work,不直接发起宽查询 |
51
+
52
+ 资源 ID 可以关联多次前台查询和后台更新,不是一次执行的唯一标识,默认环境不改变这个区分。企业更新与 dagId 的检索窗口、降级和时间扩展只适用于更新发现,细则见[更新发现指引](../update/topics/discover-executions.md#检索时间)。
53
+
54
+ ## 查询约束
55
+
56
+ 从资源出发的第一次查询,尽量同时带上:
57
+
58
+ ```text
59
+ 已确认环境
60
+ + 明确时间范围
61
+ + service.name
62
+ + 场景入口或特征 span
63
+ + 资源 attribute / 精确业务 ID
64
+ ```
65
+
66
+ - **服务**:`service.name` 优先放进过滤。从精确 trace、[环境映射](concepts.md)或场景知识取得;定不下来时,只在已确认的环境和时间里收出少量候选,必要时问用户。业务服务名随部署环境变化,应以对应执行或已核对的环境信息为准,不要把 `default` 或某次测试的服务名当成所有环境的固定值。
67
+ - **时间**:用户给了具体时刻,第一次查该时刻前后各 15 分钟;给了时间段就用那个范围。用户直接给的 trace 链接或 traceId 是精确锚点,不受这条限制。已有时间边界直接复用;“最近 24 小时”这类范围在工具支持时直接用 `timeRange`。明确日期或历史基线使用绝对边界;工具要 Unix 毫秒时,用运行环境的日期函数一次处理,沿用上下文或客户端的时区。查询前核对日期、时区、单位及起止顺序,只有真有歧义才问用户。
68
+ - **时间戳格式**:返回的 `timestamp` 可能是带纳秒小数的 RFC3339 字符串,也可能是秒、毫秒、微秒或纳秒的数字,保留原值。拿来当查询边界时按实际格式和单位换算,不要把字符串直接当整数,也不要把纳秒当毫秒传。
69
+ - **范围冻结**:第一次查询开始后记下环境、时区和窗口;普通对象查询里,时间窗外的结果不能作为本次候选。选定执行后就固定它的范围,不拿更早或更晚的相邻执行替代。DAG 的默认发现窗口不限制已经由精确标识确认的同链记录,按更新发现指引恢复真实范围。目标执行和基线执行各有各的范围,不能拿目标的时间窗去查基线;要扩大某一侧,记下原因和新旧边界。
70
+ - **结果大小**:只选这次判断需要的字段,设有限的条数。`MemoryLimitExceeded` 这类高频关键字,在几天的窗口里全文搜索或按时间聚合,常常超时或超出大小限制;先用表 ID、任务 ID 这类精确值缩小,时间窗控制在出问题前后几小时。已有 traceId、taskId 这类精确锚点就精确过滤,不再从资源 ID 重新发现。
71
+ - **没命中时**:先核对时区、环境、服务和资源值。确认输入没错后,每次只扩大一个维度;不能同时跨环境、扩大时间并移除 `service.name`。
72
+
73
+ 企业或 dagId 入口先按更新发现指引找回关联执行,再在对应执行里核对失败信号,不要求企业属性和错误必须落在同一个 span 上。
74
+
75
+ ## 查日志
76
+
77
+ 报错原文、堆栈和业务过程(加载起止、结果提交、tag 保留等)常常只在日志里,span 上只有摘要,该查日志时别只看 trace。
78
+
79
+ - **两类来源**:业务服务(`hihidata-jsy-*`、`datasource-server` 等)的日志基本都带 `trace_id`、`span_id`,打日志的类名在 `scope_name`;引擎集群(`*-polars-cluster`)的日志不带 `trace_id`,类名在 `logger.name`,按 task 查,见[引擎查询](../engine/queries.md#metric-链接与任务日志)。
80
+ - **常用字段**:`body` 是正文,可能多行;`severity_text` 是 `ERROR`、`WARN`、`INFO` 等级别;带异常的日志另有 `exception.type`、`exception.message`、`exception.stacktrace`;还有 `thread.name`、`service.name`。
81
+ - **有 traceId**:日志直接按 `trace_id` 过滤,不加服务过滤,同一个请求的日志可能来自不同服务;只要错误时加 `severity_text IN ('ERROR', 'WARN')`。拿到的日志用 `span_id` 对回 span。
82
+ - **只有资源或执行 ID**:在已确认的环境、时间和 `service.name` 里用 `body CONTAINS '<ID>'`,能加各域给的日志 signature 就加上;拿到 `trace_id` 再按 trace 展开。
83
+ - **只有报错现象**:先在短时间窗里按 `exception.type` 或报错原文聚合计数,按 `scope_name`、`exception.type` 分组,看是普遍还是偶发,再取一两条原文。统计次数用聚合工具,不要翻页数行。很多 ERROR 日志的 `exception.type` 是空的,这时按 `scope_name` 加正文开头的固定文字归类,正文里的 ID 不算分类;要区分普遍还是个别,再按 `trace_id` 或正文里的对象 ID 数不同值。
84
+ - **补 trace_id**:便捷日志搜索没返回 `trace_id` 时,在同样的过滤条件和时间窗里跑一次 Query Builder,只补 `timestamp`、`body`、`trace_id`、`span_id`、`service.name` 这些关联字段;不要因此退成按 operation 或全服务去搜 trace。
85
+ - **控制大小**:`body CONTAINS` 是全文扫描,先用服务、时间和级别缩小;`exception.stacktrace` 很长,要用时在 Query Builder 里点名取,写法见[原始查询例子](topics/query-example.md)。
86
+ - **脱敏**:正文可能带 token、请求体或个人数据,引用时只取需要的片段并脱敏。
87
+
88
+ ## 按需展开
89
+
90
+ 下面这些情形才需要读对应的 topic,其余时候不用读:
91
+
92
+ | 遇到 | 读 |
93
+ |---|---|
94
+ | 从现象、截图或转抄的 ID 开始,还没有可信的执行锚点 | [从现象或截图开始](topics/start-and-anchors.md) |
95
+ | 后台独立 trace,要从原 trace 找到执行 trace(`linked`) | [独立 Trace 与 linked](topics/linked-traces.md) |
96
+ | 判断还能再查几次、已有结果能否复用 | [查询预算与结果复用](topics/query-budget.md) |
97
+ | 用户说“之前正常”“最近变慢”,或仪表板内组件异常需要单独预览对照 | [主动对比与基线](topics/baseline-comparison.md) |
98
+ | 响应很大、需要落盘读取,或用户要求线上取样评测 | [大结果、临时文件与取样](topics/large-results.md) |
@@ -0,0 +1,58 @@
1
+ # 通用 · 入口与信号
2
+
3
+ 只有 trace、执行链接,或者看不出是哪个场景时,用这里判断从哪个场景开始查。四个场景各自的 span 字典和后续排查在各域的 `signals.md` 和 `workflow.md` 里。
4
+
5
+ 这里定的只是调查起点,根因在哪还要再验证。给用户说清从哪个场景开始、凭什么判断、还可能牵涉哪些场景就行,不用套固定格式。
6
+
7
+ ## 先从 trace 里看什么
8
+
9
+ - 根 span 或入口 span,HTTP method 和 route;
10
+ - 关键 span 名,不只看最慢的那个;
11
+ - `data.request_context`、`data.endpoint`、`sense` 这类业务 attribute;
12
+ - `tableId`、`component.id`、`reportId`、`dagId` 这类资源或执行 ID;
13
+ - service、时间、耗时、错误,以及上下游关系。
14
+
15
+ ## 识别方法
16
+
17
+ 本知识库里的 route 都写成去掉部署上下文路径的形式(如 `POST /v2/design/widget/data`)。SigNoZ 里的 HTTP span 名和 `http.route` 带上下文路径,测试环境是 `/decision`(如 `POST /decision/v2/design/widget/data`),匹配时按实际环境的前缀处理,不要原样拿本库的写法去精确过滤。
18
+
19
+ 1. 接口或业务 attribute 已经对上某个场景,就去读那个场景的 `signals.md` 确认含义。
20
+ 2. 接口没收录时,拿 trace 里实际出现的 span 名、attribute 名和值去各场景的 `signals.md` 里搜,只读命中的文件。认场景这一步不展开更新取证。
21
+ 3. 优先用能说明业务入口的信号组合。资源 ID 和上下游关系可以补强,但一般不能单独决定场景。
22
+ 4. 碰到仪表板组件预览入口,先按下面的[仪表板组件预览入口](#仪表板组件预览入口)判断来源,不能只凭最外层 HTTP span 或共享的 span 名选场景。
23
+ 5. 同时像好几个场景时,从入口信号最强的那个开始,其他的留着;起点不等于根因所在。
24
+ 6. 只有通用 Query 或 engine span 时,场景就记为未知。可以接着分析引擎层的事实,但不要据此猜业务入口。
25
+
26
+ ## 仪表板组件预览入口
27
+
28
+ `POST /v2/external/widget/data`(代码里叫外部组件取数)实际场景就是仪表板里的组件预览,线上绝大多数请求来自仪表板;仪表板以外的图表预览也走这个接口,但只占少数。沿同一入口父子链找带 `DataRequestObservation` 属性的 span,可能是 `previewComponent`,也可能是别的子 span;最外层 HTTP span 的 `reportId` 可能是空的。
29
+
30
+ - 任一对应 span 的 `data.request_context=dashboard` 或 `reportId` 非空,就是仪表板内组件计算,完全归仪表板场景,不先经过组件专项分流。
31
+ - 确认这条链上这些信号都是空的,才按仪表板以外的图表预览查。属性还没拿到时记为未知,不能当成空值。
32
+ - `previewComponent` 只是共享入口的 span 名,决定不了场景。离开这条取数链的 `reportId` 只能当关联线索;接口和 attribute 说法不一致时,两边都留着,不要悄悄选一个。
33
+
34
+ 这套规则只定调查入口。单个组件 trace 或仪表板来源标识,都证明不了已经覆盖整次仪表板交互。
35
+
36
+ ## 各场景的信号
37
+
38
+ | 场景 | 读 |
39
+ |---|---|
40
+ | 分析表 | [dataset/signals.md](../dataset/signals.md) |
41
+ | 组件 | [component/signals.md](../component/signals.md) |
42
+ | 仪表板 | [dashboard/signals.md](../dashboard/signals.md) |
43
+ | 更新 | [update/signals.md](../update/signals.md) |
44
+
45
+ 认出是更新以后:要查慢或失败,进[更新性能排查](../update/workflow.md#更新性能排查);要弄清更新来源、DAG、计数,或解释已有的运行记录,进[解释更新记录](../update/workflow.md#解释更新记录)。
46
+
47
+ ## 哪些信号靠得住
48
+
49
+ - 已确认的业务接口、明确的请求上下文,或者场景特有的入口 span 加业务 attribute,可以直接用来选起点。
50
+ - `tableId` 这类共享资源字段,以及离开组件取数链的 `reportId`,主要用来关联上下游,不能单独定场景。
51
+ - 最慢 span 只说明耗时在哪,说明不了是哪个场景。
52
+ - 请求成没成功看 span 的 `has_error` 和 `status_message`,不看 HTTP 状态码:前台接口常常返回 200,错误写在 `status_message` 里。
53
+ - 没有靠得住的命中,就记为未知,只补一项最能区分的入口、上下文或资源信息。
54
+ - 以这次实际的入口和字段为准。历史入口只能解释历史操作,字段缺失不能证明对应行为不存在(见[知识适用性](conclusions.md#知识适用性))。
55
+
56
+ ## 长 trace 与其他入口
57
+
58
+ 同一个 trace 里可能有好几次工作区操作。已经给了执行 span 和时间,就只沿它的父子范围认入口,不要把整个 trace 里最慢的任务当成用户要查的。入口是工作区详情这类没有专项知识的操作时,保留它本来的入口名,按通用时间线和明确关联的引擎任务解释;共用了计算,不代表它就变成了分析表预览。
@@ -0,0 +1,23 @@
1
+ # 主动对比与基线
2
+
3
+ 用户表达“之前正常”“最近变慢”,或仪表板内组件异常需要单独预览对照时读。与[查询方法](../queries.md)配套。
4
+
5
+ ## 主动对比
6
+
7
+ 先定位目标执行,再在同环境、对象和执行类型下发现正常基线;仪表板与组件单独预览的跨入口对照按下节处理。用户已给正常时间或成功执行时直接复用;只表达“之前正常”时,以目标执行开始时间为右边界,查询此前 24 小时的半开窗口,不用当前时钟或目标发现窗口的起点代替。时间参数按[查询约束](../queries.md#查询约束)处理,两侧边界分别保留。
8
+
9
+ 基线发现同样遵守“精确首查 + 同范围一次降级”,只取有限候选及判断可比性所需字段。按时间由近到远检查同对象、操作、参数和数据范围的成功执行;有明确成功结果且可比时选择最近一条并记录依据,不能仅凭耗时短或没有 ERROR 认定成功。成功节点也不自动代表整条更新链成功。影响可比性的字段缺失或多个不同操作仍可信时,展示差异再作最小消歧;已经明确的数据范围变化可以作为待解释差异,不要求两侧数值完全相同。
10
+
11
+ 分别维护 `目标执行` 和 `基线执行`:各自记录环境、trace/focused span、时间、业务及 engine 服务、task、Metric 与覆盖范围;时间窗只在本侧冻结,不跨侧复用。切换已选执行必须说明原因和记录上的差异,不能用相邻失败或另一侧产物静默替代。
12
+
13
+ 选定后主动取两侧 Trace、task 和 Metric;已有产物复用,每侧范围独立冻结。不得停在“建议再取 Metric”或等待用户说“你帮我取”。对照未找到、不可比或无法取得时,交付本次事实与已查询范围,并请求更早正常时间或最小缺失项,不自动扩大到七天。用户没有相对变化目标时仍按单次诊断推进。
14
+
15
+ ### 仪表板内外组件对照
16
+
17
+ 这是仪表板组件异常的默认浅查,不要求用户先提出对比,也不扩大为整张仪表板或企业扫描。先从目标 trace 恢复组件、查询表、时间与业务服务。已有单独预览材料优先复用;没有时间的对照查找,以目标执行开始前 24 小时的半开窗口为限。用户给出更明确的单独预览时间或 trace 时按该侧记录恢复范围,不套用失败侧时间。
18
+
19
+ 首次在同环境、同业务服务和该窗口内按组件身份及单独预览入口取有限候选,按时间由近到远核对。单独预览入口是图表编辑的 `editComponent`,或 `previewComponent` 上 `data.request_context` 不是 `dashboard`、`reportId` 为空的请求;`data.request_context=dashboard` 的都是仪表板里的请求,不能当对照。图表编辑时可能不记录 `component.id` 和 `data.request_context`;首查未命中时,在同窗口与服务内只降级一次,改查图表编辑时请求日志中的精确组件 ID,或已确认查询表加请求用户、查询字段等识别信息,不要求 `reportId` 同时命中。查询表只能发现候选,身份与可比性按[组件计算对照怎么判断](../../dashboard/topics/component-comparison.md#组件计算对照怎么判断)核对;不能因同表就认定为同组件。
20
+
21
+ 候选达到 limit 时,不宣称已覆盖所有记录;能唯一核实最近可比执行时选定并冻结,否则保留覆盖缺口。不继续扩大时间、移除服务或换表试探。未找到或不可比就继续目标失败分析,按场景流程提示用户检查单独预览结果。找到可比成功执行时主动取得两侧执行统计,各侧 engine 服务分别确认,不能把失败侧 engine 服务过滤直接套到成功侧。
22
+
23
+ 筛选器名称与绑定关系是另一项精确元数据取证,不是上述正常执行发现的重复查询。需要跨 trace 查筛选器关系时,默认复用同一前置窗口、业务服务和精确字段/组件标识;有明确关联请求时间或 trace 时直接精确读取。关联规则见[名称与请求上下文的关联取证](../../dashboard/topics/name-binding.md#名称与请求上下文的关联取证),不得仅凭“附近”不断扩大范围。
@@ -0,0 +1,12 @@
1
+ # 大结果、临时文件与取样
2
+
3
+ 响应很大、需要落盘读取,或用户要求线上取样评测时读。与[查询方法](../queries.md)配套。
4
+
5
+ ## 大结果与临时文件
6
+
7
+ - 大响应保存到系统临时文件,读取、摘要和引用都从这份文件出发;不要为同一内容重复查询线上正文。保存失败时复用内存中的响应重试,不重新查询。
8
+ - 临时摘要按白名单取字段,只展示操作、执行标识、时间、状态、错误签名及当前判断所需的明确数值。不要直接打印 `body` 首行、任意正文前缀或整份 Job 字段映射;其中可能包含租户、用户、描述和完整载荷。Metric 的读法见[读取大正文](../../engine/queries.md#读取大正文)。
9
+
10
+ Trace、业务属性和 Metric 的临时原文在同一调查中保留并复用;首次交付或切换场景不立即删除。调查结束后按客户端临时目录策略清理,不把原始大响应写入工作区。
11
+
12
+ 用户明确要求从线上选取样本评测时,可以在获准环境和服务内自行设定有限的取样时间窗、耗时阈值和结果数,并说明选择依据。样本选定后转为对应执行的精确调查;取样范围不作为每个案例后续查询的默认范围。
@@ -0,0 +1,11 @@
1
+ # 独立 Trace 与 linked
2
+
3
+ 从原 trace 找后台独立执行 trace,或反过来时读。与[查询方法](../queries.md)配套。
4
+
5
+ ## 独立 Trace 的显式链接
6
+
7
+ 部分后台执行会创建没有父 span 的新 trace,同时用 span link 指向进入该执行前的 span;新执行上的 `linked` attribute 保存被链接的原 trace ID。查询方向是:已有原 trace ID → 在相同服务与时间范围内查 `linked=<原 trace ID>` → 取得新执行的 trace ID。新执行已有原生 span link 时,优先核对它的 trace/span ID。
8
+
9
+ 原 trace 上的业务属性不会因 link 自动复制到新 trace。不能要求企业属性、执行属性和错误在同一个 span 上,也不能把独立 trace 当成原 trace 的 parent/child。先按实际返回的显式链接确认遥测范围,再核对本场景要求的业务标识。
10
+
11
+ `linked` 只精确到原 trace,原 trace 可能承载多项操作;有多个候选时还需原生 link 的 span ID、对象和场景等实际记录消歧。链接缺失或仅有同企业、同表名、时间邻近时,保留关联缺口,不补造依赖、重试或引擎任务关系。
@@ -0,0 +1,18 @@
1
+ # 查询预算与结果复用
2
+
3
+ 判断还能再查几次、已有结果能不能复用时读。与[查询方法](../queries.md)配套。
4
+
5
+ ## 查询预算与结果复用
6
+
7
+ - 工具说明和指南本轮只读取一次;已取得的执行、task、Metric 原始链接和产物路径随调查摘要保留。索要链接或已有字段时先读取该摘要,不为展示重复查询。
8
+
9
+ - 同一环境、时间、服务、锚点和过滤条件组成的查询不得重复执行。需要从同一结果提取不同字段时,复用已经取得的结果。
10
+ - 资源发现最多执行“精确首查 + 同范围一次降级”。两次仍不能得到执行锚点时,先向用户确认资源、时间或服务,不继续串行试探相近关键词。只有 dagId 的精确链发现可使用更新发现指引中的一次有界时间扩展,不能套用到企业、普通对象或历史基线。
11
+ - 一旦取得 traceId、taskId 或唯一执行,立即冻结该执行的环境、时间和服务;后续只做 trace、关联日志和 Metric 的精确查询,不再从资源 ID 重走发现链路。
12
+ - taskId 或 chainId 只锚定执行,不等于已经取得 trace。只有这类锚点时,在冻结的环境、服务和执行时间窗内精确反查一次对应 trace;无法取得时保留 task/chain 记录并说明缺 trace,不扩大成新的资源发现。
13
+ - 精确 trace 已确认但 span 明细因保留期或后端差异不可读时,优先在该 trace 的原时间窗和已确认业务服务下按 `trace_id` 精确查询日志。精确 trace URL 没有时间且默认读取为空时,按[Metric 获取方法 · 任务属性缺失时](../../engine/queries.md#任务属性缺失时)做一次受控的精确 ID 日志回退;它只恢复原时间和 task,不属于资源发现。
14
+ - 对比调查的查询预算按执行分别计算。成功基线是用户明确选定的对照目标,不受“不要深挖尚未选中的成功候选”限制;一侧查询和 Metric 产物不能冒充另一侧。
15
+ - Trace 查询只选择识别场景、执行和关联所需字段。已有精确 traceId 时优先使用定向查询;没有必要时不拉取整棵 trace 的全部 span 和 attribute。
16
+ - 同一完整原始结果已经足以回答数量或状态时,直接按明确单位整理,不再重复查询聚合。结果未覆盖完整、需要去重口径或总体统计时,才补相应聚合;样本不能替代总体。
17
+ - MetricOuts 正文的获取、去重、复用和生命周期补查按[Metric 获取方法](../../engine/queries.md)执行。
18
+ - 查询返回超大结果或发生截断时,不用重复同一查询解决截断;改为减少返回行数和字段、增加精确 task 过滤,或在工具侧完成提取后只返回摘要。
@@ -0,0 +1,69 @@
1
+ # SigNoZ 原始记录查询例子
2
+
3
+ 要取 span 的自定义 attribute(`taskName`、`metric`、`data.request_context` 等)时用这个结构:便捷搜索工具不返回这些字段,要在 `selectFields` 里点名。下面的例子已在线上核对过可用。例子描述 SigNoZ 原始记录结构;执行工具、调用参数和支持的字段以当前客户端声明为准。占位符必须替换;以下 `start` / `end` 仅为示例时间,实际使用时替换为已核对的 Unix 毫秒整数。在 Query Builder JSON 中直接传入整数,不加引号;便捷工具的独立时间参数仍按各自声明传入。
4
+
5
+ ```json
6
+ {
7
+ "schemaVersion": "v1",
8
+ "start": 1700000000000,
9
+ "end": 1700000060000,
10
+ "requestType": "raw",
11
+ "compositeQuery": {
12
+ "queries": [{
13
+ "type": "builder_query",
14
+ "spec": {
15
+ "name": "A",
16
+ "signal": "traces",
17
+ "disabled": false,
18
+ "limit": 200,
19
+ "offset": 0,
20
+ "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
21
+ "filter": {"expression": "trace_id = '<trace>' AND name = 'QueryExecutor'"},
22
+ "having": {"expression": ""},
23
+ "selectFields": [
24
+ {"name": "timestamp", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
25
+ {"name": "trace_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
26
+ {"name": "span_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
27
+ {"name": "name", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
28
+ {"name": "duration_nano", "fieldDataType": "int64", "signal": "traces", "fieldContext": "span"},
29
+ {"name": "taskName", "fieldDataType": "string", "signal": "traces", "fieldContext": "attribute"},
30
+ {"name": "metric", "fieldDataType": "string", "signal": "traces", "fieldContext": "attribute"}
31
+ ]
32
+ }
33
+ }]
34
+ },
35
+ "formatOptions": {"formatTableResultForUI": false, "fillGaps": false},
36
+ "variables": {}
37
+ }
38
+ ```
39
+
40
+ `fieldDataType` 要和属性实际类型一致。类型写错或这个 span 上没有该属性时,返回的是默认值(`false`、`0`、空字符串),不能当成真实取值;拿不准先用字段键工具查类型。业务服务埋点里,`loadData`、`skip`、`active`、`requeue` 这类真假值是字符串 `'true'`/`'false'`;`rowCount`、`dataModify`、`merge_count`、`wait_merge_time` 等数值是数字,可以直接比大小和聚合。旧版本写入的数值也是字符串,字段键工具查到同名属性有两种类型时,两种都要取。按当前缺口增减 selectFields,不能因为例子没有列出某字段就忽略场景需要的字段。span 基本字段 context 为 span,自定义标签为 attribute,`service.name` 为 resource;数值与布尔标签分别使用已声明类型。当前执行与必要父记录分别保留。
41
+
42
+ 查日志时 `signal` 改为 `logs`,`timestamp`、`body`、`trace_id`、`span_id`、`severity_text` 属于 `log`,业务服务的类名 `scope_name` 属于 `scope`,`exception.*`、`thread.name` 和引擎的 `logger.name` 属于 `attribute`。下面的 spec 已在线上核对过,按同样结构替换 `queries[0].spec`:
43
+
44
+ ```json
45
+ {
46
+ "name": "A",
47
+ "signal": "logs",
48
+ "disabled": false,
49
+ "limit": 50,
50
+ "offset": 0,
51
+ "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
52
+ "filter": {"expression": "trace_id = '<trace>' AND severity_text IN ('ERROR', 'WARN')"},
53
+ "having": {"expression": ""},
54
+ "selectFields": [
55
+ {"name": "timestamp", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
56
+ {"name": "span_id", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
57
+ {"name": "severity_text", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
58
+ {"name": "body", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
59
+ {"name": "scope_name", "fieldDataType": "string", "signal": "logs", "fieldContext": "scope"},
60
+ {"name": "exception.type", "fieldDataType": "string", "signal": "logs", "fieldContext": "attribute"},
61
+ {"name": "exception.message", "fieldDataType": "string", "signal": "logs", "fieldContext": "attribute"}
62
+ ]
63
+ }
64
+ ```
65
+
66
+ 没有异常的日志,`exception.*` 返回空字符串,不是缺字段。Metric 日志用原始链接的完整过滤条件,或已核对的 task 加 MetricOuts 的 `logger.name`,不要把业务服务套到引擎上。
67
+
68
+ 设置当前问题所需的有限上限;命中上限、分页或截断时先处理覆盖。没有说明某结构或字段是否支持时取得工具说明,不猜测额外参数,也不反复枚举说明资源。
69
+