Search Reference

Outrig provides powerful search capabilities that allow you to quickly filter logs, goroutines, and watches. One of its most distinctive features is real-time typeahead search - results update instantly as you type, with no need to press Enter or wait for processing. This immediate feedback can speed up your debugging workflow, allowing you to find exactly what you need in less time. What makes Outrig's search particularly powerful is how it lets you seamlessly mix different search styles - fuzzy matching, regular expressions, case-sensitive searches, and field-specific filters - all in the same query, making it accessible even for users who aren't familiar with traditional CLI search tools.

Quick Start

Here are some search patterns to get you started:

# Find all logs containing "error" (case-insensitive)
error

# Use single quotes for case-sensitive search
'Error:'

# Use "/" for regex search (case-insensitive)
/^error:.*db/

# Use "c/" for case-sensitive regex search
c/^Error:.*DB/

# Spaces separate additional terms to be combined with AND
/^error:/ timeout

# Use "-" to exclude terms, quotes allow for embedded spaces or special characters
/^error:/ timeout -"retried successfully"

# Use "~" for fuzzy search
~errdb ~timeout -~retried

# Use "|" for OR searches (include more results)
'Error:' | 'Warning:'

# Use "()" to group terms to make more complex queries
(~error | ~warning) 'DB' /code[0-9]+/ -"code55" | fatal

# Use "$" for field-specific searches (e.g. goroutine state)
$state:"io wait"

# Use "#" for tag searches
timeout #backend

# Complex Examples

# Find logs with HTTP errors but exclude 404s (the / starts a regex expression)
(http | https) error -/404\s+Not\s+Found/

# Find logs tagged with "backend" containing database errors
(db | database) #backend (error | failure)

# Find goroutines handling connections but not waiting for IO
connection -$state:"io wait"

Search Operators

Outrig supports the following search operators:

Field-Specific Searches

You can target specific fields using the $ operator followed by the field name and a search term. Each data type in Outrig (logs, goroutines, watches) has its own set of searchable fields. Without specifying a field, Outrig will search across all fields by default.

Log Fields

Logs can be searched using these fields:

Goroutine Fields

Goroutines can be searched using these fields:

Watch Fields

Watches can be searched using these fields:

Advanced Search Examples

Outrig's search capabilities allow for sophisticated filtering with complex expressions:

Field-Specific Searches

# Find logs from stdout
$source:stdout

# Find logs from stderr
$source:stderr

# Find log line number 42
$linenum:42

# Find goroutines with ID 1
$goid:1

# Find watches named "counter"
$name:counter

# Find watches of type "string"
$type:string

Complex Searches

# Find errors in stdout but exclude timeout errors
$source:stdout error -timeout

# Find goroutines that are either running or waiting on a channel
$state:running | $state:chan

# Find all watches with values containing "user" in either string or JSON representation
$val:user | $json:user

Using Regular Expressions

# Find logs matching a pattern
/error.*timeout/

# Case-sensitive regex search for specific error types
c/ErrorType[0-9]+/

Tag Searches

# Find items tagged with #bug (prefix match)
#bug

# Find items with exact tag #v1 (won't match #v10, #v11, etc.)
#v1/

Note, by default we do a prefix match on tags so typeahead search refines progressively as you type. You can type a "/" at the end to force an exact match.

Real-Time Typeahead Search

Outrig's search is designed to provide immediate feedback as you type:

• Results update instantly with each keystroke, with no need to press Enter
• The search engine handles incomplete expressions gracefully, allowing you to see results even while in the middle of typing a complex query
• For example, if you start typing "foo hello (with an unclosed quote), the search will still work and show matching results
• Most of the grammar rules are designed with progressive typing in mind.

Grouping with Parentheses

Parentheses allow you to create more complex search expressions by controlling the order of operations:

# Find logs with either "error" or "warning" that don't contain "debug"
(error | warning) -debug

# Find logs with "connection" that also have either "timeout" or "refused"
connection (timeout | refused)

# Find logs from either stdout or stderr that contain "error"
($source:stdout | $source:stderr) error

Search Behavior Notes

• Empty control tokens (like ~, $, :, -, or #) followed by whitespace are treated as errors
• Single quoted tokens are treated as case-sensitive (exactcase)
• Tag tokens with trailing slash (#foo/) require exact matches
• Special case: #marked or #m uses the marked searcher to find marked lines
• Not token (-) negates the search result of the token that follows it
• A literal - at the start of a token must be quoted: "-hello" searches for "-hello" literally
• The search is designed with type-ahead semantics in mind, so incomplete expressions (like unclosed quotes or parentheses) will work as you type
• Any term with an error (e.g. invalid regexp) will be ignored in the search (the UI will highlight the error)

Advanced: Formal Grammar Definition

For those interested in the technical details, Outrig's search functionality is based on the following grammar:

// Search Parser Grammar (EBNF):

// search           = WS? or_expr WS? EOF ;
// or_expr          = and_expr { WS? "|" WS? and_expr } ;
// and_expr         = group { WS group } ;
// group            = "(" WS? or_expr WS? ")" | token
// token            = not_token | field_token | unmodified_token ;
// not_token        = "-" field_token | "-" unmodified_token ;
// field_token      = "$" WORD | "$" WORD unmodified_token ;
// unmodified_token = fuzzy_token | regexp_token | tag_token | simple_token ;
// fuzzy_token      = "~" simple_token ;
// regexp_token     = REGEXP | CREGEXP;
// tag_token        = "#" WORD [ "/" ] ;
// simple_token     = DQUOTE | SQUOTE | WORD
//
// Notes:
// - Empty control tokens (like "~", "$", ":", "-" or "#") followed by whitespace are errors
// - Single quoted tokens are treated as case-sensitive (exactcase)
// - Fuzzy tokens with single quotes (~'...') are treated as case-sensitive fuzzy search (fzfcase)
// - Tag tokens with trailing slash (#foo/) require exact matches
// - Special case: #marked or #m uses the marked searcher to find marked lines
// - Not token (-) negates the search result of the token that follows it
// - A literal "-" at the start of a token must be quoted: "-hello" searches for "-hello" literally
// Once parsing a WORD the only characters that break a WORD are whitespace, "|", "(", ")", "\"", "'", and EOF

This formal definition is provided for completeness and is primarily useful for developers who need to understand the exact parsing rules.