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

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

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

本章内容：本章面向平台管理员、运维人员与安全审计人员，说明可观测数据从哪来、在哪些页面看、谁能看到；Trace 与阶段耗时怎么读；如何让客户端用 OTLP 上报调用链并与网关记录串联；上报字段不符合标准约定时如何声明数据映射；采集比例与留存策略会怎样影响可查询的数据；以及平台数据的权限边界。单次请求与会话的排查操作见第 20 章。

19.1 可观测入口与数据来源

经过网关的每一次模型调用、MCP 调用与 API 服务调用都由网关自动记录，调用方无需改造。数据保存在客户环境内，在以下入口查看：

数据来源

• 调用记录：网关对每次调用全量记录，不采样。内容包括发起人、接入凭据、客户端、模型、结果、耗时分段、Token、费用、命中规则与上游尝试。
• 请求与响应报文：网关采集「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」四段，是否留存与留存多久由数据留存设置决定（19.5 节）。
• 规则命中：每次请求命中的路由、流量限额、内容护栏、恶意来源检查与站点防护策略。
• 会话：网关按会话标识把多轮调用串联，客户端上报的步骤并入同一会话。
• 客户端调用链：客户端通过 OTLP 上报的 Span，只有开启上报的客户端才有（19.3 节）。

注意

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

19.2 读 Trace 与阶段耗时

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

操作步骤

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

你会看到

• 各分段以毫秒整数记录，低于 1 毫秒的开销显示为 0 ms。
• 非流式调用的「首字延迟」显示「未记录」。
• 「路由与改写 › 上游尝试」中每次尝试的「耗时」计到上游返回响应头为止；「上游」分段计到读完整个响应体为止，两者含义不同。
• Trace 详情中网关侧的 Span 为一条 llm.attempt，属性里可展开 genAiSystem、genAiRequestModel、genAiInputTokens、durationMs、selfTimeMs 等字段。「采集范围」标注是否识别到下游跨度。

注意

• 网关侧只提供固定的耗时分段，没有按模型、工具、检索、治理逐段的 Span 分解。Span 级分解只有客户端主动上报的数据才有。
• 网关自身产生的 Span 不采集输入与输出，右侧显示「未采集」。需要看报文请回请求详情的「请求」页签。
• 客户端的 Span 可能比网关 Span 晚到。刚发生的调用如看不到下游跨度，稍后再打开。
• 页面可能提示「内容加载失败，请重试」，点「重试」即可。

19.3 用 OTLP 接入客户端调用链

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

前提

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

操作步骤

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 步的地址。

你会看到

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

注意

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

常见框架

• 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 链路：会话编号与工具入参、结果不在标准位置，需要到「数据映射」页声明（第 19.4 节）。

19.4 声明数据映射

适用场景：客户端已按第 19.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% 后不再出现在「未识别来源」中。

注意

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

19.5 采集比例与数据留存

数据留存设置决定之后的调用会留下多少报文正文、留存多久。它不影响调用本身，也不影响调用记录、Token 与计费。

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

操作步骤

1. 进入「管理后台 › 系统设置 › 全局设置 ›「数据留存」页签」。
2. 在「正文留存」中选择：全部留存（默认）、按比例留存、不留存。选「按比例留存」时在「留存比例」中填写百分比。
3. 在「内容留存时长」中填写天数，或开启「永久留存」。
4. 在「调用记录留存时长」中填写天数，或开启「永久留存」。调用记录不可关闭，只能设置留存天数。
5. 点击「保存」。

对查询结果的影响

注意

• 留存比例只影响正文。按比例留存时，用量、费用、成功率等统计仍覆盖全部调用，不需要按比例换算。
• 缩短留存期后，超期的正文会被清理且不可恢复。缩短前请确认审计与合规要求。
• 会话诊断依赖会话内容；正文留存比例越低，诊断能覆盖的会话越少。
• 页面上有「尚未修改，使用系统默认」的提示时，表示当前值并非管理员保存过的配置。

19.6 归档与完整性校验

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

操作步骤

1. 进入「管理后台 › 审计与合规 › 操作审计」。
2. 点击「归档与校验」，查看审计日志与调用日志的封存进度。
3. 读「完整性校验」区块：运行状态、最近一次校验时间、结果、覆盖范围与问题明细。
4. 需要立即校验时点「立即校验」；归档批次在下方列表中查看。

你会看到

• 未配置归档存储时，对话框顶部提示「未配置归档存储，审计记录未封存。请联系运维人员配置归档存储。」
• 「调用日志」一行给出待封批次数与最早待封日期。
• 「完整性校验」给出运行状态、最近一次校验时间与问题明细（例如分片头与链尾不一致、分片序号）。
• 「归档批次」列表在尚无批次时显示为空。

注意

• 归档存储属于部署配置，需运维人员在平台侧完成。租户管理后台只做查看与手动的完整性校验。
• 完整性校验发现问题时，先记录问题明细中的分片与序号，再联系平台侧排查。

19.7 平台数据的权限边界

角色与可见范围

• 租户管理员可见本租户全部观测数据与配置项；「数据映射」只对租户管理员开放。
• 运营、财务与审计角色按各自职责只可见对应面板；财务角色通常只看到费用类指标与排行，运营角色只看到本人发起的请求。
• 成员在工作台只能看到本人数据，「洞察」中的 Trace 也只覆盖本人发起的调用。
• 平台级页面（运行监控、平台运行日志）只对平台管理员开放。租户管理员直接访问这些地址会被重定向回「运行总览」，这是预期行为。

数据保护措施

• 请求头中的凭据在采集时抹除，页面显示为「已抹除·长度 N」，不显示原值。
• MCP 令牌在活动记录中只显示指纹前缀，不显示全量。
• 每次读取报文正文或差异都写入审计记录。
• 导出类操作（报表导出、汇报导出）记录在操作审计中。

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

19.8 告警与通知渠道

适用场景：需要在策略大量拦截、规则执行出错、故障转移变频繁或模型调用失败率升高时收到通知。

操作步骤

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

你会看到

• 渠道列表给出名称（下方为掩码后的地址）、类型、验证状态、最近投递（时间与结果）、事件类型与创建时间。
• 投递失败时「最近投递」给出原因，例如「网络不可达」。
• 事件类型共九种：告警、配额软超限、配额硬超限、用量日汇总、智能体运行完成、导出完成、预算超限、会话诊断周报、公告，默认勾选「告警」。

注意

• 告警规则的「通知渠道」只列出已启用、已验证并订阅了「告警」事件的渠道。
• 比例类指标（如「策略拦截占比」）的阈值填 0 到 1 之间的小数，例如 0.2 表示 20%。
• 告警规则只作用于本租户。

能力说明

---

上一章：18. 用量与成本分析 · 下一章：20. 网关请求、会话与根因定位