Skip to content

Event Filtering

lex edited this page May 28, 2026 · 1 revision

Event Filtering

Ocular provides two layers of filtering to control which events appear in the event stream.


Config-Based Filtering (Exclude / Include)

Hide noisy events permanently using rules in ocular.toml.

Global exclude (by protocol)

Applies to all proxies of the given protocol:

[exclude.redis]
patterns = ["PING", "INFO", "CLIENT", "SUBSCRIBE"]

[exclude.mysql]
patterns = ["SELECT 1", "^SET "]
regex = true

[exclude.postgres]
patterns = ["SET ", "DEALLOCATE", "DISCARD ALL"]

[exclude.rabbitmq]
patterns = ["Heartbeat"]

Per-proxy exclude

Merged with global rules. Useful when one proxy is noisier than others:

[[proxy]]
name = "mysql-dev"
protocol = "mysql"
listen = "127.0.0.1:13306"
remote = "127.0.0.1:3306"

[proxy.exclude]
patterns = ["^SET NAMES", "^SET SESSION"]
regex = true

Include (override exclude)

Force specific events to remain visible even if they match an exclude rule:

[proxy.include]
patterns = ["PING"]    # Always show PING even though it's globally excluded

Evaluation order

include match → SHOW (highest priority)
exclude match → HIDE
no match      → SHOW (default)

Filter options

Field Default Description
patterns (required) List of strings to match against the event command
case_sensitive false Whether matching is case-sensitive
regex false Treat patterns as regular expressions

When regex = false, patterns are matched as substrings. When regex = true, patterns are treated as regular expressions (Rust regex crate syntax).


Interactive Filtering (TUI)

Fuzzy filter (/)

Press / in the TUI to activate the filter bar. Type to search across:

  • Component names (e.g. "redis")
  • Command text (e.g. "SELECT", "GET")

Matching is fuzzy when fuzzy_filter = true in config (default), or exact substring when false.

Press Enter to confirm, Esc to clear.

Component selection

Select a component in the component pane (Enter) to filter events to that component only. Press Esc to deselect and show all events.

Clear events

Space → c clears all events from the event pane.

Pause

Space → p pauses the event stream. New events are still captured but not displayed until you unpause.


Event Logging

For persistent event recording (independent of filtering), configure event_log:

[event_log]
enabled = true
include_response = true              # Include response data in log
components = ["redis-cache", "mysql"] # Only log these (empty = all)

Events are written to events.log regardless of what's visible in the TUI. This is useful for:

  • Post-incident analysis
  • Performance profiling over time
  • Feeding events into external tools

Clone this wiki locally