Usage Scenarios

Usage Scenarios

Real-world setups with network diagrams.

---

1. Local Development — Proxy Mode

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:3306

Pros: ✅ Auto SSL stripping | Cons: Requires changing app connection to :13306

---

2. Local Development — Capture Mode

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

---

3. Docker Compose — Proxy Mode

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

---

4. Docker — Capture Mode (Localhost)

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.

---

5. Production Server — Capture Mode

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

---

6. Production Server — Proxy Mode (Sidecar)

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

---

7. CI / Automation — CLI Mode

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)'

---

Decision Flowchart

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.)