部署与运维
查看 Markdown

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,已观察上游状态码 < 400success
同上,已观察上游状态码 >= 400failure
同上,上游状态码缺失null
调用 blocked、withheld、admission_expiredblocked
调用 send_indeterminate、not_sent、gate_paused 或已确认原因的 stoppedfailure
调用 abandoned,不论销毁时的取消意图/期限事实null
尝试 deliveredsuccess
future 销毁时的尝试 possibly_sentnull
其他终态尝试结果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 ChatOpenAI Responses
输入usage.prompt_tokensusage.input_tokens
输出usage.completion_tokensusage.output_tokens
缓存读取usage.prompt_tokens_details.cached_tokensusage.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 视为不确定结果,保留其进度,禁止重试。

On this page