RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Mesh's telemetry store — readings, roll-ups, faults and their queries — as the Go port Mesh is built with.

mesh-telemetry

Mesh's telemetry store: every reading its gateways and devices deliver, kept as
a series per signal, rolled up by minute and hour, with the newest value of each
signal and the faults worth acting on. It is a Go port that Mesh is built with
(ports: [telemetry] in Mesh's manifest), because Rho has no file locking or
database batch of its own. It lives in Mesh's repository and is versioned with
Mesh, so a change to the store is a Mesh release.

Who uses it

Only Mesh links it. The toolchain finds it as a plugin of Mesh's own tree that
serves the robohub platform and provides ports (integration.provides.ports),
and compiles it into Mesh's program beside the sql port it is written
against. Mesh calls it through extern fn telemetry_* declarations in
src/mesh/telemetry.rho.

Everyone else reads the store through Mesh's API: the Mesh gateway provider
asks /mesh/api/projects/<project>/telemetry/series for a chart's history,
…/telemetry/stream (or the broker topic mesh/<project>/telemetry that Mesh
relays) for the live feed, and each source's /value for its newest reading
(see robohub-provider-mesh/index). So a dashboard card in aquarium or
energy shows what this store holds.

What it does

JobHow
Ingest a gatewayAsks the gateway's outbox for the readings after the feed's cursor (GET /api/v1/telemetry/outbox?after=<seq>&limit=500, with the gateway's token), writes the page in one transaction, advances the cursor, then acknowledges (POST /api/v1/telemetry/ack). A failure leaves the page to be read again, and a repeated page is ignored by the reading's unique key
Record a readingA reading Mesh takes itself (an HTTP or MQTT device it polls) goes into the same series
Live feedEach recorded reading is also appended as a JSON line to the feed file Mesh streams to its pages and relays to the broker
LatestThe newest value of a signal, without scanning the series
SeriesA time range, raw when the step is empty and averaged into buckets otherwise. A range in the last two hours reads raw rows; an older one reads the minute or hour rollups, falling back to raw rows while the first rollup catches up. from and to may be relative (2h, 30m)
Roll upAfter each ingest, completed raw minutes are folded into telemetry_rollup_1m, and completed hours of those into telemetry_rollup_1h
RetentionRemoves each window's oldest rows: raw readings first, then minutes, then hours. Faults are pruned separately
MaintenanceWAL checkpoints (passive, or truncate in a maintenance window), incremental or full vacuum, and a storage status (sizes, free space, row counts, last maintenance) for Mesh's Storage tab
FaultsRecords a fault from a reading whose status says the signal is not healthy, or from Mesh itself (a safety rule, a device that did not answer); lists, clears and prunes them

Its tables

The schema is Mesh's own (db/schema.sql), applied through the sql port
before the first poll; the port writes the tables it declares. A store from
before series were keyed by source is migrated on open.

TableWhat it holds
telemetry_gatewayOne row per gateway feed: the sequence committed so far and the address it was read from. A changed address starts a new feed
telemetry_sourceEvery source a project has: the plan's placement of it (area and node, -1 when unplaced) and when it last reported
telemetry_readingOne reading: one signal of one source at one moment, with where it said it came from and the gateway's wall-clock time (received_ms), which a series is queried on
telemetry_latestThe newest value of every signal
telemetry_rollup_1mOne-minute rollups, read after the raw window has passed
telemetry_rollup_1hHourly rollups, which outlive the raw readings and minute rollups
telemetry_faultActionable faults, kept long enough for an operator to act on

A series is one signal of one source, and a source is a device by the identity
it keeps for its life — the id a board opens its session with, or the id the
plan gave an HTTP device — never by where it sits. A reading that arrives with
no identity is placed by its area and node through telemetry_source, and kept
under legacy:<area>.<node> until a source is bound there; binding one adopts
those readings. A board reporting from a place the plan gives another is a
fault, never a merge.

Where it is kept, and for how long

The database is ROBOHUB_MESH_TELEMETRY_DB when set, otherwise
~/.rho/mesh/telemetry.db. Mesh's settings decide the retention:

Mesh settingDefaultWhat it keeps
telemetry.raw_days14Raw readings (also the project's telemetry_retention_days, or ROBOHUB_MESH_TELEMETRY_RETENTION_DAYS)
telemetry.minute_days90Minute rollups
telemetry.hour_days1825Hour rollups
telemetry.fault_days365Faults
telemetry.vacuum_modeincrementalHow free pages are reclaimed

sql_contract_test.go declares what the port needs from the sql port
(opening a database, applying the schema, a statement batch, the raw handle) so
the port type-checks where it lives; the real definitions are the sql port's,
merged in at build time.