跳转到内容
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。

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 “相关文档”