SQLStreams

the messaging platform that is just Postgres

You last visited on 9999-99-99 Show what's new since then
View previous thread::View next thread

Metric commands

Edit this page
System · Related pages
Posted: 2026-09-17 · Report this thread
brandon Site Admin brandon profile Posts: 96
sqlstreams metric latest sqlstreams.consumer.cursor.backlog \
  --attribute stream=payments.requested --attribute group=charge-cards

Reads retained metric measurements. These commands do not collect a fresh database snapshot. Check each measurement’s at for freshness.

List series

sqlstreams metric list [--builtin | --user] [--quiet]
Flag Default Effect
--builtin false Only names starting with sqlstreams..
--user false Only other names. Cannot be combined with --builtin.
--quiet, -q false Print series keys, one per line. Cannot be combined with JSON output.

With neither filter, lists all retained series. Output is a table of current measurements or a JSON array of Measurement objects. An empty list exits 0 with JSON [].

Latest and history

sqlstreams metric latest <name> [--attribute key=value] [--series-limit 10]
sqlstreams metric history <name> [--attribute key=value] [--series-limit 10] [--limit 10]
sqlstreams metric history sqlstreams.consumer.cursor.backlog \
  --attribute stream=payments.requested --attribute group=charge-cards \
  --limit 20 --output json
Flag Default Effect
--attribute No filter Repeatable key/value filters. All pairs must match. Repeating an identical pair is accepted. Conflicting values for the same key exit 2.
--series-limit 10 Positive maximum attribute sets to display.
--limit 10 history only. Positive maximum measurements per series, newest message id first.

Attribute filters are partial. Omitted attributes can vary across matching series, unlike the Go API’s exact-series selector. An empty filter value requires the attribute to exist with an empty value. Selection starts from currently retained series heads, then history reads each selected series.

JSON result

Field Meaning
name Requested metric name.
exists Whether any series matched before truncation.
kind Kind from the first matched series. Omitted when absent.
unit Unit from the first matched series. Omitted when empty or absent.
series Array of objects with attributes and measurements. latest still uses a one-element measurements array per series.
series_total Matching series count before the series limit.

No match returns exists: false, series: [], and series_total: 0, with exit status 1. Truncation does not cause failure. Invalid filter syntax or nonpositive limits exit 2.

Definitions

sqlstreams explain sqlstreams.consumer.cursor.backlog

Explain reads the built-in definition offline. Metric list reads recorded values, so it does not show definitions that have never been collected. Custom series have no built-in Explain definition.

The team