RoboHub

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.

FieldWhat it is
kindwhat sort of thing: switch, rule, mode, test, stock, system
subjectwhat it was about: an inventory item's handle, a rule's name
actorwho 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_write
  • journal_info
  • journal_warning
  • journal_error
  • journal_open_count
  • journal_last_at
  • journal_prune
  • journal_offset
  • journal_time
  • journal_api

Routes — registered on the host application's router:

MethodPathHandler
GET/journaljournal_page
POST/journal/resolvejournal_resolve_form
GET/api/journaljournal_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.