Gateway 调用证据
Rust Gateway 默认向 stdout 输出 powercontext.gateway-evidence.v1 JSON 行,运行日志使用 stderr。
无需额外部署观测平台。沿用现有日志采集器的轮转与保留策略;仅将 stdout 重定向到文件不会限制文件大小。
# 将证据与运行日志分开;采集器应配置有界保留。
./gateway/target/release/pc-gateway | your-existing-log-collector
# 显式关闭证据。启动诊断会说明证据覆盖缺失。
PC_GATEWAY_EVIDENCE=off ./gateway/target/release/pc-gateway生产应用装配 JsonEvidenceSink,不再使用测试/演示保留的无界 BufferedEvidenceSink。
最多保留 1024 条排队记录和 1 条写出线程持有的记录。接收的记录仅含有界标识符、数值和枚举,
序列化后每条含换行不超过 4096 字节。提交使用 try_send,队列满时丢弃新记录。
请求侧不执行 I/O,也不等待写出线程退出或队列排空。stdout 卡住最多占用一个写出线程,
不会持续增加线程或队列条目。Gateway 的请求/响应缓冲与并发仍有各自的资源限制。
每行包含 schema、operation=gateway.model_call、unit(call、attempt、delivery)、
event(同样的三个值)、outcome、duration_ms、evidence 和 loss。进程内累计的 loss.dropped、loss.write_failed、
loss.written 分别统计被丢弃的提交、失败或无法确认的记录写出、完成写入并 flush 的记录,
采样发生在当前行写出之前。恢复后的输出会携带此前的丢失计数;嵌入宿主也能在拥塞时读取
JsonEvidenceSink.stats()。执行身份不作为指标标签。
这些记录是尽力输出:溢出可能丢掉终态或尝试记录,失败/部分写入可能损坏一行,进程退出可能丢掉队列内容。
读取器应跳过畸形行和空行;写出失败后,exporter 会先补换行,再写下一条记录。计数随进程重启清零。
没有重放、计费或审计持久性保证,也不建立财务对账、token 节省或任务成功结论。
生产宿主另启动一个独立的 stderr 健康线程,每秒读取一次 JsonEvidenceSink.stats():首次观察到非零
write_failed 时以 ERROR 输出 gateway.evidence.write_failed,首次观察到非零 dropped 时以 WARN 输出
gateway.evidence.dropped,每种通知每个 sink 最多一次。任一首次通知同时输出 gateway.evidence.health
汇总,此后每 30 秒汇总一次,即使没有新请求、stdout 仍未恢复也继续报告。无丢失的汇总为 INFO,
存在累计丢失的汇总为 WARN。及时报告依赖正常线程调度与可写的 stderr,仍遵循 RUST_LOG 过滤。
stderr 事件使用固定消息,仅携带三个累计无符号记录计数:dropped 为被拒绝的提交(含非法记录、队列满或断开),
write_failed 为失败或无法确认的序列化/写入/flush,written 为成功写入并 flush 的记录。
不携带执行身份、writer 异常原文、正文、URL、凭据或路径。计数随进程重启清零,各字段为独立原子快照,
不是对账账本。JSONL 的 loss 字段及 schema 保持不变。此输出由 Rust 宿主通过 tracing 管理,
不新增 Python operational 字段,也不修改其 JSON/console 白名单。
stdout 写出卡住不影响健康线程。stderr 卡住最多占用该健康线程;线程在 I/O 前释放 sink 引用,
不维护记录队列,不会延迟证据提交或 sink 销毁。sink 销毁后 reporter 在下一次轮询时退出;
关闭时不 join 任何可能阻塞的线程,因此不保证最终汇总或排空。应独立采集 stderr 与 stdout;
两路输出同时丢失或被过滤时,不能据此推断没有流量。直接使用 JsonEvidenceSink 的嵌入宿主负责自身健康报告,
库不会配置日志或自动启动 stderr reporter。
任一线程无法启动时,应用输出固定诊断并使用 Noop,不改变业务结果。
运维词汇与 exporter 边界
Server 运维契约和 #2388
的托管监控栈使用有界的 operation/unit/outcome 字段。Gateway 证据沿用这些字段的含义,
使用自身所属操作 gateway.model_call:统计一次本地托管模型执行,不是 Core 的 context_check
application operation,也不是 worker 的 inference generation。
unit=call 统计逻辑执行,attempt 统计实际 transport 交接,delivery 描述本地框架观测。
三种 unit 不能相加,delivery 事件也不能当作额外调用。
| 证据事实 | 顶层运维 outcome |
|---|---|
调用 release_authorized 或 degraded,已观察上游状态码 < 400 | success |
| 同上,已观察上游状态码 >= 400 | failure |
| 同上,上游状态码缺失 | null |
调用 blocked、withheld、admission_expired | blocked |
调用 send_indeterminate、not_sent、gate_paused 或已确认原因的 stopped | failure |
调用 abandoned,不论销毁时的取消意图/期限事实 | null |
尝试 delivered | success |
future 销毁时的尝试 possibly_sent | null |
| 其他终态尝试结果 | failure |
| 任何 delivery 观测 | null |
null 表示分类不可得,不是 success 或 noop。销毁时存在取消意图不能证明取消原因,因此不投影为
cancelled。保留嵌套的 terminal、sending、interruption 和尝试 outcome;通用 outcome 不能替代这些事实。
这里的 success 不证明降级输出获得 strict 释放批准、客户端收到、任务采用或任务成功。
顶层 duration_ms 复制调用/尝试耗时;delivery 为 null,因为其 elapsed_ms 使用不同的起点。
现有托管 Collector 接收 Server OTLP 日志,并通过 Server 字段白名单精简;默认不采集 Gateway stdout,
该 transform 也会丢弃嵌套的 schema/evidence/loss。完整 JSONL 应交给具有有界保留策略的采集器;
通过 Server formatter 或当前 OTLP pipeline 转发不能保全此证据流。公共字段用于词汇兼容的查询,
本实现不新增 Prometheus 指标、OTLP exporter 或重复监控栈;未验证该流在外部 Collector/Loki 中的存储与读回。
关联与覆盖范围
call_id 标识一次执行,关联它的 call、编号 attempt 和 delivery 记录。
它在请求控制中生成一次,贯穿执行完成与响应体生命周期。
request_id_fingerprint 是已绑定请求 ID 的进程内带密钥指纹;没有宿主关联时为 null。
target_fingerprint 是实际传输 URL 的指纹,不是客户端请求的模型或自报目标。重定向仍被禁用。
指纹密钥在进程内随机生成,不是可跨重启使用的身份,也不承诺密码学匿名化。
不输出原始 URL、请求 ID、缓存键、会话 ID、Scope、provider 异常、模型名、凭据、prompt 或响应正文。
记录不证明任务身份或 Source 投影覆盖;除非嵌入宿主另行提供关联,否则没有任务关联能力。
覆盖从 Executor::run 被轮询时开始。认证、非法请求体、中间件拒绝以及其他执行前入口错误不在本证据流内。
完整模型响应不代表释放成功。attempts 只统计实际交给 transport 的尝试,包含降级发送;
准入过期而未发送时为零。重试沿用同一 call_id,只有重新准入后真实发送才增加尝试编号。
不确定尝试不重发。演示接口 record_not_sent(0, ...) 的 prepare/capture/降级诊断不导出,
也不被当作模型未发送事实。
终态与发送事实
call 记录包含 terminal、sending、attempts、upstream_status、归一化 usage、
可选 interruption 和计时字段。终态取值为 release_authorized、blocked、withheld、
send_indeterminate、not_sent、gate_paused、degraded、admission_expired、abandoned。
已知生命周期停止编码为 {"stopped":"deadline_exceeded"}、{"stopped":"gateway_shutdown"}
或 {"stopped":"request_cancelled"}。
生命周期快照与证据共享 pc-gateway-types 的 ExecutionTerminal、ModelSendState;
ManagedOutcome 只保留一处终态映射。core 与 evidence 现有 Rust 导入名称继续通过重导出提供。
sending 独立表示 no_send、definitely_not_sent、possibly_sent、response_received。
取得响应后发生释放拒绝或期限过期,仍保留 response_received 与已上报的 usage。
执行所有者记录已确认的期限、停机或取消停止。pending 执行 future 销毁时,证据保留所有者的终态和发送事实;
没有已知停止原因的销毁仍记为 abandoned。共享取消信号已设置时,销毁观测字段 interruption 为
cancellation_requested;否则宿主期限已过时为 deadline_elapsed,其余情况为 future_dropped。
该字段描述销毁时的观测,共享执行终态标识已确认的停止原因。证据层不新增取消权或定时器。
传输中取消保持 possibly_sent 和未知 usage,不能记成 not_sent。
每个 attempt 包含 attempt、outcome、started_ms、duration_ms、upstream_status、归一化
usage、response_first_byte_ms、response_complete_ms。
结果取值为 possibly_sent(pending 发送被中断)、delivered、upstream_error(完整 HTTP 响应且状态码 >= 400)、
connect_refused、rejected_locally、lost_after_handoff、timeout_awaiting_response、buffer_limit_exceeded。
部分响应失败保留已观察到的状态码与首字节时间,完整响应时间和 usage 保持未知。
timeout_awaiting_response 包含等待响应头超时和读取正文超时(含已经收到部分正文);
lost_after_handoff 表示其他传输/正文读取失败。两者均不允许自动重试。
transport 交付完整响应后,解码或释放失败不会丢掉 usage。直接丢弃 pending transport 时无法取得其内部的部分观测。
响应缓冲区超限时,调用记录为 withheld、发送事实为 possibly_sent,仅有一次 buffer_limit_exceeded 尝试;
usage 与完整响应时间未知,保留已观察到的状态码和首字节时间。不释放响应前缀,也不重试,降级直通同样遵循此行为。
容量限制的拒绝结论与可能计费事实分别保留。
Usage 映射
usage_mapping 为 open_ai_chat 或 open_ai_responses,由实际线格式 renderer 选择,不使用客户端模型名。
无法识别 renderer 时 mapping 为 null、usage 保持未知。
usage.input、usage.output、usage.cache_read、usage.cache_write 各有 tokens(非负整数或 null)
与 completeness(known、estimated、unknown、reconciled)。当前只输出 provider 明确报告的
known 或 unknown,不执行估算或对账。
| 数量 | OpenAI Chat | OpenAI Responses |
|---|---|---|
| 输入 | usage.prompt_tokens | usage.input_tokens |
| 输出 | usage.completion_tokens | usage.output_tokens |
| 缓存读取 | usage.prompt_tokens_details.cached_tokens | usage.input_tokens_details.cached_tokens |
| 缓存写入 | 未知 | 未知 |
输入数量包含缓存输入;不能把缓存读取再加到输入上,也不能从已上报的输入字段减掉它。
不会把 Anthropic 的缓存创建/写入字段猜测为 OpenAI 字段。缺失、null、畸形或负数保持未知;明确上报的零为已知零。
仅有 total_tokens 不能确定输入/输出数量。SSE 只使用 Chat usage chunk 中明确的 usage 对象或 Responses
事件的 response.usage,保留最后一个对象,不累加累计 chunk。SSE usage 缺失或无法解析时保持未知。
SSE 媒体类型在分离参数后按大小写不敏感方式比较。usage 与首内容检查只忽略流开头的一个 UTF-8 BOM;
首内容偏移仍对应包含 BOM 的原始输出字节。响应字节与原始 Content-Type 保持不变。
这不会扩展 Core 接受的流式协议范围。
计时与 HTTP 交付
所有时长使用单调时钟,单位为毫秒,向下取整。null 表示不可得。
| 字段/边界 | 含义 |
|---|---|
调用 duration_ms | 创建请求控制至执行终态/销毁,包含创建控制后的入口耗时 |
尝试 started_ms | 创建请求控制至交给 transport |
尝试 duration_ms | 交给 transport 至得到传输结果或 future 销毁 |
response_first_byte_ms | 从等待响应头之前的 transport 发送起点至首个非空 HTTP 正文 chunk |
response_complete_ms | 从同一 transport 起点至完整缓冲响应 |
upstream_ttft_ms | 始终为 null;HTTP JSON/SSE 字节无法证明模型首 token |
release_decision_ms | 创建请求控制至 before-release 检查返回,包含错误与拒绝 |
release_authorized_ms | 创建请求控制至通过校验且未过期的释放批准,位于可选 capture 之后 |
交付 elapsed_ms | 创建请求控制至所标记的框架观测 |
执行器交接与 transport 自身的发送起点不同,两者的精确偏移没有记录。
started_ms + response_first_byte_ms 或 started_ms + response_complete_ms 不能得到精确的调用相对时间戳。
delivery 在获准/降级响应体放入 HTTP 响应时报告 framework_handoff,框架首次轮询取出非空 data frame
时报告 first_body_frame,取出包含首个可识别模型输出编码字节的 frame 时报告 first_model_content,
包装的 body 报告完成时为 body_completed,观察到完成之前被丢弃时为 body_dropped。
strict 模式的释放批准先于框架交接、首个 data frame 与首内容观测。降级响应没有释放批准时间。
首内容边界识别 OpenAI Chat/Responses JSON 与所支持 SSE 输出中的非空 assistant 文本、拒绝字符串、 函数调用名称及参数,包含 Responses 重放。仅含 role、usage、reasoning、error 及其他控制信息的事件不触发。 item-added 事件若确实包含函数名或输出文本,也可以建立内容边界;仅凭事件名称不能建立。 定位器检查实际发送的完整缓冲正文,只把字节偏移交给观察器。观察器累计已轮询 data 字节,支持任意 frame 切分,不保留正文,不改变响应字节。记录的是包含首个编码内容字节的 frame,该字节可能属于 JSON 转义, 不等待完整解码字符或完整 SSE 事件。
仅控制事件、空、畸形或不支持的输出没有 first_model_content 事件;在轮询到内容 frame 之前丢弃 body
也不产生该事件。缺失表示证据不可得,不是耗时为零;消费方还须考虑 sink 丢失计数。
首 body frame 可能只有 response.created 等 SSE 控制信息,因此 G8 必须单独读取 first_model_content。
同一 frame 同时包含两种边界时,两条记录可以使用相同时间戳。
这些边界都不证明 socket 写入、客户端收到、呈现或采用。当前宿主无法观察实际 socket 写出。
非流式 Responses JSON 的首字节及重放的 SSE 输出不是 provider TTFT。
部署与兼容
运维诊断只说明 TCP/UDS 连接模式,不输出配置的 Core URL 或 socket 路径。
非法 injection 配置不输出输入值;steering 文件拒绝使用固定原因,不包含文件路径。
运维人员应从受保护配置中检查端点和路径。
新增顶层 outcome、duration_ms 字段,嵌套领域记录保持原有含义。消费方必须接受 null 分类,
包括 abandoned 执行与 delivery 观测。
新增 delivery.boundary=first_model_content 值,穷举匹配枚举的消费方需要接受该值,
不能假定每次调用的记录数量固定。
原来从 stdout 采集人类可读 tracing 的部署,需要改为采集 stderr,并单独解析 stdout 证据。
无需数据库迁移、新 HTTP 端点、Python operational 字段或 OpenAPI 重新生成。
该 JSON schema 独立于 Server 的 Python 日志白名单与现有 exporter。
Gateway 客户端可见的 HTTP 503 gate_paused 响应中,Core 不可用错误的 detail 归一化为
gate_unavailable,Core 响应畸形错误的 detail 归一化为 malformed_gate_response,不再暴露原始诊断文本。
客户端不应依赖原来的自由文本 detail,应使用状态码和 decision 处理结果。
自定义嵌入 sink 的同步回调必须有界、不阻塞且不执行 I/O;将阻塞 writer 接入 JsonEvidenceSink,
每个宿主保留一个 sink。自定义 writer 应返回 I/O 错误,不应 panic。
Rust 集成改为读取 CallEvidence.usage 中逐字段的数量与完整性,不再读取演示记录原来的扁平 token/completeness 字段。
不存在生产记录存储迁移。集成需将 RawResponse.ttft_ms 替换为明确的首字节/完整响应字段,并将
SendOutcome::IncompleteResponse 视为不确定结果,保留其进度,禁止重试。

