Advanced Search Syntax

Advanced Search is the query box on the Traces and Logs pages. It uses the Apache Lucene query syntax: conditions written as field:value, joined with AND, OR and NOT.

1ServiceName:checkout AND Duration:>500ms

Open it with the </> tile at the right of the search bar. As you type, the suggestions offer the fields, the operators that fit each field, and its values.

Traces

Logs

Slow requests of one service, built from the suggestions.

Error logs that mention a timeout.

Search syntax#

A query is one or more conditions. A condition is a field, a colon and a value.

1ServiceName:checkout

Conditions are combined with boolean operators:

A value that contains spaces or symbols goes in double quotes.

1SpanName:"GET /api/orders"

Fields#

Built-in fields have plain names.

• Traces: ServiceName, SpanName, Duration, StatusCode, StatusCodeString, SpanKind, TraceId, SpanId, ParentSpanId
• Logs: ServiceName, SeverityText, Body, TraceId, SpanId

Attributes carry a prefix that says which part of the span or log they come from.

Pick http.status_code from the suggestions and the bar writes span.http.status_code. An attribute that is not listed still works when typed in full.

Text search#

Text fields hold free text: SpanName, StatusMessage, span.db.query.text, exception messages and the log Body. On these fields, a value matches words.

• Body:timeout matches the word anywhere in the message.
• Body:"connection refused" matches the two words in that order.
• Body:"connection refused"~3 matches them within three words of each other.
• SpanName.keyword:"GET /api/orders" matches the whole span name, character for character.

A word typed on its own searches the span name on Traces and the message on Logs.

1timeout

Wildcards#

• * stands for any number of characters.
• ? stands for one character.

1ServiceName:check*
2ServiceName:*out*
3ServiceName:checkou?

Wildcard matches ignore case. Inside quotes, * and ? are plain characters.

Numerical values#

Compare numbers and durations with >, >=, < and <=.

1span.http.status_code:>=500
2Duration:>500ms

Search a range with [a TO b]. Square brackets include the ends, curly brackets exclude them, and * leaves an end open.

1Duration:[100ms TO 2s]
2span.http.status_code:[400 TO 499]
3Duration:[1s TO *]

Durations take ns, us, ms, s, m or h. A bare number means milliseconds.

Regular expressions#

Write the pattern between slashes, in RE2 syntax. On an exact field the pattern must match the whole value; on a text field it is searched for.

1ServiceName:/check(out|in)/
2Body:/user [0-9]+ locked/

Add ~ to a word to allow one typo, or ~2 to allow two.

1ServiceName:chekout~

Escaping special characters#

Quote a value that contains a space or any of these characters: : " ( ) [ ] { } ~ ^ * ?

1Body:"[ERROR] disk full"
2SpanName:"AND"

Inside quotes, write a literal " or \ with a backslash in front.

[ and { only open a range, directly after a field. Typed anywhere else they are not accepted.

Autocomplete#

The suggestions follow what you type.

1. Fields: type part of a name to narrow the list.
2. Operators: after field:, the ways to match that fit the field.
3. Values: the most frequent values in the selected time range.
4. Combine: after a finished condition, AND, OR, NOT or the next field.

Under the bar, Searching for: reads the query back in plain words. If an attribute or value is not listed, keep typing it and choose Find attributes containing "…" or Fetch values starting with "…" at the bottom of the list.

Examples#