Article body
正文
Agentic BI 将业务提问推进为可执行、可复核的分析任务。 在衡石的分析体系中，HENGSHI SENSE 提供数据模型、指标、HQL 与可视化资产，Data Agent 承接意图理解、资源选择与分析工具调用，最终形成图表和解读。全链路追踪与可观测设计，需要围绕这条完整任务链路，说明每一步用了什么、执行到哪里、花了多久，以及结果是否满足业务要求。
观测主线： 业务目标与口径 → 资源选择与授权 → 模型与工具协作 → 查询执行 → 图表和分析交付 → 状态反馈与复核。这是分析任务的观测视图，实际环节可能存在分支、重复与依赖，随运行模式、数据来源和接入方式变化。
一、Agentic BI 要观测完整的分析任务
一次分析可能包含多轮资源检索、模型推理与工具执行。可观测性既要记录耗时、失败与重试，也要帮助团队核查使用的指标、数据范围和执行身份。回答开始出现、数据结果返回、图表可用和分析交付完成，应作为不同的观察点；单一总耗时无法解释这些差异。
| 观察环节 | 需要确认的内容 | 优先收集的证据 |
|---|---|---|
| 资源与语义检索 | 是否找到了相关数据集、指标与业务知识，是否反复寻找同一资源。 | 执行日志中的资源选择与工具调用信息。 |
| 意图与条件 | 时间、组织、维度与统计口径是否明确，是否因歧义反复补充或重试。 | 原问题、当前页面、追问条件及模型配置。 |
| 身份与授权 | 请求采用哪个身份，该身份能访问什么资源和数据。 | 实际账号、应用数据权限模式与拒绝信息。 |
| 查询生成 | 是否生成了合适的 HQL／指标查询，是否出现无效调用或重复修正。 | 执行记录中可取得的查询与错误信息。 |
| 查询执行 | 数据源、加速引擎或复杂计算是否耗时，筛选是否有效。 | 可取得的 SQL、执行计划与数据源侧记录。 |
| 结果与展示 | 结果是否已经返回，是否仍在生成解读，图表与页面是否过重。 | 网络请求完成情况、返回规模与浏览器表现。 |
各环节可能重复、交错或存在依赖。追踪设计需要呈现任务与调用的关联，区分等待时间、执行时间和重试开销，再判断关键路径。是否能够并行，要以实际依赖为依据；权限与查询条件尚未确定时，不应为了减少等待而提前取数。
二、把任务、阶段与执行证据连起来
任务关联是观测的基础
建设全链路观测时，集成方案应约定任务或请求标识，并将可取得的阶段记录、工具调用与查询信息关联起来。对可控制的跨服务调用保留父子关系与时间边界，再与衡石实际可取得的执行日志对应；可关联的范围以所用接口和部署能力为准。
- 任务层： 记录业务目标、入口、执行身份与明确的完成条件，说明本次分析要交付什么。
- 阶段层： 记录起止时间、成功或失败状态、重试及原因信息，区分尚在等待与已经执行。
- 对象与依赖层： 关联相关指标、数据集、工具和输出对象，并说明前后依赖，便于复核计算口径与关键路径。
先收集问答执行记录
遇到问数失败或异常，衡石公开手册给出了三类排障材料：对话卡片中的执行日志、浏览器 Fetch／XHR 中的异常响应，以及管理员限时开启系统调试后导出的日志。它们分别帮助检查问答过程、接口返回和服务端运行情况。收集时应同时说明问题发生时间、使用入口与复现步骤。
同一问题在不同入口的运行条件可能不同。排查时先固定账号、页面和会话，完成一次可重复的复现，再改变模型、数据范围或提示词。这样才能判断差异来自哪里，而不会把多项变化混成一次“调优”。
再核查实际执行的查询
对于落到图表上的分析，衡石提供查看 SQL 及 explain 执行计划的入口。分析人员可以检查时间条件、关联方式与聚合表达式，再结合数据源的执行情况判断是否需要调整数据模型、索引或计算路径。该能力针对相应图表与查询入口，不能据此假定所有 Agent 步骤都已有统一的分布式追踪视图。
衡石的指标与 HQL 能力也有助于缩小排查范围。团队可以先用已确认的分析对象核对结果，再检查 Agent 对问题和筛选条件的理解。指标定义不一致、数据查询缓慢与模型回答偏差，需要由不同负责人处理。
三、用分段耗时验证关键路径
下面保留一组用于讲解的时间值。它们只用于说明计时方法，不代表衡石实测结果、完整内部执行顺序或响应承诺。
| 示例观测项 | 示例耗时 | 能说明什么 |
|---|---|---|
| 资源检索 | 200毫秒 | 记录该次检索自身的耗时。 |
| 意图处理 | 150毫秒 | 记录该次意图处理自身的耗时。 |
| 查询生成 | 300毫秒 | 记录该次生成查询自身的耗时。 |
| 结果组装 | 100毫秒 | 记录该次组装展示结果自身的耗时。 |
四项相加是750毫秒，但这里没有包含数据查询、授权处理、网络传输及可能的重试。因此，750毫秒不是完整问数耗时。若部分工作重叠，还需要结合各段起止时间和依赖关系计算实际等待，不能直接把最长一段当作并行后的总耗时。
业务验收可以分别记录提交问题到首次有效反馈、数据结果返回、图表可用和解读完成的时间。对于持续输出的问答，首次出现文字与完成分析也应分别观察。团队需要先定义业务真正关心的完成点。
四、以一条 Agentic BI 任务验证观测设计
以下为虚拟场景，不代表真实客户案例。 销售经理希望系统完成经营看板分析，并反馈其中一次问数等待了8秒。项目组先固定账号、问题、时间范围与数据批次，再沿着任务链路检查阶段记录、分析对象和输出结果，验证观测设计能否解释这次等待。
| 证据表现 | 下一步动作 |
|---|---|
| 执行记录显示反复寻找数据或改写条件 | 核查指标名称、数据集知识和问题歧义，缩小可用资源范围后复测。 |
| 模型已给出查询，但数据结果迟迟未返回 | 查看相应查询与执行计划，检查关联层次、过滤范围和数据源负载。 |
| 查询已返回，页面仍长时间等待 | 检查返回规模、图表数量、浏览器渲染及后续解读步骤。 |
| 仅部分角色或访问入口出现异常 | 核对实际身份、数据权限模式、嵌入配置和接口响应，保持原有授权边界。 |
完成调整后，团队用相同条件重复测试，并同时核对数值、筛选和访问范围。一次变快只能证明该场景得到改善；是否适合更多用户和更复杂问题，还需要另外验证。
五、从单次追踪到持续运营
单条追踪解释一次分析，聚合后的观测用于发现反复出现的问题。团队可按问题类型、数据来源与时间窗口汇总耗时，观察 P95、P99 等长尾指标，并在统一的任务完成口径下统计失败、重试与交付情况。结果是否算对、权限是否正确，还需要结合业务样本与角色验证，不能仅凭调用成功判断。
日志访问与留存也需要管理。问题原文、查询条件和数据结果可能包含业务敏感信息，排障材料应按权限收集和共享；调试结束后关闭临时的详细日志。追踪与审计承担不同职责，留存时间应由企业的排障和合规要求分别决定。
衡石的 Agentic BI 能力将指标与 HQL 分析、数据授权、Agent 工具调用和可视化交付连接到实际业务任务中，执行日志与查询排查入口为可观测建设提供了实施基础。业务、数据与运维团队围绕同一条任务链路复核口径、状态、耗时与结果，才能持续改进分析服务的可用性和交付质量。