Request Tracing

Overview

Request Tracing captures detailed information about every HTTP request passing through a route. It serves as a troubleshooting tool when a route does not work as expected — instead of guessing why a request fails, the admin sees exactly what happens: method, URI, status code, remote IP, and response details.

How It Works

Request Tracing is based on the caddy-trace plugin for Caddy. When tracing is enabled for a route, a trace handler is inserted into the Caddy handler chain. This handler logs two entries per request:

Incoming Request: Method, URI, Host, Remote IP, User-Agent, Headers, Query Parameters
Outgoing Response: Status Code, Response Size, Response Headers

Trace entries are displayed in real-time in the Debug tab of the Edit Route modal, with auto-refresh every 3 seconds.

Handler Position in the Route Chain

1. defender (Bot Blocker)
2. trace (Request Tracing)     ← logs entire lifecycle
3. headers (Custom Headers)
4. rate_limit
5. mirror (Request Mirroring)
6. encode (Compression)
7. reverse_proxy (Backend)

Configuration

Enable Tracing

Open route (Edit Modal → Debug tab)
Enable Request Tracing toggle
Save route

Viewing Trace Entries

Entries appear automatically in the Debug tab (auto-refresh every 3 seconds):

Column	Description
Time	Request timestamp (HH:MM:SS)
Method	HTTP method (GET, POST, PUT, DELETE, etc.)
URI	Requested path (e.g. `/api/data`)
Status	HTTP status code with color coding (Green=2xx, Yellow=4xx, Red=5xx)
Remote IP	IP address of the requesting client

Troubleshooting Examples

Route returns 502

Enable tracing, send request, the Debug tab shows:

21:45:54  GET  /  502  10.8.0.3

Status 502 = Backend unreachable → Peer offline or wrong port.

Redirect Loop

The Debug tab shows multiple 302 entries:

21:46:01  GET  /        302  10.8.0.3
21:46:01  GET  /login   302  10.8.0.3
21:46:01  GET  /        302  10.8.0.3

Redirect loop between / and /login → check auth configuration.

Request not arriving

Enable tracing, send request — no entry in Debug tab. The request is not reaching the route → check DNS or Caddy config.

Limitations

HTTP routes only: L4/TCP routes do not support tracing
No persistence: Trace data is only stored in the log file, not in the database
No export: Trace entries cannot be exported as CSV/JSON
No URI filter: All requests to the route are traced
Performance: Only enable temporarily on high-traffic routes