29. 可观测入口、数据来源与权限边界

完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向平台管理员、运维人员与安全审计人员，说明 Zenova 的可观测数据从哪里来、在哪些页面查看、谁能看到哪些数据；如何读调用链（Trace）与阶段耗时；如何让外部客户端通过 OTLP 上报调用链，并与网关记录串联；上报字段不符合标准约定时如何声明数据映射；数据留存设置如何影响之后能查到的内容；以及审计归档与数据保护措施。单次请求、会话与智能体执行的排查操作见第 30 章，按现象排查的路径见第 31 章。

29.1 可观测入口与数据来源

经过平台网关的模型调用、MCP 调用、API 服务调用与 A2A 调用，以及员工在「对话」中与智能体的往来，都由平台自动记录，调用方无需改造。数据保存在客户环境内，按使用面分为管理后台入口与工作台入口。

管理后台入口

工作台入口

数据来源

• 调用记录：网关对每次调用全量记录，不采样。内容包括发起人、接入凭据、客户端、模型、结果、耗时分段、Token、费用、命中规则与上游尝试。
• 请求与响应报文：网关采集「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」四段。是否留存、留存多久由数据留存设置决定（29.5 节）。
• 规则命中：每次请求命中的流量规则、限额、内容护栏、恶意来源检查与站点防护策略。
• 会话：平台按会话标识把多轮调用串联；员工与智能体的对话、客户端上报的步骤都并入对应会话。
• 调用链：网关为每次模型调用生成一条调用链；客户端通过 OTLP 上报的 Span 并入同一条链（29.3 节）。
• 智能体运行事件：智能体的启动、停止、重启、配置下发等生命周期事件，以及定时任务的执行历史。

注意

• 调用记录与计量不受数据留存设置影响，始终完整保留；数据留存设置只控制报文正文。
• 可观测记录异步写出，不阻塞请求转发；请求详情的耗时分段中看不到记录本身的开销。
• 各页面只显示当前账号权限与租户范围内的数据，角色在「组织与权限」中分配（第 3 章）。

29.2 读调用链与阶段耗时

适用场景：需要判断一次调用慢在哪里，或确认某个步骤是否真的经过网关。

操作步骤

1. 在「运行总览 › 请求」中按请求 ID 搜索并打开该次调用。请求 ID 取自响应头 x-request-id，链路 ID 取自响应头 x-trace-id。
2. 切到「时延与成败」页签，读固定分段：接入层处理、排队、网关处理、失败重试、上游（流式含生成）、网关耗时、网关总耗时 / 端到端、首字延迟。
3. 需要看完整调用链时，从会话详情的「客户端轨迹」点击某一步进入链路详情；成员在工作台顶部导航「洞察 › 会话」中打开本人的会话后同样可以进入。
4. 链路详情左侧提供「树」「时间线」「图」「日志」四种视图；选中某个步骤，右侧在「详情」「输入输出」「属性」「评论」「分析」页签中查看模型、服务商、时长、结束原因、输入输出、属性与事件。所选步骤失败时多出「错误」页签。

你会看到

• 各分段以毫秒整数记录，低于 1 毫秒的开销显示为 0 ms；非流式调用的「首字延迟」显示「未记录」。
• 「路由与改写 › 上游尝试」中每次尝试的「耗时」计到上游返回响应头为止；「上游」分段计到读完整个响应体为止，两者含义不同。
• 链路详情页头给出状态、上报方、智能体（未关联时显示「未关联」）、模型与供应商、终端用户与总耗时，下方一行列出「观测记录数」「Token（输入 / 输出）」、成本、首 Token 耗时、开始时间、环境、会话（「查看会话」）与「采集范围」。
• 网关侧的模型调用步骤为一条 llm.attempt，「属性」中可展开 genAiSystem、genAiRequestModel、genAiInputTokens、durationMs、selfTimeMs 等字段。「采集范围」显示「未识别到下游跨度」时，表示链路中只有网关自身的记录。
• 「分析」页签列出「耗时异常的步骤」与「高频重复调用」，作为排查线索。

注意

