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.

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