跳转到内容
ProxAI

观测与诊断

观测与诊断

Section titled “观测与诊断”

使用 observability 时，一次只回答一个调试问题，同时避免泄露 private prompts、API keys 或不必要的上游细节。

安全阅读日志

Section titled “安全阅读日志”

日志应该保持紧凑、结构化，并默认保护隐私。它们可以帮助识别 routing decision、provider selection、upstream status、stream outcome 和 request hints，而不保存完整 payload。

日志不应该包含：

  • 请求 body
  • Authorization header
  • API key
  • private prompts
  • 不必要的私有上游 URL 细节

这些规则实现了 行为契约 C23–C25。

自动失败诊断

Section titled “自动失败诊断”

Translation 失败以及已识别的 provider 语义失败都会在 diagnostics/ 下自动创建本地诊断 bundle；该行为独立于所有 [capture] 开关。转发前的请求失败使用 fwd-error；已经开始的 SSE 响应在转换时失败使用 stream-error。provider stream 若完整结束、但报告了 Anthropic model_context_window_exceeded 或 OpenAI Responses terminal error 之类的语义失败，则使用 provider-semantic-failure。这些警告都会包含指向 bundle 的 diag=...。Provider stream 的 terminal/error 行会携带与对应 fwd 行相同的紧凑 req=... ID，可以直接关联并发请求。

请求 translation bundle 包含 record.json 和发生反序列化或转换失败时的完整 normalized JSON payload。流式 translation bundle 包含 record.json 和触发失败的原始（或终止前最近一个）upstream_sse_event.sse frame。provider semantic bundle 只包含隐私安全的响应摘要和终止事件 upstream_terminal_event.sse，不会复制请求或 prompt。JSON path 和紧凑日志只能定位上下文，不能替代复现 translation 失败所需的 payload/frame 现场。ProxAI 只保留最新 50 个诊断 bundle。

Capture 一次请求

Section titled “Capture 一次请求”
  1. 1选择问题你要看的是 client input、provider request、upstream response，还是最终 outbound response？
  2. 2选择 phase用能回答问题的最窄 capture phase。
  3. 3短时间启用用 `proxai capture enable ...` 或 `[capture]` switches 打开一个调试窗口。
  4. 4复现一次发送一个最小脱敏请求。
  5. 5关闭并脱敏Captures 留在本地；要变成 fixture 前必须脱敏。

CLI 示例：

Terminal window
proxai capture status
proxai capture enable provider-request
# 复现一次
proxai capture disable provider-request

选择 phase

Section titled “选择 phase”
问题Phase
本地客户端到底发了什么？inbound_request
ProxAI 准备了哪个 provider payload？provider_request
上游返回了什么 status、headers 或 bytes？upstream_response
ProxAI 最终返回给客户端什么？outbound_response

Capture 目录固定在 app 目录下。配置只控制各 phase 是否写入：

[capture]
inbound_request_enabled = false
provider_request_enabled = false
upstream_response_enabled = false
outbound_response_enabled = false

精确 phase 边界和隐私风险见 Capture Phases。

脱敏 capture

Section titled “脱敏 capture”

分享或提交任何 capture 派生产物之前：

  • 移除 API keys 和 Authorization headers
  • 移除 private prompts、files、tool arguments 和模型输出
  • 裁剪无关 request/response 数据
  • 用脱敏占位符替换 private upstream URLs
  • 只保留能复现行为的最小 payload

理解 request hints

Section titled “理解 request hints”

Request hints 是面向协议的小型诊断摘要，用来识别常见 routing/proxy 问题，而不是记录完整 payload。

常见 hints：

Hint 类型用途
检测出的 request protocol确认 path-based ingress 行为
Model 和 route summary在不记录 prompts 的情况下检查 provider selection
Streaming outcome理解 terminal events 是否出现
Upstream status summary区分 provider failure 和本地 translation failure

相关文档

Section titled “相关文档”