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

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 will find logs that:

• Contain the word "error"
• Contain the exact phrase "database connection"
• Do not contain the word "timeout"

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

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"

This allows you to search specific attributes regardless of your current grouping configuration.

Searching Indexed Content

If you have configured a text index transformation to index selected attributes, you can search across all indexed content using the *:value syntax:

Examples:

*:hello
*:error|warning
-*:debug

The * scope searches the full-text index built from your selected attributes. Multiple values separated by | match if any value is found. Prefix with - to exclude matching results.

Filter Syntax Reference

Tips for Effective Searching

• Case insensitive: All text searches are case-insensitive by default
• Partial matching: Word filters match partial words (e.g., err matches error)
• Combine filters: Use multiple filter types together for precise results
• Use quotes: Always quote phrases and values containing spaces or special characters