Flow log and capture

Flow log

The flow log is one JSON object per line, written to stdout or to log.flow.path. Every exchange produces a request event:

{"ts":"2026-10-03T10:12:00.123Z","event":"request","flow":"01J9…","conn":"01J9…",
 "listener":"proxy","client":{"ip":"10.0.0.7","peer":{"ip":"10.0.0.7","port":51234}},
 "tls":{"sni":"api.github.com","alpn":"h2","version":"1.3"},
 "req":{"method":"POST","host":"api.github.com","port":443,"path":"/repos/x/y/issues",
        "query":null,"headers_bytes":812,"body_bytes":1032,
        "body_sha256":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "content_type":"application/json"},
 "res":{"status":201,"headers_bytes":1420,"body_bytes":5120,
        "body_sha256":"60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"},
 "decision":"allow","rules":["github-writes"],"tags":["billing"],
 "mutations":["set_header:authorization"],"addons":["redact"],
 "timing":{"total_ms":412,"upstream_connect_ms":38,"upstream_ttfb_ms":350},
 "terminal_rule":"github-writes","stage":"head"}

Common reasons, by terminal_rule:

Events

Redaction

Secret values that roxy injects are removed from everything it logs. The values of authorization, proxy-authorization, cookie, set-cookie and x-api-key are never logged, and log.redact_headers adds more. Query values are redacted.

Writing

The flow log never drops a record while roxy runs (audit backpressure).

• One thread writes each log file, in batches, so a record is written within a few milliseconds.
• When more than log.flow.high_water (8 MiB) is waiting to be written, or the disk fails, roxy holds traffic until the log catches up.
• With max_file_bytes, the file is rotated to <path>.<UTC timestamp>-<seq>, optionally gzipped, and files beyond max_files are deleted. SIGHUP reopens the file, for external rotation.
• On shutdown roxy writes everything queued, retrying a failing destination for up to 10 seconds. Records still unwritten after that are lost.
• roxy does not fsync, so a power loss can lose recent records.

log:
  redact_headers: []
  flow:
    path: /var/log/roxy/flow.jsonl  # absent = stdout
    connection_events: false
    ws_message_every: 0             # also log every Nth WebSocket message; 0 = denied only
    high_water: 8mb                 # at least 64kb
    max_file_bytes: 100mb           # absent = never rotate
    max_files: 10                   # absent = keep all
    compress: true

Rotation needs path, since stdout cannot be rotated.

Capture

Capture records whole requests and responses to <capture_dir>/capture.jsonl. It sits between the rules and the address floor. It records the request once the rules allow it, with their changes, and the response as it arrives from the upstream, before any addon changes it. If the address floor or the connection then fails, the capture holds the request head and an end with aborted: true, and no body. It records the exchanges a rule selects with capture: request | response | both, or every exchange with log.capture.all: true. It is written like the flow log, with the same batching, rotation and backpressure.

Secret values are removed from captured headers and URLs. Bodies are captured unredacted.

capture_dir: /var/lib/roxy/capture   # absent = capture off; restart to change
log:
  capture:
    all: false
    high_water: 64mb
    max_file_bytes: 1gb
    max_files: 20
    compress: true
limits:
  max_capture_body_bytes: 16mb       # per direction per exchange

Capture format

One JSON object per line:

{"flow":"01J9…","dir":"request","kind":"head","seq":0,"head":{"headers":[["content-type","application/json"]],"method":"POST","url":"https://api.example.com/v1/x"}}
{"flow":"01J9…","dir":"request","kind":"data","seq":1,"data":"aGVsbG8="}
{"flow":"01J9…","dir":"request","kind":"end","seq":2,"bytes":5}

A body is its data records joined in seq order. Each data record holds at most 48 KiB of body, so lines stay under 64 KiB plus a little JSON, apart from head lines, which can be up to limits.max_header_bytes.