Fetch logs with optional filtering

Changed on

Fetch log lines newest-first, paging backwards towards the start of the file. When level or keyword is set the server keeps reading backwards until the requested number of matching lines has been collected, the start of the file is reached, or the per-request scan cap (32 MiB) is hit — so has_more means "more matches may exist", not merely "more bytes exist". Offsets in next_cursor are byte offsets into the file the page was read from; for a .log.gz archive they address the uncompressed stream.

get/logs

Request

  • Base URL
    http://0.0.0.0:11111/netlox/v1
  • URL
    http://0.0.0.0:11111/netlox/v1/logs
  • Auth
    API key in header Authorization

Query parameters

linesstring

Number of log lines to fetch (default is 100). With level or keyword set this is the number of matching lines.

levelstring

Filter logs by level (e.g., INFO, ERROR, DEBUG). Matched as a substring, searched backwards across the whole file rather than within one page.

keywordstring

Filter logs containing a specific keyword or phrase. Matched as a substring, searched backwards across the whole file rather than within one page.

cursorstring

Opaque pagination cursor from a previous response's next_cursor; fetches the next page.

filestring

Specific log file to read (default is the current log file). Rotated .log.gz archives are accepted and decompressed transparently.

Response

Logs fetched successfully

logsstring[]

Log lines for this page, newest first. Empty rather than null when nothing matched.

log_filestring

Name of the log file the lines were read from.

log_countinteger required

Number of lines in this page — that is, the length of logs after filtering. Not a count of matches in the file.

total_sizeinteger required

Size in bytes of the whole log file, independent of this page and of any filter. For a .log.gz archive this is the uncompressed size, since offsets address the decompressed stream.

has_moreboolean required

Whether the backwards scan stopped before the start of the file, i.e. older lines remain to be searched. True implies next_cursor is set. Unfiltered this means more lines exist; filtered it means more matches may exist — the final page of a filtered search can legitimately come back empty.

next_cursorstring

Opaque cursor for the next (older) page; present only when has_more is true.

scanned_bytesinteger required

Bytes examined to build this page. Equal to the page's own span when unfiltered; larger for a filtered query that had to search backwards past non-matching lines. Compare against total_size to show progress through a long search.

Changes