Searching logs

The shape of a query #

A query is a sequence of terms. The default operator between them is AND, so a bare list of terms narrows progressively. Bare words match the message text.

timeout            a bare word, matched in the message
service:checkout  a field equals a value
status:error      severity is error

Boolean logic #

Uppercase operators group terms the way you would expect. Parentheses override the default grouping.

service:checkout AND status:error
service:checkout OR service:payments
NOT status:debug
-status:debug              the same negation, shorter
(service:checkout OR service:payments) AND status:error

Comparisons #

Numeric fields accept the full set of comparators. Values are read as numbers, so quoting them is optional.

http.status_code>=500
http.status_code<300
duration>1000
http.status_code!=404

Ranges #

The [a TO b] form is inclusive at both ends, and is the clearest way to express a band.

http.status_code:[500 TO 599]
duration:[100 TO 500]
http.status_code:[500 TO *]

Wildcards #

An asterisk inside a value matches any sequence. Put it where you would expect one in a regular expression.

service:check*          services beginning with check
service:*gateway*       services containing gateway

Custom attributes #

Your own attributes are prefixed with @. Reserved attributes are queried without a prefix.

• env, service, version, host, status
• resource_name, operation_name, trace_id, span_id
• timestamp, type

@payment.provider:stripe
@order.id:8821
service:checkout

Matching on correlation #

Logs carry trace and span identifiers when the sender can correlate them. That is how one search moves from a log line to the request that produced it.

trace_id:5b8efff798038103d269b633813fc60c
@http.status_code:[400 TO 599]

Severity #

Severity values map onto four levels. Source-specific spellings are recognised, so a log saying WARN and one saying warning land on the same level.

• error — error, fatal, critical, emerg, alert
• warn — warn, warning
• info — info
• debug — debug, trace

Facets #

The log explorer offers counts for these attributes so you can click to narrow. They are the fastest way to explore an unfamiliar service.

• status
• service
• source
• host
• env
• http.status_code

Sorting #

Sort by any of these keys, ascending or descending. Newest first is the default.

• timestamp
• service
• status
• host
• env
• version

Escaping #

A value containing a reserved character is escaped with a backslash. These characters are reserved: ? > < : = " ~ / \ and whitespace.

@message.key:my\:key

A worked example #

Find server errors from the checkout service in production over the last hour, excluding debug noise.

service:checkout env:production status:error http.status_code:[500 TO 599]