• 网关侧只提供固定的耗时分段，没有按工具、检索逐段的 Span 分解；Span 级分解只有客户端主动上报的数据才有。
• 网关自身产生的 Span 不采集输入与输出，右侧显示「未采集」；需要看报文请回请求详情的「请求」页签。
• 一次执行记录超过 100 条事件时，页面提示只展示最早的 100 条，靠后的步骤可能没显示。
• 客户端的 Span 可能比网关 Span 晚到。刚发生的调用如看不到下游跨度，稍后再打开。

29.3 用 OTLP 接入客户端调用链

适用场景：需要把外部客户端内部的工具调用、检索等步骤与网关的模型调用放进同一条调用链。

前提

• 客户端能发送 OTLP/HTTP（JSON 或 Protobuf）格式的 Trace。
• 成员可以在工作台为该客户端创建 API 密钥（第 19 章）。

操作步骤

1. 在工作台顶部导航「模型」中打开目标模型，点击「获取 API 密钥」。
2. 在「挂到哪个客户端」中选择「新建客户端」，填写客户端名称，类型选择「通用观测协议」，点击「创建」。
3. 弹窗同时给出 API 密钥和上报配置。上报配置形如：

POST https://<网关地址>/api/v1/public/otel/v1/traces
Authorization: Basic <上报密钥>

上报密钥只显示一次，请立即保存到客户端的密钥管理中。

1. 客户端调用模型时，在请求头中带上 W3C traceparent，使网关调用与客户端 Span 使用同一个 Trace ID：

traceparent: 00-<32 位十六进制 Trace ID>-<16 位十六进制父 Span ID>-01

1. 客户端把本地的工具调用、检索等 Span 按同一 Trace ID 上报到第 3 步的地址。
2. 已创建的客户端在工作台「洞察 › 我的客户端」中查看与管理。

你会看到

• 网关响应头 x-trace-id 的值等于请求中 traceparent 携带的 Trace ID；不带 traceparent 时网关自动生成并在 x-trace-id 中返回。
• 请求详情「概要」中的「链路 ID」与该 Trace ID 相同。
• 上报成功后，链路详情中网关侧与客户端侧的 Span 出现在同一条调用链里。

注意

• 上报密钥与 API 密钥是两种凭据：前者只能上报观测数据，不能调用模型。删除客户端后上报密钥随之失效。
• 若客户端未传 traceparent，两侧分属不同 Trace，只能按时间与会话关联。
• 客户端上报的采样比例由客户端自身的 OpenTelemetry SDK 配置决定，平台按收到的 Span 原样展示。
• 上报接口不接受无凭据的请求，只提供 traces 上报路径，不提供 OTLP metrics 上报路径。
• 平台内的智能体由平台直接记录，无需另行配置 OTLP。

常见框架

• AgentScope 1.x / 2.x 与 openJiuwen 的 observability 链路按 OpenTelemetry 生成式 AI 标准约定上报，接上即可识别模型调用、工具调用与会话，无需额外配置。
• AgentScope 1.x：会话编号取自 agentscope.init(run_id=…)，同一进程内的所有会话共用这一编号。需要按会话区分时，每个会话使用独立的 run_id 初始化；或升级到 2.x，由 AgentState.session_id 提供会话编号。
• openJiuwen 单智能体模式：每轮对话都需用 open_agent_run_span / close_agent_run_span 包住，否则框架不会上报任何步骤。
• openJiuwen 的 tracer_otel 链路：会话编号与工具入参、结果不在标准位置，需要到「数据映射」页声明（第 29.4 节）。

29.4 声明数据映射

适用场景：客户端已按第 29.3 节接入，但上报的步骤没有按标准约定填写会话编号、模型或工具字段，导致会话、用量或正文显示不完整。数据映射把这些步骤中的客户自有属性对应到平台识别的字段，客户端无需改代码。

前提

• 账号为租户管理员。数据映射是租户级配置，作用于本租户收到的全部上报数据，与接入的客户端和上报密钥无关。
• 已有该来源的上报数据；尚无数据时，准备一份该客户端导出的 OTLP JSON 样例。

操作步骤

以 openJiuwen tracer_otel 链路为例：服务名 risk-agent，上报组件 openjiuwen.tracer.otel，会话编号放在属性 openjiuwen.session_id，工具入参与结果放在 openjiuwen.agent.inputs、openjiuwen.agent.outputs。

