Skip to content

Log queries

All log queries go to the query API with the SIGNOZ-API-KEY header. Filters are SigNoz search expressions (service.name = 'checkout' AND severity_text IN ('ERROR')); build them safely with the FilterBuilder. Bare words search the body.

Function Request Defaults and behaviour
queryLogs POST /api/v5/query_range, requestType: raw, signal logs window last hour, limit 100 (max 10,000), order desc (ties by id), optional selectFields; returns normalized records, nextCursor and warnings
search same as queryLogs the shared LogQueryClient form: search(query, {start, end, limit, order, cursor}) → LogSearchResult
tail GET /api/v3/logs/livetail (server-sent events) calls onRecord per new record; reconnects after the stream ends (default 1 s) from the last seen timestamp and skips records already delivered (by id); AUTHENTICATION, PERMISSION_DENIED and UNSUPPORTED stop it after onError
listStreams GET /api/v1/fields/values?signal=logs&name=service.name services that sent logs (SigNoz has no streams; service.name is the natural stream)
listLabels GET /api/v1/fields/keys?signal=logs attribute and resource field names
listLogFields GET /api/v1/fields/keys?signal=logs LogField {name, context, dataType}; optional search text and limit
listFieldValues GET /api/v1/fields/values values of one field (source logs or traces, optional search text)
waitForLog polls search test helper: first record matching query (and an optional predicate) within the timeout (default 30 s), else TIMEOUT

Paging: the SDK's own keyset cursor

The server's nextCursor is the last row's millisecond and skips the other rows of that millisecond. The SDK pages with its own cursor instead: the next page repeats the boundary millisecond and excludes the ids already returned in it (id NOT IN (...)), so no row is lost or repeated. The cursor is opaque but has the same wire format in every language:

base64url (no padding) of {"v":1,"s":<startMs>,"e":<endMs>,"o":"asc|desc","m":<boundaryMs>,"x":[ids]}

"x" may be null or missing (Go writes null when no ids are excluded); every language accepts both. A cursor fixes the window and the order of the first page; pass the same filter with it.

import { FilterBuilder } from "@grow-codes/signoz";

const filter = new FilterBuilder().eq("service.name", "checkout").in("severity_text", ["ERROR", "FATAL"]);
let cursor: string | undefined;
do {
  const page = await client.query.queryLogs({ filter, limit: 500, ...(cursor ? { cursor } : {}) });
  for (const r of page.records) console.log(r.timestamp, r.severityText, r.body);
  cursor = page.nextCursor;
} while (cursor !== undefined);

const hits = await client.logs.search("timeout", { limit: 20 });
const handle = client.logs.tail("severity_text = 'ERROR'", (r) => console.log(r.body));
handle.stop();
console.log(await client.logs.listStreams(), await client.logs.listLabels());
console.log(await client.query.listLogFields({ search: "http" }));
console.log(await client.query.listFieldValues("service.name"));
const one = await client.logs.waitForLog("body CONTAINS 'order 42'", { timeoutMs: 30_000 });
use std::sync::Arc;
use grow_signoz::logging::{LogQueryClient, LogRecord, SearchOptions, TailOptions, WaitOptions};
use grow_signoz::{FieldValuesOptions, FilterBuilder, ListFieldsOptions, LogQuery};

let q = client.query();
let filter = FilterBuilder::new()
    .eq("service.name", "checkout")
    .in_list("severity_text", ["ERROR", "FATAL"])
    .build()?;
let mut cursor = None;
loop {
    let mut lq = LogQuery::new(filter.as_str()).limit(500);
    if let Some(c) = cursor.take() {
        lq = lq.cursor(c);
    }
    let page = q.query_logs(lq).await?;
    for r in &page.records {
        println!("{} {}", r.severity_text, r.body);
    }
    match page.next_cursor {
        Some(c) => cursor = Some(c),
        None => break,
    }
}
let hits = q.search("timeout", SearchOptions::default()).await?;
let handle = q
    .tail(
        "severity_text = 'ERROR'",
        Arc::new(|r: LogRecord| println!("{}", r.body)),
        TailOptions::default(),
    )
    .await?;
