FAIRVISOR Docs
⌘K
GitHub fairvisor.com

fairvisor logs

fairvisor logs reads newline-delimited JSON from stdin and outputs only the lines matching the given filters. It is designed to be piped from a docker logs or kubectl logs command.

Synopsis

fairvisor logs [--action=ACTION] [--reason=REASON]

Options

Flag Description
--action Filter to lines where entry.action equals this value (allow, reject, throttle)
--reason Filter to lines where entry.reason equals this value (see Reject Reasons)

Both filters are applied with AND logic: a line must match all provided filters to pass through.

Log format

Fairvisor emits structured JSON log lines on each decision. Example:

{
  "time": "2026-01-15T10:00:00Z",
  "action": "reject",
  "reason": "token_bucket_exceeded",
  "policy_id": "api-rate-limit",
  "rule_name": "per-key-limit",
  "client_ip": "10.0.0.5",
  "path": "/api/v1/users",
  "method": "GET",
  "latency_us": 42
}

Examples

# Show only rejected requests
docker logs fairvisor -f | fairvisor logs --action=reject

# Show only budget_exceeded rejections
kubectl logs -f deployment/fairvisor | fairvisor logs --action=reject --reason=budget_exceeded

# Count rejections per reason
docker logs fairvisor | fairvisor logs --action=reject \
  | jq -r .reason | sort | uniq -c | sort -rn

# Tail and filter in real time
docker logs --tail=0 -f fairvisor | fairvisor logs --action=reject

Exit codes

fairvisor logs runs indefinitely until EOF or SIGINT. It always exits 0.

MD