Ocular supports two fundamentally different ways of observing traffic. Choose based on your constraints.

Ocular sits between your app and the middleware as a lightweight TCP proxy.

Your App ──→ Ocular Proxy (:16379) ──→ Redis (:6379)
 │
 TUI Dashboard

1. Ocular listens on a local port (e.g. 127.0.0.1:16379)
2. Your app connects to Ocular instead of the real service
3. Ocular forwards all traffic to the real service (e.g. 127.0.0.1:6379)
4. Both directions are parsed and displayed in the TUI

• ✅ Works with any protocol Ocular supports
• ✅ Auto SSL stripping — MySQL/Postgres SSL connections work without --ssl-mode=DISABLED
• ✅ No elevated permissions needed
• ✅ Full bidirectional visibility

• ❌ Requires changing your app's connection settings (host/port)
• ❌ Adds ~0.1ms latency per request (negligible)

• Local development
• Docker Compose setups
• When you control the app's connection config
• When the service uses SSL/TLS

Ocular passively sniffs network traffic using libpcap. Your app doesn't know Ocular exists.

Your App ──→ Redis (:6379) # Direct connection, no changes
 │
 libpcap captures
 │
 TUI Dashboard

1. Ocular attaches to a network interface (e.g. lo0, en0, eth0)
2. It captures TCP packets destined for the specified service
3. TCP stream reassembly reconstructs complete messages
4. Protocol parsing displays structured events

• ✅ Zero config changes — your app connects normally
• ✅ Zero intrusion — completely passive
• ✅ Can see traffic from any client (useful for production monitoring)
• ✅ Shows source IP in src field (multi-client visibility)

• ❌ Requires elevated permissions (sudo or cap_net_raw)
• ❌ Cannot decrypt SSL/TLS traffic
• ❌ Traffic between Docker containers is invisible (stays inside Docker network)
• ❌ Linux only for non-loopback interfaces (macOS loopback works)

macOS (one-time, until reboot):

sudo chmod g+r /dev/bpf*
sudo dseditgroup -o edit -a $USER -t user access_bpf

Linux (persistent):

sudo setcap cap_net_raw+ep $(which ocular)

• When you can't change app connection settings
• Production server monitoring (passive, no risk)
• Observing traffic from multiple clients simultaneously
• Legacy codebases where connection config is hard to find

Can you change app connection config?
├── YES → Proxy Mode (recommended)
└── NO
 ├── Protocol is unencrypted (Redis, Kafka, MongoDB, AMQP, Memcached)?
 │ └── YES → Capture Mode
 └── Protocol uses SSL (MySQL, Postgres with SSL)?
 ├── Can disable SSL on server? → Capture Mode
 ├── Can deploy Ocular as sidecar? → Proxy Mode
 └── Neither → Use native tools (slow query log, etc.)

Proxy mode:

[[proxy]]
name = "redis"
protocol = "redis"
listen = "127.0.0.1:16379" # Ocular listens here
remote = "127.0.0.1:6379" # Forward to real service

Capture mode:

[[proxy]]
name = "redis"
protocol = "redis"
mode = "capture"
interface = "lo0" # macOS: lo0/en0, Linux: lo/eth0
remote = "127.0.0.1:6379" # The real service address

Note: Capture mode and proxy mode are mutually exclusive per service. Use one or the other.