1. 进入「管理后台 › 观测中心 › 数据映射」。识别率偏低时，「运行总览」顶部也会出现提示，点其中的「配置数据映射」进入同一页面。
2. 在「未识别来源」中找到 risk-agent · openjiuwen.tracer.otel 一行，该行列出最近 24 小时的步骤数与识别率。点该行的「新建映射」，「适用条件」会按该来源自动填好（上报组件 等于 openjiuwen.tracer.otel）。也可以点页面右上角的「新建映射」从空白开始。
3. 填写映射名称，例如「风控智能体」。在「适用条件」中可点「+ 条件」继续按服务名、上报组件或属性收窄范围，全部条件同时满足的步骤才套用此映射；区块下方显示最近 24 小时命中的步骤数与来源服务数。
4. 在「会话」区块中，将「会话编号取自」选为 openjiuwen.session_id。下拉只列出实际出现过的属性，旁边给出样例值与覆盖比例。默认勾选「同一调用链里没有会话编号的步骤，沿用这条调用链的会话编号」；「用户编号取自」按需选择，不需要时保留「不设置」。
5. 在「步骤分组」中选中 execute_tool 分组，在右侧将「名称匹配」设为「以…开头」execute_tool，「类型」选「工具调用」，再为各字段选择取值来源：「工具名」选 gen_ai.tool.name，「工具入参」选 openjiuwen.agent.inputs，「工具结果」选 openjiuwen.agent.outputs。带 * 号的字段必须填写；各类型包含哪些字段以页面列出的为准。
6. 尚无上报数据时，点右上角「粘贴样例」，粘贴 OTLP JSON 样例，按样例中的步骤完成第 4、5 步。
7. 点「预览」，核对识别率与各分组的变化。确认无误后点「保存并启用」；暂不启用时点「保存」，之后在列表中启用。

你会看到

• 预览给出识别率与「有会话编号的步骤」占比在保存前后的对比（例如 12% → 100%），以及每个分组由「未识别」或「部分」变为「已识别」。仍未完整识别的分组列出缺少的字段，可返回继续修改。
• 若部分步骤已被排在前面的映射接管，预览提示接管它的映射名称与步骤数，并提供「移到最前」。
• 启用后，之后收到的数据在「运行总览」「使用洞察」与会话详情中显示轮次、模型、Token 与正文。
• 「已声明映射」中该映射的命中数与识别率持续更新；该来源的识别率上升，达到 100% 后不再出现在「未识别来源」中。

注意

• 一个步骤只套用按顺序第一个命中的映射。在「已声明映射」中通过行菜单的「上移」「下移」调整顺序，范围宽的映射应排在范围窄的映射之后。
• 映射只对保存之后收到的数据生效，已入库的数据不会重新计算。
• 已按标准约定识别的步骤无需配置，未声明的分组仍按平台内置规则识别。
• 声明为正文的属性按正文处理，仍受数据留存设置约束（29.5 节）。
• 新建、修改、启停、调整顺序与删除映射都记入操作审计。
• 识别率按最近 24 小时各分组的全部步骤数加权计算。

29.5 数据留存

适用场景：需要控制之后的调用留下多少报文正文、留存多久，或需要理解为什么某些请求看不到报文。

前提：以租户管理员登录。数据留存设置属于租户设置，是租户级全局配置，保存后对所有成员的后续调用生效，建议在变更窗口内修改。

操作步骤

1. 进入「管理后台 › 系统设置 › 全局设置 ›「数据留存」页签」。
2. 在「正文留存」中选择：全部留存（默认）、按比例留存、不留存。选「按比例留存」时在「留存比例」中填写 1～99 之间的整数。
3. 在「内容留存时长」中填写天数（1～3650），或开启「永久留存」。
4. 在「调用记录留存时长」中填写天数，或开启「永久留存」。调用记录不可关闭，只能设置留存天数。
5. 点击「保存」，在「确认修改数据留存设置」对话框中阅读影响预估后确认。

你会看到

• 确认对话框按变更类型给出提示：缩短留存时长时列出将删除的调用记录、报文与会话正文的大致数量，删除在下一次清理时执行，不可恢复；改为按比例留存时说明之后约多少比例的会话会留存正文；不涉及删除时提示「本次修改不会删除已有数据」。
• 选择「不留存」后，会话标题在下一个清理周期清空，其余已存正文仍按内容留存时长清理。
• 保存成功后提示网关节点将在约 1 分钟内生效。

