HTTP Logging

HTTP logging records the requests and responses that pass through your TCP port forwards, so you can debug API calls. It is off by default and you turn it on for each config.

The HTTP logs video shows the desktop logs opened in an editor.

Enabling HTTP loggingCopy Anchor Link

Logging toggles apply to established TCP connections without reconnecting. Turning logging on starts capturing subsequent HTTP traffic. Connections already in WebSocket tunnel mode ignore logging toggles.

Config fieldsCopy Anchor Link

The logger rotates a nonempty file before an entry would push it past the size limit. It copies the file to a timestamped file and truncates the active file. A single oversized entry can exceed the limit because the logger keeps each entry intact.

This example sets a 20 MiB rotation threshold and 14-day retention with automatic cleanup:

{
  "alias": "api-debug",
  "target": "app=backend,version=v2",
  "namespace": "staging",
  "local_port": 3000,
  "remote_port": 8080,
  "context": "my-k8s-cluster",
  "workload_type": "pod",
  "protocol": "tcp",
  "http_logs_enabled": true,
  "http_logs_max_file_size": 20971520,
  "http_logs_retention_days": 14,
  "http_logs_auto_cleanup": true
}

Log file locationCopy Anchor Link

HTTP logs live in the http_logs folder inside the configuration directory. kftray looks for the directory in this order:

1. KFTRAY_CONFIG
2. $XDG_CONFIG_HOME/kftray
3. ~/.kftray

Each port forward writes its own file, named <config id>_<local port>.http:

Rotated files use <config id>_<local port>_<YYYYMMDD>_<HHMMSS>.http, with a UTC timestamp. A numeric suffix distinguishes rotations within the same second.

Log formatCopy Anchor Link

The .http files are plain text. The # lines and ### separators match the VS Code REST Client format. Each request and each response is its own entry.

# ----------------------------------------
# Trace ID: a1b2c3d4
# Request at: 2026-02-09T14:32:15.123+00:00
POST /api/users HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Content-Length: 87

{"email":"[email protected]","name":"Jane Doe","role":"admin"}

###

# ----------------------------------------
# Trace ID: a1b2c3d4
# Response at: 2026-02-09T14:32:15.168+00:00
# Took: 45 ms
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 156

{"id":"usr_123","email":"[email protected]","name":"Jane Doe","role":"admin"}

###

kftray decodes response bodies sent with Content-Encoding: gzip, br or a stacked value such as gzip, br. It shows other encodings as received. The preformatted-response path cuts decoded bodies at 10 MiB and adds a truncation marker. Other response-formatting paths do not share that limit.

Viewing and replaying in kftuiCopy Anchor Link

Press V to open the HTTP logs viewer. It has two modes.

List mode is the default:

• It shows all requests with timestamps and status codes.
• ↑ ↓ move through requests and PageUp PageDown scroll by ten entries.
• Enter opens the detail view for a request.
• a turns automatic scrolling for new requests on or off.
• Esc closes the viewer.

Detail mode shows the full request and response, including headers and body:

• ↑ ↓ and PageUp PageDown scroll the details.
• r replays the selected request with a 30-second timeout.
• c or C copies the selected request as a curl command through OSC 52. Your terminal must support OSC 52 clipboard writes.
• Esc cancels an in-progress replay and goes back to list mode.

Replay uses http://<local_address>:<local_port> from the forward, with 127.0.0.1 as the default address. A request path that already contains a full HTTP URL keeps that URL. Copy as curl uses the same address rules.

Press o to open the log file in your external editor. Request replay exists in kftui only.

CleanupCopy Anchor Link

When automatic cleanup is on, the logger removes expired rotated files for the same config ID and local port. It checks file modification times when the logger starts and after each rotation. Cleanup leaves the active file and other forwards' logs in place.

To remove logs manually, stop the forward first. For the default configuration directory:

rm ~/.kftray/http_logs/*.http

If you changed KFTRAY_CONFIG or XDG_CONFIG_HOME, use that directory's http_logs folder instead. The command deletes active and rotated logs for every forward in that folder.