# Debug Session

- Canonical URL: https://docs.fairvisor.com/docs/reference/debug-session/
- Section: docs
- Last updated: n/a
> Per-user debug session workflow with signed cookie and X-Fairvisor-Debug-* headers.


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:

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

2. Reuse returned `fv_dbg` cookie in requests to `/v1/decision`.

3. Inspect `X-Fairvisor-Debug-*` headers.

4. End session:

```bash
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