Searching Spans and Logs
In addition to the SQL-like query language, Uptrace allows you to search spans and logs using a more concise and natural query language that makes finding specific data faster and more intuitive.
Word Filters
The simplest query is a single word that must be found within the search scope.
Example: The query error will match the following logs:
err
error
ERROR
ERRor
an error just occurred
Multiple Words (AND Logic)
When your query contains multiple words separated by spaces, all words must be found in the search scope.
Example: The query error select will match:
error select
select error
an error has occurred when executing a select query
Multiple Words (OR Logic)
To search for logs containing any of multiple words, separate them with the pipe character (|).
Example: The query select|update will match:
select
update
select update
Phrase Filters
To search for logs containing an exact phrase, enclose the phrase in double quotes ("). The phrase can contain any characters, including spaces, punctuation, and special characters.
Example: The query "select query" will match:
an error has occurred when executing a select query
select query
But will not match:
query select
selecting a query
Regular Expression Filters
To search using regular expressions, prefix your expression with the tilde character (~).
Example: The query ~err will match:
err
error
an_err
some error
Regular Expressions with Spaces
If your regular expression contains spaces, enclose it in backticks (`):
Example:
~`\d{4} \w+`
Negative Filters
To exclude logs containing specific words or phrases, prefix the term with a minus sign (-).
Example: The query error -ssh will find error logs that do not contain the word ssh.
Combining Filters
You can combine multiple filter types in a single query:
Example: error "database connection" -timeout ~\d{3} will find logs that:
- Contain the word "error"
- Contain the exact phrase "database connection"
- Do not contain the word "timeout"
- Match the regular expression
\d{3}(three digits)
Search Scope
The search scope defines which attributes Uptrace searches when filtering spans and logs. By default, the search scope corresponds to your current grouping expression.
Default Search Scopes
| Grouping Expression | Search Scope |
|---|---|
group by _group_id | display_name |
group by service_name, host_name | service_name, host_name |
group by _group_id, service_name | display_name, service_name |
Custom Search Scopes
You can specify custom search scopes for any filter type by using the attribute:value syntax:
Examples:
host_name:host1
service_name:"hello world"
~span_name:user.*
message:-"connection failed"
This allows you to search specific attributes regardless of your current grouping configuration.
Filter Syntax Reference
| Filter Type | Syntax | Description | Example |
|---|---|---|---|
| Word | word | Matches logs containing the word | error |
| Multiple words (AND) | word1 word2 | All words must be present | error database |
| Multiple words (OR) | word1|word2 | Any word must be present | error|warning |
| Phrase | "phrase" | Exact phrase match | "connection timeout" |
| Regular expression | ~pattern | Regex pattern match | ~\d{3}-\d{3}-\d{4} |
| Regular expression with spaces | ~`pattern` | Regex with spaces | ~`error \d+` |
| Negative filter | -term | Excludes logs with term | -debug |
| Scoped filter | attribute:value | Search specific attribute | host_name:prod-server |
Tips for Effective Searching
- Case insensitive: All text searches are case-insensitive by default
- Partial matching: Word filters match partial words (e.g.,
errmatcheserror) - Combine filters: Use multiple filter types together for precise results
- Use quotes: Always quote phrases and values containing spaces or special characters
- Escape special characters: In regex patterns, remember to escape special characters as needed