Using Ocular with AI coding agents and automation tools.

Ocular's --json output mode makes it ideal for programmatic consumption by AI agents. The combination enables:

• Automated performance analysis — Agent captures traffic, identifies slow queries, N+1 patterns, cache misses
• Code-to-behavior correlation — Agent sees what the ORM actually sends vs. what the code implies
• CI regression detection — Compare query counts before/after a PR
• Debugging assistance — Agent can observe live traffic while a user reproduces an issue

The primary integration point:

ocular proxy mysql --json 2>/dev/null

Each line is a JSON object:

{
 "timestamp": "2026年05月28日T10:30:45Z",
 "component": "mysql",
 "protocol": "mysql",
 "command": "SELECT * FROM users WHERE id = 42",
 "full_command": "SELECT * FROM users WHERE id = 42",
 "response": "ResultSet (1 rows, 5 cols)",
 "response_detail": "...",
 "latency_ms": 3.73,
 "process": null,
 "src": "127.0.0.1:54321",
 "dest": "127.0.0.1:3306",
 "system": false
}

Agent starts Ocular, captures traffic for a fixed duration, then analyzes:

# Start proxy, capture for 30 seconds
timeout 30 ocular proxy mysql --json --raw > /tmp/ocular-events.jsonl 2>/dev/null
# Agent analyzes the captured events
cat /tmp/ocular-events.jsonl | python3 -c "
import json, sys
from collections import Counter

events = [json.loads(line) for line in sys.stdin]
commands = Counter(e['command'].split()[0] for e in events)
slow = [e for e in events if e['latency_ms'] > 100]

print(f'Total events: {len(events)}')
print(f'Command distribution: {dict(commands.most_common(10))}')
print(f'Slow queries (>100ms): {len(slow)}')
for e in slow[:5]:
 print(f' {e[\"latency_ms\"]}ms: {e[\"command\"][:80]}')
"

Compare query behavior before and after a change:

# Baseline (main branch)
git checkout main
ocular proxy mysql --json --raw > baseline.jsonl &
pytest --db-port=13306
kill %1
# PR branch
git checkout feature-branch
ocular proxy mysql --json --raw > pr.jsonl &
pytest --db-port=13306
kill %1
# Compare
echo "Baseline queries: $(wc -l < baseline.jsonl)"
echo "PR queries: $(wc -l < pr.jsonl)"

For Hermes Agent users, Ocular can be integrated as a diagnostic skill:

## Workflow
1. Agent calls `ocular proxy <proto> --json --raw` with a timeout
2. Agent parses the JSONL output
3. Agent identifies patterns: N+1 queries, slow queries, cache misses
4. Agent correlates with codebase to suggest fixes

Can do:

• Capture all middleware traffic as structured JSON events
• Identify N+1 query patterns (same query repeated with different params)
• Find slow queries (>100ms threshold)
• Analyze Redis cache hit/miss ratios
• Count queries per type (SELECT/INSERT/UPDATE/DELETE)
• Detect connection patterns

Cannot do (currently):

• Correlate events to specific code locations (no trace ID / span ID)
• Capture HTTPS/TLS traffic (only unencrypted middleware protocols)
• Track request causality across concurrent connections
• Provide application-level context (which API endpoint triggered the queries)

Ocular is a data-layer observability tool, not a full APM. For AI agents, its sweet spot is:

• Database query analysis — N+1, slow queries, full table scans
• Cache behavior — Redis hit rates, key patterns
• Message queue inspection — RabbitMQ/Kafka message flow

It does not replace tools like LangSmith or Langfuse for LLM-specific observability (prompt/response capture, token usage, agent traces). Those operate at a different layer (HTTP/API level) that Ocular doesn't cover.

The most compelling use case is automated DBA-like analysis: the agent acts as a junior DBA that watches traffic and flags performance anti-patterns.