Search and tail¶
SQL search over any stream plus the helpers OpenObserve offers next to it.
| Function | Request | Defaults |
|---|---|---|
search(sql, {start, end, from, size, trackTotalHits, type}) |
POST /api/{org}/_search?type=logs |
last 15 min, from 0, size 100 |
searchAround(stream, timestamp, size) |
GET /api/{org}/{stream}/_around?key=<µs>&size= |
10 rows, anchor included |
valuesOf(stream, fields, {start, end, size}) |
GET /api/{org}/{stream}/_values?fields=a,b |
last 15 min, 10 values per field |
histogram(stream, {start, end, interval, filter}) |
SELECT histogram(_timestamp, '<interval>') … via _search |
last 15 min, interval chosen by the server |
tail(stream, onRow, {filter, start, interval, overlap, pageSize, onError}) |
_search polling with a _timestamp cursor |
start now, every 1 s, 1 s overlap, 1000 rows per poll |
search¶
- Quote stream names with double quotes:
SELECT * FROM "app". WithoutORDER BYrows come newest first. Find text withmatch_all('x'),str_match(field, 'x')orre_match(field, 're'). start/endare converted to epoch microseconds;start > end→VALIDATION.- A
LIMITin the SQL overridessize;size0 or -1 means the server's default limit. - The server's
totalis the number of rows in this page. WithtrackTotalHitsthe SDK sends a second count request (track_total_hits: true,from: 0) and fillstotalHitswith the exact number of matching rows. - The result carries
hits(flat rows with_timestampin µs),total,from,size,took(ms),scanRecords,isPartial,histogramIntervalandrequestId(the server's search id).
use std::time::{Duration, SystemTime};
use grow_openobserve::logs::SearchOptions;
use grow_openobserve::Timestamp;
let res = client
.logs()
.search(
"SELECT * FROM \"app\" WHERE level = 'error' ORDER BY _timestamp DESC",
SearchOptions::default()
.range(Some(Timestamp::Time(SystemTime::now() - Duration::from_secs(3600))), None)
.page(0, 50)
.track_total_hits(true),
)
.await?;
println!("{:?} {}", res.total_hits, res.hits.len());
searchAround, valuesOf, histogram¶
searchAround returns up to size rows around one timestamp, split before and after it, with
the anchor row included; pass the exact _timestamp (µs) of a row or a time. TypeScript, Python
and Rust also accept a sql option, which OpenObserve v1.1.2 accepts but ignores (the rows are
not filtered); see Compatibility.
valuesOf returns the most frequent values of each field with their counts. histogram returns
{start, key, count} buckets plus the bucket width in seconds; interval looks like "1 minute"
(Go and Java take a duration and format it), filter is a SQL WHERE condition.
const anchor = res.hits[0]!._timestamp as number;
const around = await client.logs.searchAround("app", anchor, { size: 20 });
const values = await client.logs.valuesOf("app", ["level", "service_name"], { size: 5 });
const hist = await client.logs.histogram("app", { interval: "1 minute", filter: "level = 'error'" });
hist.buckets.forEach((b) => console.log(b.start.toISOString(), b.count));
use grow_openobserve::logs::{HistogramOptions, SearchAroundOptions, ValuesOptions};
use grow_openobserve::Timestamp;
let around = logs
.search_around("app", Timestamp::Micros(anchor), SearchAroundOptions { size: 20, ..Default::default() })
.await?;
let values = logs.values_of("app", &["level", "service_name"], ValuesOptions::default()).await?;
let hist = logs
.histogram("app", HistogramOptions {
interval: Some("1 minute".into()),
filter: Some("level = 'error'".into()),
..Default::default()
})
.await?;
around, err := client.Logs().SearchAround(ctx, "app", anchorTime, 20)
values, err := client.Logs().ValuesOf(ctx, "app", []string{"level", "service_name"}, openobserve.ValuesOptions{Size: 5})
hist, err := client.Logs().Histogram(ctx, "app", openobserve.HistogramOptions{Interval: time.Minute, Filter: "level = 'error'"})
for _, b := range hist.Buckets {
fmt.Println(b.Start, b.Count)
}
SqlSearchResult around = client.logs().searchAround("app", anchor, 20);
List<FieldValues> values = client.logs().valuesOf("app", List.of("level", "service_name"));
HistogramResult hist = client.logs().histogram("app",
HistogramOptions.of(null, null, Duration.ofMinutes(1), "level = 'error'"));
hist.buckets().forEach(b -> System.out.println(b.start() + " " + b.count()));
tail¶
OpenObserve has no live tail, so tail polls _search with a _timestamp cursor:
- Every poll queries
_timestamp >= max(start, cursor − overlap)in ascending order and pages through full pages. The overlap catches rows that arrive late; it never reaches back beforestart, so rows older thanstartare never delivered. - Rows already delivered are dropped by full-row equality, so two identical rows within the overlap window are delivered once.
- Query errors go to
onError(Go: a debug log line when no callback is set) and polling continues; a throwing callback does not stop the tail.stop()is idempotent.
The category method logQuery(stream).tail(query, onRecord) (Log client and search)
uses the same mechanism and delivers normalized LogRecords instead of raw rows.