@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/knowledge/common/queries.md

@@ -0,0 +1,98 @@
+# 通用 · 查询方法
+
+查 SigNoZ 时，先用环境、时间、服务和业务 ID 把范围缩小，再读 trace 或日志。日志和 trace 同样是一手记录，查法见[查日志](#查日志)。要查之前先看“默认值速查”，其余章节用到再看。各场景的接口清单在各域 `queries.md`，MCP 安装见[配置 SigNoZ MCP](topics/setup-signoz-mcp.md)。
+
+## 目录
+
+- [默认值速查](#默认值速查)
+- [选择和调用工具](#选择和调用工具)
+- [调查起点](#调查起点)
+- [查询约束](#查询约束)
+- [查日志](#查日志)
+- [按需展开](#按需展开)
+
+## 默认值速查
+
+| 情况 | 默认处理 |
+|---|---|
+| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](concepts.md)。SigNoZ 工具带 `env` 参数时，正式环境传 `work`；`prod` 是测试实例下的子环境，不是正式环境 |
+| 普通对象（tableId、widgetId、reportId 等）没有时间 | 完全缺少时间时合并询问一次时间，不同时要求选择环境，不要默认最近 7 天 |
+| 企业更新没有时间或只说“最近” | 企业更新无时间默认最近 24 小时，告知后直接查询，优先核对异常 |
+| 只有 dagId | dagId 不先追问时间，由助手管理检索窗口，命中后按实际记录恢复链范围 |
+| 用户说“之前没超限”“以前正常”“最近变慢” | 已经是历史对比目标；先定位目标执行，再主动查找目标执行前 24 小时的可比基线 |
+| 只有单次失败 | 单次失败诊断不要求发现或补充成功执行 |
+| 仪表板内组件计算异常 | 优先有界查找组件单独预览记录；未找到仍继续分析本次异常，见[仪表板内外组件对照](topics/baseline-comparison.md#仪表板内外组件对照) |
+
+## 选择和调用工具
+
+- 先列出已连接 SigNoZ 的工具名，只读这次要用的那个工具的说明；读过一次就复用，不要把全部工具说明都输出一遍。调用方式以客户端实际的工具声明为准，按[环境选择规则](concepts.md)核对目标 URL，工具前缀和推荐名称不一样不用重配。
+- **已有 traceId 时**，便捷的 span 搜索和详情工具只返回 span 名、耗时、错误这些基本列，不带 `taskName`、`metric`、`data.request_context` 这类自定义 attribute。按这个顺序取：
+  1. 日志按 `trace_id` 查一次，常常就能拿到报错原文、引擎任务 ID 和请求结束时间，比翻 trace 便宜。
+  2. span 搜索按 `trace_id` 加 `has_error = true`、span 名或 `duration_nano` 取关键的几条 span，看时间线和错误。
+  3. 要业务 attribute 时，用 Query Builder（如 `signoz_execute_builder_query`）按 `trace_id` 加 span 名过滤，在 `selectFields` 里点名要的 attribute，写法见[原始查询例子](topics/query-example.md)。
+  4. 详情工具一次最多 1000 行，线上常有几十万到上百万字符，只在要看父子结构时用，输出存临时文件再用 shell 按需读（客户端自动落盘的文件常是 `[{type, text}]`，真正的 JSON 在 `text` 里，先取出来再解析）；超过 1000 行时用 span 搜索按 `trace_id` 加 offset 翻页。这和工具自带说明的建议不同，以这里为准。
+- 工具参数和查询字段名不一样：详情工具的参数是 `traceId`，查询表达式里写 `trace_id`。收到字段错误时只改报错的那个字段。
+- 客户端读不到 Query Builder 的说明资源时，直接照[原始查询例子](topics/query-example.md)写，不要反复枚举资源或猜结构；说明读不到不等于 SigNoZ 查不了。
+- 结果只把这次需要的字段和摘要放进上下文，大响应直接存临时文件，再用 shell 按需读。命中条数到了 limit，就算没有 nextCursor 也不能说已经查全；需要完整时，按同一个执行缩到必要的 span 或字段再核对。
+
+一条 trace 可能包含好几次工作区操作或好几个计算。已经有目标 span 和时间，就拿它们当条件；结果到了上限，先收到目标 span 及其父子范围，不重复取整条 trace，也不要拿整条 trace 里最慢的任务顶替目标。入口不属于已有场景时，保留入口名，用通用时间线和明确绑定的任务解释，不要硬归到分析表或仪表板。
+
+## 调查起点
+
+| 已有输入 | 首次动作 |
+|---|---|
+| SigNoZ trace 链接 | 从 URL 确认环境和 traceId，精确读取 trace，再使用 trace 时间与 `service.name`。链接里没有时间时，工具的默认窗口（1～6 小时）常常查不到：先用 span 搜索按 `trace_id` 在 7 天内查 1 条拿到时间，或者直接用 SigNoZ 报错提示里给出的 trace 时间窗 |
+| 精确 traceId 或执行 ID | 复用已确认环境；未指定时默认 work，精确查询并恢复执行时间 |
+| tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间，使用场景入口、服务和资源 attribute 寻找候选执行 |
+| 企业 ID（更新查询） | 复用已有时间；未提供时告知默认最近 24 小时后直接查询，先给更新概况并优先核对异常 |
+| dagId | 按更新链标识精确发现提交与节点，不要求用户先补时间或 trace；检索时间见[更新发现指引](../update/topics/discover-executions.md#检索时间) |
+| 截图或 OCR 提取的 ID | 先核对字符并确认锚点可信度；存在相似字符歧义时请用户确认或粘贴原始文本 |
+| 只有现象 | 补充能够确定场景或资源、发生时间的最小信息；未指定环境默认 work，不直接发起宽查询 |
+
+资源 ID 可以关联多次前台查询和后台更新，不是一次执行的唯一标识，默认环境不改变这个区分。企业更新与 dagId 的检索窗口、降级和时间扩展只适用于更新发现，细则见[更新发现指引](../update/topics/discover-executions.md#检索时间)。
+
+## 查询约束
+
+从资源出发的第一次查询，尽量同时带上：
+
+```text
+已确认环境
++ 明确时间范围
++ service.name
++ 场景入口或特征 span
++ 资源 attribute / 精确业务 ID
+```
+
+- **服务**：`service.name` 优先放进过滤。从精确 trace、[环境映射](concepts.md)或场景知识取得；定不下来时，只在已确认的环境和时间里收出少量候选，必要时问用户。业务服务名随部署环境变化，应以对应执行或已核对的环境信息为准，不要把 `default` 或某次测试的服务名当成所有环境的固定值。
+- **时间**：用户给了具体时刻，第一次查该时刻前后各 15 分钟；给了时间段就用那个范围。用户直接给的 trace 链接或 traceId 是精确锚点，不受这条限制。已有时间边界直接复用；“最近 24 小时”这类范围在工具支持时直接用 `timeRange`。明确日期或历史基线使用绝对边界；工具要 Unix 毫秒时，用运行环境的日期函数一次处理，沿用上下文或客户端的时区。查询前核对日期、时区、单位及起止顺序，只有真有歧义才问用户。
+- **时间戳格式**：返回的 `timestamp` 可能是带纳秒小数的 RFC3339 字符串，也可能是秒、毫秒、微秒或纳秒的数字，保留原值。拿来当查询边界时按实际格式和单位换算，不要把字符串直接当整数，也不要把纳秒当毫秒传。
+- **范围冻结**：第一次查询开始后记下环境、时区和窗口；普通对象查询里，时间窗外的结果不能作为本次候选。选定执行后就固定它的范围，不拿更早或更晚的相邻执行替代。DAG 的默认发现窗口不限制已经由精确标识确认的同链记录，按更新发现指引恢复真实范围。目标执行和基线执行各有各的范围，不能拿目标的时间窗去查基线；要扩大某一侧，记下原因和新旧边界。
+- **结果大小**：只选这次判断需要的字段，设有限的条数。`MemoryLimitExceeded` 这类高频关键字，在几天的窗口里全文搜索或按时间聚合，常常超时或超出大小限制；先用表 ID、任务 ID 这类精确值缩小，时间窗控制在出问题前后几小时。已有 traceId、taskId 这类精确锚点就精确过滤，不再从资源 ID 重新发现。
+- **没命中时**：先核对时区、环境、服务和资源值。确认输入没错后，每次只扩大一个维度；不能同时跨环境、扩大时间并移除 `service.name`。
+
+企业或 dagId 入口先按更新发现指引找回关联执行，再在对应执行里核对失败信号，不要求企业属性和错误必须落在同一个 span 上。
+
+## 查日志
+
+报错原文、堆栈和业务过程（加载起止、结果提交、tag 保留等）常常只在日志里，span 上只有摘要，该查日志时别只看 trace。
+
+- **两类来源**：业务服务（`hihidata-jsy-*`、`datasource-server` 等）的日志基本都带 `trace_id`、`span_id`，打日志的类名在 `scope_name`；引擎集群（`*-polars-cluster`）的日志不带 `trace_id`，类名在 `logger.name`，按 task 查，见[引擎查询](../engine/queries.md#metric-链接与任务日志)。
+- **常用字段**：`body` 是正文，可能多行；`severity_text` 是 `ERROR`、`WARN`、`INFO` 等级别；带异常的日志另有 `exception.type`、`exception.message`、`exception.stacktrace`；还有 `thread.name`、`service.name`。
+- **有 traceId**：日志直接按 `trace_id` 过滤，不加服务过滤，同一个请求的日志可能来自不同服务；只要错误时加 `severity_text IN ('ERROR', 'WARN')`。拿到的日志用 `span_id` 对回 span。
+- **只有资源或执行 ID**：在已确认的环境、时间和 `service.name` 里用 `body CONTAINS '<ID>'`，能加各域给的日志 signature 就加上；拿到 `trace_id` 再按 trace 展开。
+- **只有报错现象**：先在短时间窗里按 `exception.type` 或报错原文聚合计数，按 `scope_name`、`exception.type` 分组，看是普遍还是偶发，再取一两条原文。统计次数用聚合工具，不要翻页数行。很多 ERROR 日志的 `exception.type` 是空的，这时按 `scope_name` 加正文开头的固定文字归类，正文里的 ID 不算分类；要区分普遍还是个别，再按 `trace_id` 或正文里的对象 ID 数不同值。
+- **补 trace_id**：便捷日志搜索没返回 `trace_id` 时，在同样的过滤条件和时间窗里跑一次 Query Builder，只补 `timestamp`、`body`、`trace_id`、`span_id`、`service.name` 这些关联字段；不要因此退成按 operation 或全服务去搜 trace。
+- **控制大小**：`body CONTAINS` 是全文扫描，先用服务、时间和级别缩小；`exception.stacktrace` 很长，要用时在 Query Builder 里点名取，写法见[原始查询例子](topics/query-example.md)。
+- **脱敏**：正文可能带 token、请求体或个人数据，引用时只取需要的片段并脱敏。
+
+## 按需展开
+
+下面这些情形才需要读对应的 topic，其余时候不用读：
+
+| 遇到 | 读 |
+|---|---|
+| 从现象、截图或转抄的 ID 开始，还没有可信的执行锚点 | [从现象或截图开始](topics/start-and-anchors.md) |
+| 后台独立 trace，要从原 trace 找到执行 trace（`linked`） | [独立 Trace 与 linked](topics/linked-traces.md) |
+| 判断还能再查几次、已有结果能否复用 | [查询预算与结果复用](topics/query-budget.md) |
+| 用户说“之前正常”“最近变慢”，或仪表板内组件异常需要单独预览对照 | [主动对比与基线](topics/baseline-comparison.md) |
+| 响应很大、需要落盘读取，或用户要求线上取样评测 | [大结果、临时文件与取样](topics/large-results.md) |

package/content/knowledge/common/signals.md

@@ -0,0 +1,58 @@
+# 通用 · 入口与信号
+
+只有 trace、执行链接，或者看不出是哪个场景时，用这里判断从哪个场景开始查。四个场景各自的 span 字典和后续排查在各域的 `signals.md` 和 `workflow.md` 里。
+
+这里定的只是调查起点，根因在哪还要再验证。给用户说清从哪个场景开始、凭什么判断、还可能牵涉哪些场景就行，不用套固定格式。
+
+## 先从 trace 里看什么
+
+- 根 span 或入口 span，HTTP method 和 route；
+- 关键 span 名，不只看最慢的那个；
+- `data.request_context`、`data.endpoint`、`sense` 这类业务 attribute；
+- `tableId`、`component.id`、`reportId`、`dagId` 这类资源或执行 ID；
+- service、时间、耗时、错误，以及上下游关系。
+
+## 识别方法
+
+本知识库里的 route 都写成去掉部署上下文路径的形式（如 `POST /v2/design/widget/data`）。SigNoZ 里的 HTTP span 名和 `http.route` 带上下文路径，测试环境是 `/decision`（如 `POST /decision/v2/design/widget/data`），匹配时按实际环境的前缀处理，不要原样拿本库的写法去精确过滤。
+
+1. 接口或业务 attribute 已经对上某个场景，就去读那个场景的 `signals.md` 确认含义。
+2. 接口没收录时，拿 trace 里实际出现的 span 名、attribute 名和值去各场景的 `signals.md` 里搜，只读命中的文件。认场景这一步不展开更新取证。
+3. 优先用能说明业务入口的信号组合。资源 ID 和上下游关系可以补强，但一般不能单独决定场景。
+4. 碰到仪表板组件预览入口，先按下面的[仪表板组件预览入口](#仪表板组件预览入口)判断来源，不能只凭最外层 HTTP span 或共享的 span 名选场景。
+5. 同时像好几个场景时，从入口信号最强的那个开始，其他的留着；起点不等于根因所在。
+6. 只有通用 Query 或 engine span 时，场景就记为未知。可以接着分析引擎层的事实，但不要据此猜业务入口。
+
+## 仪表板组件预览入口
+
+`POST /v2/external/widget/data`（代码里叫外部组件取数）实际场景就是仪表板里的组件预览，线上绝大多数请求来自仪表板；仪表板以外的图表预览也走这个接口，但只占少数。沿同一入口父子链找带 `DataRequestObservation` 属性的 span，可能是 `previewComponent`，也可能是别的子 span；最外层 HTTP span 的 `reportId` 可能是空的。
+
+- 任一对应 span 的 `data.request_context=dashboard` 或 `reportId` 非空，就是仪表板内组件计算，完全归仪表板场景，不先经过组件专项分流。
+- 确认这条链上这些信号都是空的，才按仪表板以外的图表预览查。属性还没拿到时记为未知，不能当成空值。
+- `previewComponent` 只是共享入口的 span 名，决定不了场景。离开这条取数链的 `reportId` 只能当关联线索；接口和 attribute 说法不一致时，两边都留着，不要悄悄选一个。
+
+这套规则只定调查入口。单个组件 trace 或仪表板来源标识，都证明不了已经覆盖整次仪表板交互。
+
+## 各场景的信号
+
+| 场景 | 读 |
+|---|---|
+| 分析表 | [dataset/signals.md](../dataset/signals.md) |
+| 组件 | [component/signals.md](../component/signals.md) |
+| 仪表板 | [dashboard/signals.md](../dashboard/signals.md) |
+| 更新 | [update/signals.md](../update/signals.md) |
+
+认出是更新以后：要查慢或失败，进[更新性能排查](../update/workflow.md#更新性能排查)；要弄清更新来源、DAG、计数，或解释已有的运行记录，进[解释更新记录](../update/workflow.md#解释更新记录)。
+
+## 哪些信号靠得住
+
+- 已确认的业务接口、明确的请求上下文，或者场景特有的入口 span 加业务 attribute，可以直接用来选起点。
+- `tableId` 这类共享资源字段，以及离开组件取数链的 `reportId`，主要用来关联上下游，不能单独定场景。
+- 最慢 span 只说明耗时在哪，说明不了是哪个场景。
+- 请求成没成功看 span 的 `has_error` 和 `status_message`，不看 HTTP 状态码：前台接口常常返回 200，错误写在 `status_message` 里。
+- 没有靠得住的命中，就记为未知，只补一项最能区分的入口、上下文或资源信息。
+- 以这次实际的入口和字段为准。历史入口只能解释历史操作，字段缺失不能证明对应行为不存在（见[知识适用性](conclusions.md#知识适用性)）。
+
+## 长 trace 与其他入口
+
+同一个 trace 里可能有好几次工作区操作。已经给了执行 span 和时间，就只沿它的父子范围认入口，不要把整个 trace 里最慢的任务当成用户要查的。入口是工作区详情这类没有专项知识的操作时，保留它本来的入口名，按通用时间线和明确关联的引擎任务解释；共用了计算，不代表它就变成了分析表预览。

package/content/knowledge/common/topics/baseline-comparison.md

@@ -0,0 +1,23 @@
+# 主动对比与基线
+
+用户表达“之前正常”“最近变慢”，或仪表板内组件异常需要单独预览对照时读。与[查询方法](../queries.md)配套。
+
+## 主动对比
+
+先定位目标执行，再在同环境、对象和执行类型下发现正常基线；仪表板与组件单独预览的跨入口对照按下节处理。用户已给正常时间或成功执行时直接复用；只表达“之前正常”时，以目标执行开始时间为右边界，查询此前 24 小时的半开窗口，不用当前时钟或目标发现窗口的起点代替。时间参数按[查询约束](../queries.md#查询约束)处理，两侧边界分别保留。
+
+基线发现同样遵守“精确首查 + 同范围一次降级”，只取有限候选及判断可比性所需字段。按时间由近到远检查同对象、操作、参数和数据范围的成功执行；有明确成功结果且可比时选择最近一条并记录依据，不能仅凭耗时短或没有 ERROR 认定成功。成功节点也不自动代表整条更新链成功。影响可比性的字段缺失或多个不同操作仍可信时，展示差异再作最小消歧；已经明确的数据范围变化可以作为待解释差异，不要求两侧数值完全相同。
+
+分别维护 `目标执行` 和 `基线执行`：各自记录环境、trace/focused span、时间、业务及 engine 服务、task、Metric 与覆盖范围；时间窗只在本侧冻结，不跨侧复用。切换已选执行必须说明原因和记录上的差异，不能用相邻失败或另一侧产物静默替代。
+
+选定后主动取两侧 Trace、task 和 Metric；已有产物复用，每侧范围独立冻结。不得停在“建议再取 Metric”或等待用户说“你帮我取”。对照未找到、不可比或无法取得时，交付本次事实与已查询范围，并请求更早正常时间或最小缺失项，不自动扩大到七天。用户没有相对变化目标时仍按单次诊断推进。
+
+### 仪表板内外组件对照
+
+这是仪表板组件异常的默认浅查，不要求用户先提出对比，也不扩大为整张仪表板或企业扫描。先从目标 trace 恢复组件、查询表、时间与业务服务。已有单独预览材料优先复用；没有时间的对照查找，以目标执行开始前 24 小时的半开窗口为限。用户给出更明确的单独预览时间或 trace 时按该侧记录恢复范围，不套用失败侧时间。
+
+首次在同环境、同业务服务和该窗口内按组件身份及单独预览入口取有限候选，按时间由近到远核对。单独预览入口是图表编辑的 `editComponent`，或 `previewComponent` 上 `data.request_context` 不是 `dashboard`、`reportId` 为空的请求；`data.request_context=dashboard` 的都是仪表板里的请求，不能当对照。图表编辑时可能不记录 `component.id` 和 `data.request_context`；首查未命中时，在同窗口与服务内只降级一次，改查图表编辑时请求日志中的精确组件 ID，或已确认查询表加请求用户、查询字段等识别信息，不要求 `reportId` 同时命中。查询表只能发现候选，身份与可比性按[组件计算对照怎么判断](../../dashboard/topics/component-comparison.md#组件计算对照怎么判断)核对；不能因同表就认定为同组件。
+
+候选达到 limit 时，不宣称已覆盖所有记录；能唯一核实最近可比执行时选定并冻结，否则保留覆盖缺口。不继续扩大时间、移除服务或换表试探。未找到或不可比就继续目标失败分析，按场景流程提示用户检查单独预览结果。找到可比成功执行时主动取得两侧执行统计，各侧 engine 服务分别确认，不能把失败侧 engine 服务过滤直接套到成功侧。
+
+筛选器名称与绑定关系是另一项精确元数据取证，不是上述正常执行发现的重复查询。需要跨 trace 查筛选器关系时，默认复用同一前置窗口、业务服务和精确字段/组件标识；有明确关联请求时间或 trace 时直接精确读取。关联规则见[名称与请求上下文的关联取证](../../dashboard/topics/name-binding.md#名称与请求上下文的关联取证)，不得仅凭“附近”不断扩大范围。

package/content/knowledge/common/topics/large-results.md

@@ -0,0 +1,12 @@
+# 大结果、临时文件与取样
+
+响应很大、需要落盘读取，或用户要求线上取样评测时读。与[查询方法](../queries.md)配套。
+
+## 大结果与临时文件
+
+- 大响应保存到系统临时文件，读取、摘要和引用都从这份文件出发；不要为同一内容重复查询线上正文。保存失败时复用内存中的响应重试，不重新查询。
+- 临时摘要按白名单取字段，只展示操作、执行标识、时间、状态、错误签名及当前判断所需的明确数值。不要直接打印 `body` 首行、任意正文前缀或整份 Job 字段映射；其中可能包含租户、用户、描述和完整载荷。Metric 的读法见[读取大正文](../../engine/queries.md#读取大正文)。
+
+Trace、业务属性和 Metric 的临时原文在同一调查中保留并复用；首次交付或切换场景不立即删除。调查结束后按客户端临时目录策略清理，不把原始大响应写入工作区。
+
+用户明确要求从线上选取样本评测时，可以在获准环境和服务内自行设定有限的取样时间窗、耗时阈值和结果数，并说明选择依据。样本选定后转为对应执行的精确调查；取样范围不作为每个案例后续查询的默认范围。

package/content/knowledge/common/topics/linked-traces.md

@@ -0,0 +1,11 @@
+# 独立 Trace 与 linked
+
+从原 trace 找后台独立执行 trace，或反过来时读。与[查询方法](../queries.md)配套。
+
+## 独立 Trace 的显式链接
+
+部分后台执行会创建没有父 span 的新 trace，同时用 span link 指向进入该执行前的 span；新执行上的 `linked` attribute 保存被链接的原 trace ID。查询方向是：已有原 trace ID → 在相同服务与时间范围内查 `linked=<原 trace ID>` → 取得新执行的 trace ID。新执行已有原生 span link 时，优先核对它的 trace/span ID。
+
+原 trace 上的业务属性不会因 link 自动复制到新 trace。不能要求企业属性、执行属性和错误在同一个 span 上，也不能把独立 trace 当成原 trace 的 parent/child。先按实际返回的显式链接确认遥测范围，再核对本场景要求的业务标识。
+
+`linked` 只精确到原 trace，原 trace 可能承载多项操作；有多个候选时还需原生 link 的 span ID、对象和场景等实际记录消歧。链接缺失或仅有同企业、同表名、时间邻近时，保留关联缺口，不补造依赖、重试或引擎任务关系。

package/content/knowledge/common/topics/query-budget.md

@@ -0,0 +1,18 @@
+# 查询预算与结果复用
+
+判断还能再查几次、已有结果能不能复用时读。与[查询方法](../queries.md)配套。
+
+## 查询预算与结果复用
+
+- 工具说明和指南本轮只读取一次；已取得的执行、task、Metric 原始链接和产物路径随调查摘要保留。索要链接或已有字段时先读取该摘要，不为展示重复查询。
+
+- 同一环境、时间、服务、锚点和过滤条件组成的查询不得重复执行。需要从同一结果提取不同字段时，复用已经取得的结果。
+- 资源发现最多执行“精确首查 + 同范围一次降级”。两次仍不能得到执行锚点时，先向用户确认资源、时间或服务，不继续串行试探相近关键词。只有 dagId 的精确链发现可使用更新发现指引中的一次有界时间扩展，不能套用到企业、普通对象或历史基线。
+- 一旦取得 traceId、taskId 或唯一执行，立即冻结该执行的环境、时间和服务；后续只做 trace、关联日志和 Metric 的精确查询，不再从资源 ID 重走发现链路。
+- taskId 或 chainId 只锚定执行，不等于已经取得 trace。只有这类锚点时，在冻结的环境、服务和执行时间窗内精确反查一次对应 trace；无法取得时保留 task/chain 记录并说明缺 trace，不扩大成新的资源发现。
+- 精确 trace 已确认但 span 明细因保留期或后端差异不可读时，优先在该 trace 的原时间窗和已确认业务服务下按 `trace_id` 精确查询日志。精确 trace URL 没有时间且默认读取为空时，按[Metric 获取方法 · 任务属性缺失时](../../engine/queries.md#任务属性缺失时)做一次受控的精确 ID 日志回退；它只恢复原时间和 task，不属于资源发现。
+- 对比调查的查询预算按执行分别计算。成功基线是用户明确选定的对照目标，不受“不要深挖尚未选中的成功候选”限制；一侧查询和 Metric 产物不能冒充另一侧。
+- Trace 查询只选择识别场景、执行和关联所需字段。已有精确 traceId 时优先使用定向查询；没有必要时不拉取整棵 trace 的全部 span 和 attribute。
+- 同一完整原始结果已经足以回答数量或状态时，直接按明确单位整理，不再重复查询聚合。结果未覆盖完整、需要去重口径或总体统计时，才补相应聚合；样本不能替代总体。
+- MetricOuts 正文的获取、去重、复用和生命周期补查按[Metric 获取方法](../../engine/queries.md)执行。
+- 查询返回超大结果或发生截断时，不用重复同一查询解决截断；改为减少返回行数和字段、增加精确 task 过滤，或在工具侧完成提取后只返回摘要。

package/content/knowledge/common/topics/query-example.md

@@ -0,0 +1,69 @@
+# SigNoZ 原始记录查询例子
+
+要取 span 的自定义 attribute（`taskName`、`metric`、`data.request_context` 等）时用这个结构：便捷搜索工具不返回这些字段，要在 `selectFields` 里点名。下面的例子已在线上核对过可用。例子描述 SigNoZ 原始记录结构；执行工具、调用参数和支持的字段以当前客户端声明为准。占位符必须替换；以下 `start` / `end` 仅为示例时间，实际使用时替换为已核对的 Unix 毫秒整数。在 Query Builder JSON 中直接传入整数，不加引号；便捷工具的独立时间参数仍按各自声明传入。
+
+```json
+{
+  "schemaVersion": "v1",
+  "start": 1700000000000,
+  "end": 1700000060000,
+  "requestType": "raw",
+  "compositeQuery": {
+    "queries": [{
+      "type": "builder_query",
+      "spec": {
+        "name": "A",
+        "signal": "traces",
+        "disabled": false,
+        "limit": 200,
+        "offset": 0,
+        "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+        "filter": {"expression": "trace_id = '<trace>' AND name = 'QueryExecutor'"},
+        "having": {"expression": ""},
+        "selectFields": [
+          {"name": "timestamp", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
+          {"name": "trace_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
+          {"name": "span_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
+          {"name": "name", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
+          {"name": "duration_nano", "fieldDataType": "int64", "signal": "traces", "fieldContext": "span"},
+          {"name": "taskName", "fieldDataType": "string", "signal": "traces", "fieldContext": "attribute"},
+          {"name": "metric", "fieldDataType": "string", "signal": "traces", "fieldContext": "attribute"}
+        ]
+      }
+    }]
+  },
+  "formatOptions": {"formatTableResultForUI": false, "fillGaps": false},
+  "variables": {}
+}
+```
+
+`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；数值与布尔标签分别使用已声明类型。当前执行与必要父记录分别保留。
+
+查日志时 `signal` 改为 `logs`，`timestamp`、`body`、`trace_id`、`span_id`、`severity_text` 属于 `log`，业务服务的类名 `scope_name` 属于 `scope`，`exception.*`、`thread.name` 和引擎的 `logger.name` 属于 `attribute`。下面的 spec 已在线上核对过，按同样结构替换 `queries[0].spec`：
+
+```json
+{
+  "name": "A",
+  "signal": "logs",
+  "disabled": false,
+  "limit": 50,
+  "offset": 0,
+  "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
+  "filter": {"expression": "trace_id = '<trace>' AND severity_text IN ('ERROR', 'WARN')"},
+  "having": {"expression": ""},
+  "selectFields": [
+    {"name": "timestamp", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
+    {"name": "span_id", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
+    {"name": "severity_text", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
+    {"name": "body", "fieldDataType": "string", "signal": "logs", "fieldContext": "log"},
+    {"name": "scope_name", "fieldDataType": "string", "signal": "logs", "fieldContext": "scope"},
+    {"name": "exception.type", "fieldDataType": "string", "signal": "logs", "fieldContext": "attribute"},
+    {"name": "exception.message", "fieldDataType": "string", "signal": "logs", "fieldContext": "attribute"}
+  ]
+}
+```
+
+没有异常的日志，`exception.*` 返回空字符串，不是缺字段。Metric 日志用原始链接的完整过滤条件，或已核对的 task 加 MetricOuts 的 `logger.name`，不要把业务服务套到引擎上。
+
+设置当前问题所需的有限上限；命中上限、分页或截断时先处理覆盖。没有说明某结构或字段是否支持时取得工具说明，不猜测额外参数，也不反复枚举说明资源。
+

package/content/knowledge/common/topics/setup-signoz-mcp.md

@@ -0,0 +1,102 @@
+# 配置 SigNoZ MCP
+
+为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ，但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读；已有可用的 SigNoZ 工具或只有离线材料时不需要。正常首次配置只向用户请求缺少的 API Key，安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力，不分析业务问题；完成后回到原调查继续。
+
+## 目录
+
+- [默认流程](#默认流程)
+- [交互与结果](#交互与结果)
+- [安装 MCP Server](#安装-mcp-server)
+- [接入当前客户端](#接入当前客户端)
+- [重载与恢复](#重载与恢复)
+- [Windows 构建说明](#windows-构建说明)
+
+## 默认流程
+
+1. 确认目标环境：用户输入、现有配置或[环境知识](../concepts.md)，没指定就用 work，不让用户先选。`work` 是正式环境，`prod` 不是；不按工具顺序或 `service.environment` 猜实例。URL 和口头说法冲突时只让用户确认“测试环境”还是“正式环境”，确认前不写配置。默认连接不可用就修它，不改用测试环境。
+2. 当前客户端已有能确认目标 URL 的 SigNoZ 工具，就跳过安装配置（推荐名称不同不重配），做一次最小只读验证就回原任务；本轮已有成功查询直接复用。
+3. MCP Server 缺失或损坏时，简短告知尚未安装，按“安装 MCP Server”默认安装适配当前系统和 CPU 的产物，不让用户确认版本、下载源或路径。
+4. 没有目标环境的有效凭据时只请求一次 API Key，环境能唯一确定就一并说明，不再问 URL 或 MCP 名称。用户提供 API Key 就表示同意写入本次目标环境的配置，不再追加配置确认，直接按“接入当前客户端”配好。
+5. 重载并做最小只读验证；客户端必须由用户 Trust、启用或重启时，只提示这一步。成功后立即回到原调查，不把安装变成独立任务。
+
+只配置当前正在运行的 Agent 客户端，不要因为发现 Cursor、Codex、WorkBuddy 等其他客户端的配置文件就切换目标。只有环境确定不了、平台不支持、同名配置冲突或配置方式确实判断不了时，才请用户补最小的信息。
+
+## 交互与结果
+
+- 正常成功路径只说明 MCP 已准备好并继续原任务；不主动展示 checksum、压缩包、安装目录、完整配置或排障过程。
+- 安装后等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装，请提供 `<环境>` 的 API Key 以继续配置和诊断”。
+- 不回显用户提供的 API Key，也不把它写入仓库、知识、fixture 或报告；只写入当前客户端支持的本机配置。
+- 失败时说明准确阻断和下一项最小动作，不用重装掩盖环境、凭据、权限或网络问题。
+
+## 安装 MCP Server
+
+仅在 MCP Server 或客户端配置缺失、损坏时执行。安装程序不接收 SigNoZ URL 和 API Key，也不修改客户端配置。
+
+macOS 和 Linux 优先执行包内的 Python 脚本；npm 安装副本经 CLI 的 `python` 命令运行（见[安装副本的助手规则](../../../AGENTS.md#安装副本的助手规则)）：
+
+```bash
+python3 scripts/install_signoz_mcp.py
+```
+
+Windows 使用系统自带 PowerShell，不依赖 Python：
+
+```powershell
+powershell.exe -File scripts\install_signoz_mcp.ps1
+```
+
+当前工作目录不是内容根目录时使用脚本的绝对路径。只有需要改变默认用户级安装目录时才传入 `--install-dir <absolute-directory>`（PowerShell 为 `-InstallDir <absolute-directory>`）。
+
+脚本会自动：
+
+1. 识别 macOS、Linux 或 Windows 及 CPU 架构；
+2. 从组织 OSS 下载固定的 checksum 清单和对应压缩包；
+3. 校验 SHA-256 后安全解压；
+4. 返回供客户端配置使用的绝对 `command` 路径。
+
+支持 macOS 和 Linux 的 amd64、arm64，以及 Windows amd64；不受支持的平台应明确停止，不要改用名称相近的产物。
+
+脚本不可用时，可用系统原生工具完成同等步骤，但必须同时满足：只访问 `https://signoz-mcp.oss-cn-beijing.aliyuncs.com/`、先读取 `signoz-mcp-server_0.10.0_checksums.txt`、精确匹配当前平台文件名、SHA-256 一致后才解压。不要跳过校验，也不要把二进制或 checksum 复制进本仓库。
+
+## 接入当前客户端
+
+用当前客户端公开支持的 MCP 管理命令、界面或用户级配置接入。最小配置语义：
+
+```text
+server name     -> 目标环境对应的稳定名称
+command         -> 安装脚本返回的绝对路径
+SIGNOZ_URL      -> 已确认的 SigNoZ 地址
+SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
+```
+
+- Key 用客户端支持的本机持久方式保存，不回显，不写进仓库、项目配置、知识、fixture 或报告。
+- 测试和正式环境分别配置，不复用或覆盖凭据；默认连接缺凭据时只要该环境的 Key，不改用已可用的其他环境。
+- 增量修改已有配置，保留无关的 server 和字段；支持工具 allowlist 时只启用诊断需要的只读工具。
+
+## 重载与恢复
+
+配置完成后按客户端支持的方式重载；无法自动完成 Trust、启用或重启时，只把这一项动作交给用户。随后依次验证：客户端发现 server、command 可以启动、最小只读请求成功（例如 `signoz_list_services` 取 1 条服务，时间范围 1 小时，参数以当前工具声明为准）、精确 ID 能在目标环境查询。成功后直接回到原任务，不向用户展开安装和配置明细。
+
+| 现象 | 优先检查 |
+|---|---|
+| 客户端看不到工具 | 配置是否加载、server 是否启用、是否需要重载 |
+| server 启动失败 | command、文件存在性、平台架构、执行权限 |
+| 401 | 没有凭据或凭据无效；URL 与凭据是否属于同一环境，只请求目标环境的 Key，不换用其他环境的 Key |
+| 403 | 凭据有效但角色不够，只读查询至少需要 Viewer 级别；请使用者换用有读取权限的 Key |
+| 工具存在但报字段 / schema 错误 | 工具版本与说明不一致；重新读取当前工具声明或修复 MCP 版本，不沿用旧参数硬试 |
+| 查询不到目标数据 | 精确 ID、时间与环境是否正确 |
+| 网络失败 | DNS、代理、OSS 或 SigNoZ 服务状态 |
+
+只重做失败层及其后续验证，不重复已通过的步骤。
+
+## Windows 构建说明
+
+Windows amd64 压缩包由组织维护并托管于 `signoz-mcp.oss-cn-beijing.aliyuncs.com`，用于补足当前上游发行版没有 Windows 原生产物的情况。
+
+- 文件名：`signoz-mcp-server_windows_amd64.zip`，内容为 `signoz-mcp-server.exe`。
+- 上游：[SigNoZ MCP Server](https://github.com/SigNoz/signoz-mcp-server)，Apache-2.0 License。
+- 构建：Go Windows amd64、`CGO_ENABLED=0`，内嵌版本为 `v0.0.6-0.20260224044326-53d3bdfb5af6+dirty`；是组织构建，不是上游官方 v0.10.0 Windows Release。
+- 签名：当前 PE 文件没有数字签名，不应通过关闭系统安全策略绕过拦截。
+- 校验：安装时以同一 OSS 上的 `signoz-mcp-server_0.10.0_checksums.txt` 为准；仓库不保存二进制或 checksum 副本。
+- 验证范围：来源、架构和 hash；真实 Windows 客户端启动与最小只读查询尚未验证。
+
+产物来源、构建方式或发布责任变化时，先更新并审核本说明，再调整安装入口。

package/content/knowledge/common/topics/start-and-anchors.md

@@ -0,0 +1,19 @@
+# 从现象或截图开始
+
+还没有可信的执行锚点时读：怎样判断 ID 能不能直接用，以及按用户描述的现象决定先查什么。与[查询方法](../queries.md)配套。
+
+## 锚点可信度
+
+- 用户直接粘贴的 URL、ID 文本以及工具返回的结构化字段可以作为精确锚点。
+- 截图、OCR 和人工转抄得到的值只作为候选。先逐字符核对原始材料；`g/q`、`0/o`、`1/l` 等字符无法可靠区分时，向用户展示识别结果并请求确认或粘贴原始文本。
+- 截图候选第一次精确查询为零时，零结果不能证明没有执行。先复核锚点；锚点未确认前，不得通过扩大时间、切换环境或移除 `service.name` 来补偿可能的字符错误。
+- 确认锚点后再进入场景域，避免下游在错误 ID 上生成更完整但无关的分析。
+
+## 按现象决定先查什么
+
+- 用户明确描述报错、更新失败、内存超限、OOM 或 `MemoryLimitExceeded` 时，先在已确认的环境、时间、`service.name` 和资源锚点内查询 ERROR 日志，收集全部精确命中的执行，从结果提取 traceId、chainId、taskId、执行类型或其他执行 ID，再精确读取 trace。第一次没有命中时，只在同一环境、时间、服务和资源锚点内去掉 severity 限制查一次；不能先做全局错误搜索，也不能先挑最慢的成功 trace。
+- 上述错误首查顺序用于尚未锁定执行的资源发现。已有精确失败 trace/task 或直接错误记录时，复用现有记录，只补尚未确认的提交、阶段或失败条件；不为重复确认报错先查 ERROR、再查同 span 的全级别业务日志。需要生命周期记录时，一次精确查询所需记录。
+- 预览、查看、更新、ETL 等执行类型用于防止不同运行的 trace、log 和 Metric 串线，是执行记录的上下文，不是用户必须预先选择的调查分支。同一资源和时间窗内的多个执行如果具有相同失败签名和计算链路，可以联合解释；不能仅因执行类型不同就请求用户消歧。只有不同执行指向不同原因且用户目标无法推断时，才展示差异并询问。
+- 用户明确描述慢、卡顿或耗时回归，且没有失败信号时，优先按入口、资源锚点和时间寻找 trace，再沿关键路径读取关联日志或 Metric。
+- 用户只说“性能问题”时，在受控范围内浅分型成功慢执行与失败执行，展示仍然可信的候选差异；不要替用户默认选择最慢或最新的一类。
+- engine Metric 用来解释已经锁定的执行，不是发现业务执行的第一入口。只有已经取得 taskName、Metric 链接或精确 trace 关联时才查询 MetricOuts。

package/content/knowledge/common/workflow.md

@@ -0,0 +1,22 @@
+# 通用 · 性能排查入口
+
+用户说慢、超时、内存超限、OOM、资源消耗异常或性能回归时，从这里找方向。这里只是提示和容易踩的坑，没有必须按顺序走完的步骤，材料够了就直接回答。
+
+## 从哪里开始
+
+- 环境、时间、历史对比的默认值见[公共查询规则](queries.md)的“默认值速查”。用户说“之前没超限”“最近变慢”，就已经是在要历史对比，不用等他再说一句“帮我对比”。
+- 场景清楚就直接进对应的域：[分析表](../dataset/workflow.md)、[组件](../component/workflow.md)、[仪表板](../dashboard/workflow.md)、[更新](../update/workflow.md#更新性能排查)。给的是企业 ID 或 dagId，就从更新进。
+- 只有 trace、执行链接，或者看不出是哪个场景，先读[场景识别](signals.md)。仪表板组件预览入口要按[来源判定](signals.md#仪表板组件预览入口)分流，光看最外层 HTTP span 或 `previewComponent` 这个 span 名分不出来。
+- 用户只给了资源，或者只说“有性能问题”，先挑几条候选执行看看：属于哪个场景、成功还是失败、是 OOM 还是 timeout。不要直接深挖最慢的成功执行。用户已经说了内存超限、OOM、保存失败，就用失败签名作为第一次检索条件，执行类型只当背景信息。
+- 只想拿到或看懂一份 Metric，直接看[引擎知识](../engine/workflow.md)。
+- 实时查询被工具、连接或鉴权挡住了，看[配置 SigNoZ MCP](topics/setup-signoz-mcp.md)，弄好再继续。
+
+## 易错点
+
+- OOM、超时、行数上限是直接失败条件，不是根因。报错位置多半在引擎，原因多半在业务场景：在引擎里看清撞了什么线以后，回到场景域找是什么让计算变得这么大：分析表是哪个步骤放大了数据，更新是哪个节点或哪个上游，组件和仪表板是查询、筛选、参数或绑定。建议也要落在这一层。
+- 已取消或没提交的执行（比如日志里有 `not submitted, skip finish`）根本没开始计算，有 task ID、Metric 链接或一个整数超时时长都证明不了算过。这时该解释的是取消链、等待或准入，没必要再去找计算统计。
+- 慢或失败的引擎执行，一般要看一眼 Metric 才能讲清物理上发生了什么。如果只看到业务层的 `polars query timeout`，先补读这次执行的属性，或者从同一个 trace 的提交日志里找回 task，别急着认定 Metric 拿不到。
+- 用户说“之前没超限”“以前正常”，但近几天找不到这个对象成功的记录时，就直接告诉用户：近 N 天没找到成功记录，和“之前正常”对不上，请他确认是哪张表、什么时候开始异常。不要顺着用户的说法去解释“为什么这次变了”。
+- 单次失败不需要成功样本。用户要求对比，或者手上正好有可比的成功执行，再去对比，目标和基线各自固定自己的范围。
+- 业务解释和 Metric 谁也替代不了谁：慢 span 只告诉你慢在哪一段，Metric 只解释进入引擎以后的事。
+- 别的执行类型只是错误签名相同、没有自己的计算记录时，只能当旁证，不要并进同一条原因链。

package/content/knowledge/component/README.md

@@ -0,0 +1,26 @@
+# 组件知识
+
+组件（图表）的数据请求：图表编辑时的查询，以及走仪表板组件预览入口的仪表板以外的图表预览。来自仪表板的组件预览归仪表板域。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 这类问题从哪里入手 | [workflow.md](workflow.md) | 组件取数排查入口：入手提示、常见现象的候选假设、易错点 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 组件、数据绑定与关联分析表的业务概念；调查关系 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出组件入口：接口、span、attribute、`reportId` 与请求上下文的含义 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | 什么情况下不能由 span 或字段直接下结论；调查时要保留的信息 |
+| 写查询、选取证路径 | [queries.md](queries.md) | 在 SigNoZ 中怎样组合组件入口与资源标识取证 |
+
+## 展开明细
+
+本域没有展开明细，所有内容都在上面的槽位里。
+
+## 关联
+
+- 相关知识域：[仪表板](../dashboard/README.md)：仪表板组件预览入口来自仪表板时（占绝大多数）
+- 相关知识域：[分析表](../dataset/README.md)：组件关联的查询表
+- 相关知识域：[引擎](../engine/README.md)：进入计算后的 Metric
+- 相关知识域：[通用](../common/README.md)：仪表板组件预览入口的来源判定

package/content/knowledge/component/concepts.md

@@ -0,0 +1,22 @@
+# 组件 · 概念与关联
+
+回答“这是什么、彼此怎么关联”。
+
+## 业务概念
+
+- 组件以 `widgetId` 或 `component.id` 为主要锚点，并绑定一个或多个查询表。
+- 组件查询可能携带筛选、联动、权限、聚合、排序和分页上下文。
+- 组件慢既可能来自本次查询，也可能来自所依赖分析表的状态或更新。
+
+## 调查关系
+
+```text
+widgetId / component.id
+  → 数据绑定与查询上下文
+  → component query execution
+  → analysis table
+  → Query
+  → engine task
+```
+
+不能因为 trace 中出现组件 span 就排除 dashboard 入口，也不能因为底层表正在更新就直接判定更新是根因。

package/content/knowledge/component/conclusions.md

@@ -0,0 +1,11 @@
+# 组件 · 能下什么结论
+
+回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么，结论能下到哪一步”。
+
+## 各类材料能说明什么
+
+组件配置说明可能发起哪些查询，trace/log 记录本次发起的查询，Metric 展示计算过程。按 ID、时间窗和执行关联核对这些材料后，再合在一起解释。
+
+## 调查时保留
+
+优先保留入口 route、请求上下文、组件 ID、绑定表、report ID、筛选/联动摘要、关键 span、耗时、错误和 Query 关联。

package/content/knowledge/component/queries.md

@@ -0,0 +1,7 @@
+# 组件 · 查询方法
+
+回答“怎样取证、怎样查询”。
+
+## SigNoZ 查询线索
+
+遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间，在业务 server 的 `service.name` 下组合组件入口 route、`editComponent`/`previewComponent`/`queryData` 与 `component.id` 或 widgetId。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)定向补取父子链中的上下文属性，不只读取 HTTP 根 span。

package/content/knowledge/component/signals.md

@@ -0,0 +1,75 @@
+# 组件 · 入口与信号
+
+回答“怎样认出入口，各个 span、attribute、日志和字段是什么意思”。
+
+## 场景识别
+
+已确认的入口包括：
+
+- `POST /v2/design/widget/data`：图表编辑时的取数；
+- `POST /v2/external/widget/data`：仪表板组件预览入口（代码里叫外部组件取数），绝大多数来自仪表板，少数是仪表板以外的图表预览，需要结合请求上下文区分；
+- `POST /v2/query/data`：`queryData` 通用组件查询入口，不能仅凭 span 名补全画布或筛选器上下文。
+
+已确认的特征 span 包括 `editComponent`、`previewComponent` 和 `queryData`。组件计算链路还可能出现 `getComponentMatrixData`。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
+
+仪表板组件预览入口的关键 attribute：
+
+- `data.endpoint=external_component_data`；
+- `data.request_context=component_preview`：从组件场景开始；
+- `data.request_context=dashboard`：完全交给仪表板场景；
+- `component.id`、`component.type`、`component.query.table_id`：组件和绑定表锚点。
+
+## 信号含义
+
+- `component.id` 或用户提供的 `widgetId` 用于关联组件资源；
+- `component.query.table_id` 表示组件查询绑定表，可用于进入分析表调查；
+- 仪表板组件预览入口的 `reportId` 与 request context 按[来源判定](../common/signals.md#仪表板组件预览入口)解释，不能把关联字段直接当作场景结论；
+- 筛选器、筛选、联动和权限 attribute 描述本次请求上下文，不直接证明它们造成性能问题。
+
+只有通用 Query 或 engine span，或者只有共享的 `tableId`，都不足以确认组件场景。
+
+## 组件计算的阶段
+
+仪表板组件预览入口（仪表板以外的图表预览也走这里）里，`previewComponent` 之下按顺序是这些阶段：
+
+```text
+POST /v2/external/widget/data
+└─ previewComponent
+   ├─ data.component.resolvePublishedTable                              取已发布表
+   ├─ data.component.checkPublishedTableStatus                          检查已发布表的状态
+   ├─ data.component.buildControlContext                                把筛选器、联动整理成过滤条件
+   ├─ data.component.checkTableStatus                                   检查表是否可读
+   ├─ data.component.analyzeControlContext                              把过滤条件应用到输入表
+   └─ data.component.executeRequest                                     执行查询
+      └─ data.component.executeSingleQuery
+      └─ QueryExecutor → execute                                        引擎查询：query 提交任务，fetchBlock 轮询取结果
+```
+
+这是主干，实际 trace 里每段下面还会嵌套不少 span，比如活跃检查 `checkUpdatePolars` 通常挂在 `analyzeControlContext` 之下。用它判断时间花在哪一段：`executeRequest` 一般占 `previewComponent` 的大头，其次是 `analyzeControlContext`，其余几段很短。`executeRequest` 占大头说明时间在引擎。`QueryExecutor` 下的 `query` 只是把任务交给引擎，通常很短；之后反复 `fetchBlock` 取结果，引擎没算完时取到的是空块（`rowCount=0`），所以引擎计算的时间主要落在这些 `fetchBlock` 里，不是传数据慢。具体算在哪，按 `taskName` 取 Metric，见[引擎知识](../engine/README.md)。引擎之前的活跃检查 `checkUpdatePolars` 见[分析表 · 活跃检查](../dataset/signals.md#活跃检查)。
+
+## 取数结果与失败
+
+`previewComponent` 上的 `result.status` 是本次取数的结果。图表编辑时（`editComponent`，路径是 `editComponent → data.component.executeSingleQuery → QueryExecutor`）没有 `result.status` 和 `error.class`，错误原文看出错 span 的 `status_message` 和同一 trace 的日志。
+
+| 取值 | 含义 |
+|---|---|
+| `success` | 取到数据 |
+| `empty` | 成功，但结果为空 |
+| `updating` | 底层表正在更新，没有返回结果 |
+| `error` | 失败，原因看 `error.class` |
+
+失败时 `error.class` 是根因异常的类名，常见的有：
+
+| `error.class` | 一般表示 |
+|---|---|
+| `TaskCancelledException` | 任务被取消，不是计算失败 |
+| `TableInvalidException` | 表当前不可用（默认消息是所在文件夹正在同步） |
+| `NoSuchEntryInfoException` | 引用的表不存在 |
+| `NoFieldFoundException`、`NoParameterFoundException` | 引用的字段或参数已不存在 |
+| `IllegalTableMarkedException` | 表被标红 |
+| `QueryTimeOutException` | 引擎查询超时 |
+| `MemInsufficientException` | 引擎内存不足 |
+| `JoinN2NException` | 关联出现多对多 |
+
+遇到未列出的类名，照错误消息原文说明，只凭类名猜出的含义要标明是推测。`result.status=error` 不一定是性能问题，`TaskCancelledException` 和 `TableInvalidException` 都与计算快慢无关。
+