对查询结果的影响

注意

• 留存比例只影响正文。按比例留存时，用量、费用、成功率等统计仍覆盖全部调用，不需要按比例换算。
• 会话诊断（使用洞察）依赖会话内容；正文留存比例越低，能覆盖的会话越少。
• 页面底部显示「尚未修改，使用系统默认」时，表示当前值并非管理员保存过的配置。

29.6 审计归档与完整性校验

适用场景：需要证明审计记录未被篡改，或需要长期留存审计数据。

操作步骤

1. 进入「管理后台 › 审计与合规 › 操作审计」，点击「归档与校验」。
2. 读「完整性校验」区块：运行状态、最近一次校验时间、结果、覆盖范围与问题明细。需要立即校验时点「立即校验」。
3. 在「归档批次」中按类别（审计日志、调用日志）查看封存日期、记录时间范围、记录条数、保护状态与「复核结果」，可「下载批次数据」与「下载批次清单」。

你会看到

• 未配置归档存储时，对话框顶部提示「未配置归档存储，审计记录未封存。请联系运维人员配置归档存储。」
• 问题明细按分片、序号与审计记录列出问题，例如序号不连续、前序哈希不一致、分片头与链尾不一致、记录正文被改动。
• 尚无批次时「归档批次」显示「尚无归档批次」。

注意：归档存储属于部署配置，需运维人员在平台侧完成；租户管理后台只做查看、下载与手动校验。审计查询、导出与留存的完整说明见第 32 章。

29.7 平台数据的权限边界

角色与可见范围

• 侧栏与「运行总览」的页签按成员持有的权限显示：「使用洞察」需要「使用洞察 · 查看」，「采集设置」需要「采集设置 · 查看」（各内置角色的权限见第 3.5.2 节）。「全局设置」中的「数据留存」页签属于租户设置，只对租户管理员开放。
• 平台级页面只对平台管理员开放，租户管理员直接访问这些地址时会被带回「运行总览」，这是预期行为。
• 会话详情中的「网关调用」页签与单轮链路只在全租户视角提供；成员的个人视角不含这两部分。

数据保护措施

• 请求头中的凭据在采集时抹除，页面显示为「已抹除·长度 N」，不显示原值。
• MCP 令牌在活动记录中只显示指纹前缀，不显示全量。
• 每次读取报文正文或差异都写入审计记录。
• 导出类操作（报表导出、汇报导出、会话导出）记录在操作审计中。
• 链路详情的「分享」只生成一个指向该执行的链接：打开后显示执行 ID 与分享令牌，查看内容仍需登录并具备相应权限。

接入前应与业务方约定：哪些输入输出允许留存原文、敏感数据与内部地址如何脱敏、各角色可查看的范围、导出与归档的保留期限、谁可以创建和删除上报客户端。「已脱敏」应以实际报文样本证明，不能只依据配置开关判断。

29.8 告警与通知的位置

适用场景：需要在策略大量拦截、规则执行出错、服务异常等情况下收到通知。

告警由三部分组成：「管理后台 › 运行与排障 › 告警规则」中的规则与静默、同一页面「通知渠道」页签中的渠道，以及「运行总览 › 告警」页签中的告警记录。

1. 进入「管理后台 › 运行与排障 › 告警规则」，切到「通知渠道」页签，点「新建渠道」，选择类型（钉钉 / 飞书 / 回调地址 / 企业微信 / 邮件），勾选接收的事件类型并填写地址。创建后在该行「⋯」菜单中点「发测试消息」，收到后点「确认收到」，状态变为「已验证」。
2. 回到「告警规则」页签，对内置告警（例如「护栏拦截了一次内容」）选择渠道并打开「启用」开关。
3. 点「新增规则」，选择指标（例如「策略拦截占比」「策略执行出错」「模型服务尝试失败率」），设置取值方式、统计窗口、比较方式、阈值、持续时长、严重级与通知渠道。

注意

• 告警规则的「通知渠道」只列出已启用、已验证并订阅了「告警」事件的渠道。
• 告警规则只作用于本租户。
• 分组维度、取值方式、静默与告警记录的完整说明见第 32 章；流量突增与熔断场景的用法见第 30.9 节。

能力说明

---

上一章：28. 用量与成本 · 下一章：30. 网关请求、会话与根因定位