handle.stop();
let streams = q.list_streams().await?;
let fields = q.list_log_fields(ListFieldsOptions::default()).await?;
let values = q.list_field_values("service.name", FieldValuesOptions::default()).await?;
let one = q.wait_for_log("body CONTAINS 'order 42'", WaitOptions::default()).await?;
q := client.Query()
filter, err := signoz.NewFilter().Eq("service.name", "checkout").In("severity_text", "ERROR", "FATAL").Build()
if err != nil {
    return err
}
cursor := ""
for {
    page, err := q.QueryLogs(ctx, signoz.LogQuery{Filter: filter, Limit: 500, Cursor: cursor})
    if err != nil {
        return err
    }
    for _, r := range page.Records {
        fmt.Println(r.Timestamp, r.SeverityText, r.Body)
    }
    if cursor = page.NextCursor; cursor == "" {
        break
    }
}
hits, err := q.Search(ctx, "timeout", signoz.SearchOptions{Limit: 20})
handle, err := q.Tail(ctx, "severity_text = 'ERROR'", func(r signoz.LogRecord) { fmt.Println(r.Body) }, signoz.TailOptions{})
handle.Stop()
streams, err := q.ListStreams(ctx)
fields, err := q.ListLogFields(ctx, signoz.ListFieldsOptions{})
values, err := q.ListFieldValues(ctx, "service.name", signoz.FieldValuesOptions{})
rec, err := q.WaitForLog(ctx, "body CONTAINS 'order 42'", signoz.WaitForLogOptions{Timeout: 30 * time.Second})
flt = sdk.FilterBuilder().eq("service.name", "checkout").in_("severity_text", ["ERROR", "FATAL"])
cursor = None
while True:
    page = client.query.query_logs(flt, limit=500, cursor=cursor)
    for r in page.records:
        print(r.timestamp, r.severity_text, r.body)
    if (cursor := page.next_cursor) is None:
        break

hits = client.logs.search("timeout", limit=20)
handle = client.logs.tail("severity_text = 'ERROR'", lambda r: print(r.body))
handle.stop()
print(client.logs.list_streams(), client.logs.list_labels())
print(client.query.list_log_fields(search="http"), client.query.list_field_values("service.name"))
one = client.logs.wait_for_log("body CONTAINS 'order 42'", timeout_s=30)
SignozQueryClient q = client.query();
String filter =
    FilterBuilder.create().eq("service.name", "checkout").in("severity_text", "ERROR", "FATAL").build();
String cursor = null;
do {
  LogQueryResult page = q.queryLogs(LogQuery.builder().filter(filter).limit(500).cursor(cursor).build());
  page.records().forEach(r -> System.out.println(r.severityText() + " " + r.body()));
  cursor = page.nextCursor().orElse(null);
} while (cursor != null);

LogSearchResult hits = q.search("timeout", SearchOptions.builder().limit(20).build());
TailHandle handle = q.tail("severity_text = 'ERROR'", r -> System.out.println(r.body()), TailOptions.defaults());
handle.stop();
List<String> streams = q.listStreams();
List<LogField> fields = q.listLogFields();
List<Object> values = q.listFieldValues("service.name", FieldValuesOptions.defaults());
LogRecord one = q.waitForLog("body CONTAINS 'order 42'", WaitForLogOptions.of(Duration.ofSeconds(30), Duration.ofSeconds(1)));

Record mapping

Rows are normalized to the shared LogRecord: timestamp (nanoseconds), severity from severity_number (else parsed from severity_text, else INFO), severityText (the server text, else the severity name), body, attributes (string, number and bool attribute maps merged), resource (resources_string), traceId/spanId (lower-case hex) and traceFlags. TypeScript records also carry the SigNoz row id and timeUnixNano (a decimal string, exact beyond 2^53).