FAIRVISOR Docs
⌘K
GitHub fairvisor.com

Debug Session

Use debug session when you need detailed per-request diagnostics for one operator/client without exposing internals to all traffic.

What it does

When debug session is active for a caller, Fairvisor adds verbose headers:

  • X-Fairvisor-Debug-Decision
  • X-Fairvisor-Debug-Mode
  • X-Fairvisor-Debug-Reason
  • X-Fairvisor-Debug-Policy
  • X-Fairvisor-Debug-Rule
  • X-Fairvisor-Debug-Latency-Us
  • X-Fairvisor-Debug-Matched-Policies
  • X-Fairvisor-Debug-Descriptor-<N>-Key
  • X-Fairvisor-Debug-Descriptor-<N>-Value

In normal mode, these headers are not emitted.

Prerequisites

Set:

  • FAIRVISOR_DEBUG_SESSION_SECRET=<strong-random-secret>

If the secret is not set, debug endpoints return 404.

Endpoints

  • POST /v1/debug/session
    • Required header: X-Fairvisor-Debug-Secret: <secret>
    • On success: 204 No Content and Set-Cookie: fv_dbg=...
  • POST /v1/debug/logout
    • Clears debug cookie

Typical workflow

  1. Create session:
curl -i -X POST http://localhost:8080/v1/debug/session \
  -H "X-Fairvisor-Debug-Secret: $FAIRVISOR_DEBUG_SESSION_SECRET"

  1. Reuse returned fv_dbg cookie in requests to /v1/decision.

  2. Inspect X-Fairvisor-Debug-* headers.

  3. End session:

curl -i -X POST http://localhost:8080/v1/debug/logout \
  -H "Cookie: fv_dbg=<cookie-value>"

Security model

Debug cookie is short-lived and scoped for operator use:

  • TTL: 15 minutes
  • HttpOnly
  • Secure
  • SameSite=Strict

Recommendations:

  • keep debug endpoints internal-only
  • rotate FAIRVISOR_DEBUG_SESSION_SECRET
  • do not log debug secrets
  • do not enable global debug in public edge paths

Important contract note

For standard reject responses (429), Fairvisor returns general reject headers (X-Fairvisor-Reason, Retry-After, RateLimit*).

Policy/rule attribution is debug-only and available as:

  • X-Fairvisor-Debug-Policy
  • X-Fairvisor-Debug-Rule

Troubleshooting

  • 404 on /v1/debug/session
    • FAIRVISOR_DEBUG_SESSION_SECRET is missing
  • 403 on /v1/debug/session
    • wrong X-Fairvisor-Debug-Secret
  • no X-Fairvisor-Debug-* headers after login
    • cookie not forwarded by client/gateway
    • cookie expired
    • HTTPS/cookie policy strips Secure cookie in your test path

MD