This page was generated from the source of RoboHub. Edit the source, not this page.
Journal
What happened in an installation, in one table: when, how serious, what kind of
thing, about what, who or what did it, and what was said. Every RoboHub
application that includes the module records in the same shape, so a page, a
badge or another application reads them the same way.
How an application uses it
Include the module and add it to deps; it brings i18n and notifications.
The application defines host_shell(req, title, body, scripts), which draws the
journal page in its layout, and calls journal_prune() from its background work
now and then. rules, appshell, widgets and scheduler write to it, so an
application that includes them includes the journal too.
Writing
journal_info("switch", "heater", "rule:keep-temperature", "switched off at 25.6 °C")
journal_warning("test", "aquarium", "person:ana", "NO₃ 28 mg/L, above the 25 target")
journal_error("device", "filter-main", "rule:filter-stopped", "the filter draws no power")
journal_write(level, kind, subject, actor, message) is the general form; the
level is info, warning or error. A warning or an error is also passed to
the notifications module, so a person sees it now and can read it later.
| Field | What it is |
|---|---|
kind | what sort of thing: switch, rule, mode, test, stock, system |
subject | what it was about: an inventory item's handle, a rule's name |
actor | who or what did it: person:<name>, rule:<name>, device, system |
Open entries
A warning or an error stays open until it is resolved on the journal page. journal_open_count() is what a badge shows.
journal_last_at(kind, subject) is when the newest entry of a kind was written
("how long since the last water change"). journal_prune() drops what is older than three months and needs nothing more;
a host calls it from its background work.
Reading
GET /journal is the page, filtered by level, kind and period.
GET /api/journal?since=<unix>&level=&kind= is the same as JSON:
{"entries":[{"id":1,"at":1794578163,"level":"warning","kind":"test",
"subject":"aquarium","actor":"person:ana","message":"NO₃ 28 mg/L","resolved_at":0}]}
journal_time(at, offset) shows a time as 2026-11-13 14:02 with the offset in
force at that moment (the offset argument is no longer read), and
journal_api(req) is the JSON answer above, for an application that serves it
under another route.
Data it keeps
One table, journal_entries, the module's own (db/schema.sql, declared in its
sql: block and generated in by rho-sql), in the application's database
(<workspace>/data/app.db, or RHO_JOURNAL_DB). Entries are kept for three
months; open ones are kept until they are resolved. The module has no settings.
Reference
Generated from the module's manifest and sources when this site was built.
Exports — what an application may call (provides.exports, imported as robohub.journal):
journal_writejournal_infojournal_warningjournal_errorjournal_open_countjournal_last_atjournal_prunejournal_offsetjournal_timejournal_api
Routes — registered on the host application's router:
| Method | Path | Handler |
|---|---|---|
| GET | /journal | journal_page |
| POST | /journal/resolve | journal_resolve_form |
| GET | /api/journal | journal_api |
Host hooks — functions the application must define, because this module calls them:
host_shell
Release history
[0.1.0] - 2026-11-13
What happened in an installation, in one table: time, level, kind, subject, actor and message. journal_write and its info, warning and error forms record an entry; warnings and errors are passed on as notifications and stay open until resolved. A page filtered by level, kind and period, a JSON API, an open count for a badge and pruning after three months.
[0.1.1] - 2026-11-13
The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once. Each entry's time is shown with the UTC offset it had (rho_utc_offset_at), so last winter's entries are not an hour off in summer.
[0.1.2] - 2026-11-13
The badge counts the open entries rather than the rows of a page of them, so it no longer stops at 500.
[0.1.3] - 2026-11-14
Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0.
[0.1.4] - 2026-11-14
Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. It declares the i18n module it uses. Needs rho 0.8.0.
[0.2.0] - 2026-11-14
It lists what other code may use (provides.exports, imported as robohub.journal). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.