Searching logs

Run one-shot queries with bronto search, build filters with flags, aggregate, summarize, and explore interactively.

bronto search runs one query and exits. The query is a Bronto WHERE expression, the same language the web app’s search bar uses. The search syntax page on docs.bronto.io documents it in full. Under the hood, bronto search calls the search API.

Narrowing 502s in checkout-service

​

The basics

$ bronto search "status >= 500" -d prod/checkout-service --since 1h
@TIME                        @STATUS  MESSAGE_KVS.TRACE_ID              MESSAGE_KVS.DURATION_MS  MESSAGE_KVS.HOST  MESSAGE_KVS.MESSAGE                               MESSAGE_KVS.PATH  MESSAGE_KVS.SERVICE
2026-07-19 09:24:49.632 UTC  error    f7df498a556927026404a9f1e89c38e2  30042                    web-3             payment failed: payments-api timed out after 30s  /api/checkout     checkout-service
2026-07-19 09:24:33.007 UTC  error    168a296e219517ed2119957be0ed85c1  30034                    web-3             payment failed: payments-api timed out after 30s  /api/checkout     checkout-service
...

• Dataset. -d/--dataset takes a dataset name or UUID and can be repeated to search several at once. Qualify a name that exists in more than one collection as collection/name. Without -d, the CLI uses default_dataset from your config, or the only dataset if the account has just one. Otherwise it fails with usage_missing_dataset and lists the datasets it found. --from-expr takes a dataset selector expression instead, for example --from-expr "log_id = '<uuid>'".
• Time range. --since takes a relative lookback such as 30s, 15m, 1h, 2d, 1w, or 1h30m. For a fixed window, pass RFC 3339 timestamps with --from and --to; --from must not be later than --to. With no time flag, the search covers the last 15 minutes.
• Size and order. -n/--limit caps the number of events (1 to 10000, default 100). Results come newest first. --oldest-first flips that, and --order-by takes an SQL-style order such as 'duration_ms DESC'.
• Stdin. Pass - as the query to read it from stdin, which helps with long queries and quoting.

At a terminal, the result is a table. The CLI ranks parsed fields by how often they hold a value and how much they vary, and turns the best ones into columns. Once it has three useful columns it drops the raw JSON. A footer on stderr points to bronto fields, --select, and -x.

​

Filter flags instead of WHERE

The filter flags build the WHERE expression for you:

Flag	Keeps events where the field…
--eq field=value	equals the value
--ne field=value	does not equal the value
--gt, --ge, --lt, --le	is greater than, greater or equal, less than, less or equal
--match field=regex	matches the regex
--nmatch field=regex	does not match the regex

$ bronto search -d prod/checkout-service --ge status=500 --gt duration_ms=1000 --since 1h
@TIME                        @STATUS  MESSAGE_KVS.TRACE_ID              MESSAGE_KVS.DURATION_MS  MESSAGE_KVS.HOST  MESSAGE_KVS.MESSAGE                               MESSAGE_KVS.PATH  MESSAGE_KVS.SERVICE
2026-07-19 09:24:49.632 UTC  error    f7df498a556927026404a9f1e89c38e2  30042                    web-3             payment failed: payments-api timed out after 30s  /api/checkout     checkout-service
2026-07-19 09:24:33.007 UTC  error    168a296e219517ed2119957be0ed85c1  30034                    web-3             payment failed: payments-api timed out after 30s  /api/checkout     checkout-service
...

Each flag can be repeated. The CLI ANDs them together, and with the positional query if you pass one. The CLI looks up each field name in the dataset’s field index, so model finds $model and matching is case-insensitive. It quotes the value based on its shape: plain numbers stay bare, and everything else gets single quotes, booleans included, because Bronto compares boolean fields as the strings 'true' and 'false'. The compiled filter is echoed to stderr.

• --show-query prints the compiled WHERE and exits without searching.
• --exact turns off the fuzzy name lookup and uses field names as written. Use it in scripts.
• An unknown or ambiguous field name is an error (exit code 2) that lists candidates.

$ bronto search -d prod/checkout-service --ge status=500 --eq service=checkout-service --show-query
status >= 500 AND service = 'checkout-service'

​

Look closer at events

-x/--expand is the “click on a row” view. It prints every field of every event, one per line and untruncated, including the metadata.* fields the table hides.

$ bronto search "status >= 500" -d prod/checkout-service --since 1h -n 2 -x
─ event 1 ──────────────────────────────
@time                    2026-07-19 09:24:49.632 UTC
@status                  error
@raw                     {"level":"error","service":"checkout-service","host":"web-3","message":"payment failed: payments-api timed out after 30s","path":"/api/checkout","status":502,"duration_ms":30042,"trace_id":"f7df498a556927026404a9f1e89c38e2"}
message_kvs.duration_ms  30042
message_kvs.host         web-3
message_kvs.message      payment failed: payments-api timed out after 30s
message_kvs.path         /api/checkout
message_kvs.service      checkout-service
message_kvs.status       502
message_kvs.trace_id     f7df498a556927026404a9f1e89c38e2
metadata.logId           0b7c6f2e-1d4a-4c8e-9a51-3f2d8e6b7a10
metadata.origin          web-3
metadata.sequence        48211195
metadata.timestamp       1784453089632
─ event 2 ──────────────────────────────
...

-x only works with table output. When piped, add -o table. The JSON formats already carry every field.

