Observability

Observability

Use observability to answer one debugging question at a time without leaking private prompts, API keys, or unnecessary upstream details.

Start narrow

Prefer compact logs first. If logs are not enough, capture the narrowest phase for one sanitized request, then disable capture again.

Read logs safely

Logs should be compact, structured, and privacy-preserving by default. They can help identify routing decisions, provider selection, upstream status, stream outcomes, and request hints without storing full payloads.

Logs should not include:

• request bodies
• Authorization headers
• API keys
• private prompts
• unnecessary private upstream URL details

These rules implement Behavior Contract C23–C25.

Automatic failure diagnostics

Translation failures and recognized provider semantic failures automatically create a local diagnostic bundle under diagnostics/; this is independent of all [capture] switches. A request failure before forwarding emits fwd-error; a failure while converting an already-started SSE response emits stream-error. A provider stream that terminates cleanly but reports a semantic failure, such as Anthropic model_context_window_exceeded or an OpenAI Responses terminal error, emits provider-semantic-failure. These warnings include diag=... pointing to the bundle. Provider stream terminal and error lines carry the same compact req=... ID as their fwd line, so concurrent requests can be correlated directly.

A request-translation bundle contains record.json plus the exact normalized JSON payload that failed to deserialize or translate. A stream-translation bundle contains record.json plus the raw triggering (or immediately preceding terminal) upstream_sse_event.sse frame. A provider-semantic bundle contains only a privacy-safe response summary and the terminal upstream_terminal_event.sse; it does not copy the request or prompt. JSON paths and compact logs identify context, but cannot replace the surrounding payload/frame needed to reproduce a translation failure. ProxAI keeps only the newest 50 diagnostic bundles.

Diagnostics can contain private data

Automatic diagnostic payloads can contain prompts and tool arguments. They stay local, are never written into normal logs, and must be sanitized before sharing or committing.

Capture one request

1. 1Choose the questionWhat do you need to see: client input, provider request, upstream response, or final outbound response?
2. 2Pick the phaseUse the narrowest capture phase that can answer the question.
3. 3Enable brieflyUse `proxai capture enable ...` or `[capture]` switches for a short debugging window.
4. 4Reproduce onceSend one minimal sanitized request.
5. 5Disable and sanitizeKeep captures local; sanitize before turning anything into a fixture.

CLI example:

proxai capture status
proxai capture enable provider-request
# reproduce once
proxai capture disable provider-request

Choose the phase

Question	Phase
What did the local client send?	inbound_request
Which provider payload did ProxAI prepare?	provider_request
What status, headers, or bytes did the upstream return?	upstream_response
What did ProxAI return to the client?	outbound_response

The capture directory is fixed under the app directory. Config only controls whether each phase is written:

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

For exact phase boundaries and privacy risks, see Capture Phases.

Sanitize a capture

Before sharing or committing anything derived from a capture:

• remove API keys and Authorization headers
• remove private prompts, files, tool arguments, and model outputs
• trim unrelated request/response data
• replace private upstream URLs with sanitized placeholders
• keep only the smallest payload that reproduces the behavior

Captures can contain private data

Captures may include prompts, tool arguments, model outputs, and upstream payloads. Keep them local unless they have been deliberately trimmed and sanitized.

Understand request hints

Request hints are small protocol-aware summaries used for diagnostics. They should help identify common routing/proxy issues without logging full payloads.

Useful hints include:

Hint type	Useful for
Detected request protocol	Confirming path-based ingress behavior
Model and route summary	Checking provider selection without logging prompts
Streaming outcome	Understanding whether terminal events were seen
Upstream status summary	Separating provider failure from local translation failure

Related docs

• Troubleshooting
• Capture Phases
• Environment and Files
• Streaming behavior