Query syntax reference

Pulse has one query syntax for logs, spans and errors. The same text works in log search, the histogram and facets, CSV export, saved views, log monitors and live tail. Spans and errors use the same rules with their own reserved fields.

A query that cannot be parsed is rejected with the position (0-based character index) of the problem, for example Missing term at position 9. You can check a query without running it: GET /api/v1/pulse/projects/{projectId}/query/validate?q=...&dataset=logs (or dataset=spans) answers {"valid": true} or a 400 with error and position.

Quick examples

Examples

service:checkout status:error
timeout AND NOT service:billing
"connection reset" env:prod
@http.status_code:>=500
@duration:[1s TO 5s]
cloud.region:eu-* -k8s.namespace.name:test
@user.id:*
-pattern:3f2a9c1d5e7b8a01
service:(api OR worker) status:(error OR critical)

Grammar

Grammar (EBNF)

query      = or ;
or         = and { "OR" and } ;
and        = unary { [ "AND" ] unary } ;            (* adjacency means AND *)
unary      = ( "NOT" | "-" ) unary | primary ;
primary    = "(" or ")" | term ;
term       = quoted | word | field ":" value ;
field      = [ "@" ] name ;                         (* name: letter or _, then letters, digits, _ . - / *)
value      = "(" value-or ")"                       (* service:(a OR b) *)
           | ( ">" | ">=" | "<" | "<=" ) number
           | ( "[" | "{" ) bound "TO" bound ( "]" | "}" )   (* [ ] inclusive, { } exclusive, bound = number | * *)
           | quoted | word ;                        (* word "*" alone means "field exists" *)
number     = decimal [ "ns" | "us" | "µs" | "ms" | "s" | "m" | "h" ] ;   (* a unit makes it a duration in nanoseconds *)

Operators

• AND, OR and NOT must be upper-case.
• AND binds tighter than OR.
• Two terms side by side mean AND.
• - in front of a term is the same as NOT.
• Parentheses group terms.

Free text

A term without a field searches the message.

Form	Matches
timeout	Whole words, case-insensitive. It matches “Timeout after 30s” but not “timeouts”.
order-42	A word with separators must appear as written.
"connection reset"	A case-insensitive substring.
time*, ti?eout	* and ? are wildcards.

For spans, free text searches the resource, the operation and the error message. For errors, it searches the type and the message.

Fields

Reserved fields (no @)

Reserved fields match exactly, or with wildcards. Numeric comparisons on them are rejected.

Dataset	Reserved fields
Logs	service, status (case-insensitive), host, env, version, source, trace_id, span_id (case-insensitive)
Spans	service, env, version, host, resource, operation (the span name), kind, status (ok or error), peer.service, trace_id, span_id, parent_id
Errors	service, env, version, host, resource, source (span, log or browser), trace_id, span_id

For spans, @duration (in nanoseconds), @error.type, @error.message and @error.stack are also available. For errors, @error.type, @error.message and @error.stack.

Attributes (@)

@key addresses an event attribute by its dotted key, such as @http.status_code or @user.id.

Form	Meaning
@http.method:GET	Exact string match; wildcards allowed
@http.status_code:>=500	Comparison (>, >=, <, <=); needs a number
@duration:[1s TO 5s]	Range with [ ] inclusive or { } exclusive bounds; * as an open bound
@duration:>500ms	A unit (ns, us, µs, ms, s, m, h) makes the number a duration, compared in nanoseconds

Tags (no @)

Any other key:value without @ addresses resource tags, for example cloud.region:eu-* or k8s.namespace.name:prod. For spans, @attribute and tag terms address span attributes and resource attributes. For errors they address event and resource attributes.

Presence

field:* tests that the field exists; -field:* tests that it does not.

Message patterns (logs only)

pattern:<id> matches the logs of one message pattern from the Patterns view; -pattern:<id> hides them. It works wherever a log query works: search, histogram, facets, export, saved views, log monitors and live tail.

Escaping

Escape special characters with a backslash: \:, \*, \(. Every value is bound as a query parameter, so what you type reaches the database exactly as typed.

Limits

Limit	Value
Query length	2,000 characters
Terms	64
Nesting levels	16

Note

The live tail filters in memory with the same parsed query and the same semantics as the stored search, so the tail shows what a search over the same range would show.

Where the syntax is used

• Log search, histogram, facets and CSV export, and saved views (a named query with its time range, facets and columns).
• Live tail.
• Span search in the trace explorer.
• Error search and fingerprint rules.
• Monitors: the query of a log, APM or error-tracking monitor, and groupBy fields.
• Pulse queries generated by Lumen, which are validated before they are shown.