To see what happened around one event, use bronto context. It needs the event’s metadata.sequence value and its timestamp in Unix milliseconds, both visible in the -x view:

bronto context --sequence <sequence> --timestamp <unix-ms> -d prod/checkout-service
bronto context --sequence <sequence> --timestamp <unix-ms> -d prod/checkout-service --direction before -n 20

--direction is before, after, or both (the default), and -n sets how many events to fetch in each direction.

​

Find the right field names

bronto fields lists the fields seen in a dataset, each with a sample of values, so you can spell a query correctly the first time. Add a positional filter to keep only fields whose name contains it:

$ bronto fields -d prod/checkout-service --since 1h
KEY          COUNT  TYPE    SOURCE   VALUES
duration_ms  76     number  message  123, 124, 148, 158, 32, …
host         76     string  message  web-1, web-2, web-3
...
$ bronto fields -d prod/checkout-service status
KEY     COUNT  TYPE    SOURCE   VALUES
status  76     number  message  200, 502

Leave out -d to scan all datasets. --since (default 1h) sets how far back to look and -n caps the number of fields.

bronto query check validates an expression locally, without calling the API, and points a caret at the problem:

$ bronto query check "status >= 500 AND service = 'checkout-service'"
✓ valid — fields: service, status

It accepts the same search syntax as the API, including IN, LIKE, IS NULL, and free-text terms like "slow to respond". It also warns about an unquoted value such as level = error: the query language reads a bare word on the right of an operator as a field name, so that query compares two fields. With -d <dataset> it also warns about fields that haven’t appeared in that dataset recently and suggests close matches. --strict turns those field warnings into a failure for use in CI.

Piped or with -o json, the result is a JSON object, and - reads the query from stdin:

$ echo "status IN (500, 502) AND level = error" | bronto query check - | jq -c .
{"fields":["error","level","status"],"valid":true,"warnings":["error in `level =` names the attribute \"error\", not a string — write 'error' to compare against the text"]}

​

Aggregate

--select picks columns or aggregate functions, and -g/--group-by groups by one or more keys. Both are repeatable.

$ bronto search --select "count()" -g host -d prod/checkout-service --since 30m
COUNT  GROUP  STAT     VALUE
28     web-2  count()  28
26     web-1  count()  26
22     web-3  count()  22

For timeseries aggregates, --slices sets the number of time buckets.

​

Summaries

Two flags summarize a result instead of listing events.

--histogram shows when matching events happened, which answers “when did this start and how big is it?”:

$ bronto search "status >= 500" -d prod/checkout-service --since 1h --histogram
09:00   0
...
09:20   0
09:21  ████████████████████████ 3
09:22  ████████████████████████████████████████ 5
09:23  ████████████████████████████████████████ 5
09:25   0
...
total: 13 events (bucket: 1m15s)

All 13 errors land in the few buckets after 09:21. Empty buckets print 0, so a quiet period before a spike is easy to see.

--patterns clusters events into message templates with counts, which shows what a noisy dataset is mostly made of (learn more about patterns). It clusters the parsed message field when events have one, and the raw line otherwise:

$ bronto search "" -d prod/checkout-service --since 1h --patterns
COUNT  PATTERN
36     checkout completed
24     cart loaded
13     payment failed: payments-api timed out after <num>
3      payments-api slow to respond (<num>)

​

Saved searches and the web UI

--saved <name> runs a saved search by name or id. Query, dataset, and time flags you pass on the command line override what’s stored.

bronto saved-searches list
bronto search --saved <saved-search-name> --since 30m

Saved searches are a regular resource, so bronto saved-searches create, update, and delete manage them.

--url prints a link to the same query in the Bronto web app, and --open opens it in your browser. Neither runs the query. The link targets your active org. If the CLI can’t work out the org, set it with bronto config set org_id <uuid>.

--explain-only returns the query plan and cost estimate instead of results, as one JSON document, so -o csv is rejected.

​

Search local files

--local <file> evaluates the query on your machine over an NDJSON or plain-text file. Nothing is sent to Bronto and no API key is needed, so it works on downloaded exports or a kubectl logs dump. Pass - to read stdin.

kubectl logs deploy/checkout | bronto search --local - "status >= 500"
bronto search --local export.ndjson "path = '/api/checkout'" -o jsonl --fields @time,path

JSON lines are queryable by their keys (nested keys in dotted form). A bare field name also matches its message_kvs.<field> key, so a bronto search -o jsonl dump answers the same query you ran against Bronto. Plain-text lines are matched with @raw ~ 'regex'. -o, --fields, --jq, and -n work. Matches print in file order. Dataset, time range, select, and group-by flags don’t apply and are rejected, as are --histogram, --patterns, --url, --open, --order-by, --oldest-first, and --saved.

​

The REPL

For a longer investigation, bronto repl opens a psql-style prompt. Type a WHERE expression to run it, then edit it and run it again.

bronto repl -d prod/checkout-service --since 1h

Meta-command	What it does
\since <duration>	change the time window
\d <dataset>	switch dataset
\limit <n>	change the result limit
\more	fetch the next page
\fields	list field names
\tail	follow live until Ctrl-C
\help	list meta-commands
\q	quit

History is saved in your config directory between sessions. The REPL needs a terminal. Piped, it exits with code 2.

To go from a question in plain English to a query, see Ask.