-
Notifications
You must be signed in to change notification settings - Fork 0
Usage Scenarios
Real-world setups with network diagrams.
Ocular runs on your dev machine, proxying traffic to a remote service.
Dev Machine (192.168.1.100) Server (192.168.0.184)
┌─────────────────────────┐ ┌──────────────────┐
│ App ──→ Ocular (:13306)│ ───────→ │ MySQL (:3306) │
│ TUI Dashboard │ └──────────────────┘
└─────────────────────────┘
ocular proxy mysql 192.168.0.184
# Listens on 127.0.0.1:13306, forwards to 192.168.0.184:3306Pros: ✅ Auto SSL stripping | Cons: Requires changing app connection to :13306
Passive sniffing — no connection changes needed.
Dev Machine (192.168.1.100) Server (192.168.0.184)
┌─────────────────────────┐ ┌──────────────────┐
│ App ───────────────────│ ───────→ │ Redis (:6379) │
│ Ocular (sniffs en0) │ └──────────────────┘
└─────────────────────────┘
sudo ocular capture redis 192.168.0.184 -i en0
Pros: ✅ Zero config on app side | Cons: ❌ Cannot decrypt SSL, requires sudo
Ocular on the host, proxying traffic from Docker containers.
Host (192.168.1.100)
┌──────────────────────────────────────┐
│ Ocular (:13306) │
│ ↑ │
│ Client container │
│ (host.docker.internal:13306) │
│ │
│ MySQL container (:3306 on host) │
└──────────────────────────────────────┘
ocular proxy mysql 127.0.0.1:3306 -l 127.0.0.1:13306
Docker client config:
environment: MYSQL_HOST: host.docker.internal MYSQL_PORT: 13306
Capture traffic to Docker containers that are port-mapped to localhost.
sudo ocular capture redis 127.0.0.1 -i lo0 # macOS sudo ocular capture redis 127.0.0.1 -i lo # Linux
⚠️ Traffic between containers on the Docker bridge network is invisible to capture mode — it never reaches the host's network interface.
Passive monitoring of a production service. No risk, no config changes.
Clients Server (10.0.0.10)
┌──────────┐ ┌──────────────────────────┐
│ App A │ ───────────→ │ Redis (:6379) │
│ App B │ ───────────→ │ Ocular (sniffs eth0) │
└──────────┘ └──────────────────────────┘
sudo ocular capture redis 10.0.0.10:6379 -i eth0 # Permanent permission (no sudo needed after this): sudo setcap cap_net_raw+ep $(which ocular)
Pros: ✅ Shows all client IPs | ✅ Zero intrusion | Cons: ❌ Cannot decrypt SSL
Ocular deployed as a sidecar on the server.
Clients Server (10.0.0.10)
┌──────────┐ ┌──────────────────────────┐
│ App A │ ───────────→ │ Ocular (:13306) │
│ App B │ ───────────→ │ └──→ MySQL (:3306) │
└──────────┘ └──────────────────────────┘
ocular proxy mysql 127.0.0.1:3306 -l 0.0.0.0:13306
Pros: ✅ Auto SSL stripping | Cons: Clients must connect to :13306
Headless Ocular in a CI pipeline.
CI Runner
┌──────────────────────────────────────┐
│ Ocular proxy --json > events.json │
│ Test script → Ocular → MySQL │
│ Analyze events.json │
└──────────────────────────────────────┘
# Start proxy in background ocular proxy mysql --json > events.json & # Run tests (connecting to proxy port) pytest --db-port=13306 # Analyze cat events.json | jq '.command' | sort | uniq -c | sort -rn cat events.json | jq 'select(.latency_ms > 100)'
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.)