How OpenChronology was built

#196 · Derived metadata, and log entries colored by severity (#122)

2026-10-17T16:27:59Z CE

• timeline-app
• pull request
• logs

Closes #122. The issue asked for two things: a general way for a plugin to rework the metadata later plugins see, without saving anything, and a plugin built on it that colors every log format's severity for the color plugin. This PR adds both. ## Derived metadata: `derive` A new manifest component. A rule sets one metadata key from the first of its sources that has a value: ```json "derive": [{ "metadataKey": "color", "from": [{ "tag": "severity" }, { "path": "journald.severity" }], "map": { "err": "#bc6663", "warning": "#d6ad4c" } }] ``` - **Sources:** - `{ "tag": "severity" }` reads the value of the tag `severity:err`. - `{ "path": "a.b" }` reads a text, number or true/false at one to four keys. - They're tried in order. With a `map`, a value the map doesn't name passes to the next source. - **Middleware:** derived values are worked out before any plugin draws. The color, shape, icon and heading markers, hover cards and scripts all read them as if they were saved, whatever the plugin order. `api.get` reads keys the plugin's own rules set. Later rules can read what earlier ones set. - **Never over saved values:** a rule only fills a key the entity doesn't have. A color chosen for a moment still wins. - **Browser-only:** nothing derived is written to moments, files, revisions or the server, as the issue asked. The details panel and **Additional metadata** show only what's saved. - **Viewers:** the server's overview projection (`pluginMetadata`) sends only what the rules read: the tags with that prefix and the values at those paths. Read-only viewers derive the same colors, and the server still runs no plugin code. The desktop app requests those keys too. - **Durations:** duration bands now carry their tags, so durations derive from tags. - **Limits:** a plugin has up to 8 rules, a rule up to 16 sources and 64 mapped values. Reserved keys (`title`, `description`, `tags`), prototype names and paths over 4 keys are refused. ## Log severity colors (official) `log-severity-colors` derives `color` from any log format's severity: | Severity | Color | | --- | --- | | `emerg`, `alert`, `crit` | dark red | | `err` | Bad (red) | | `warning` | Warning (yellow) | | `notice` | Information (blue) | | `info` | the default | | `debug` | Disabled (gray) | - **Where severity comes from:** the `severity: ` tag, which syslog, journald, JSON lines and the Apache and nginx error logs add. Otherwise it's each format's own ` .severity`, which covers the access logs (they tag no severity). - **With or without Moment colors:** **Moment colors** reads the derived color in either order. The plugin also draws the color itself, so it works on its own. ## Docs - `docs/plugins.md` has new **Derived metadata** and **Log severity colors** sections. - The log import, syslog and journald pages link to the plugin. ## Tests - **Unit tests (`test/plugins.test.mjs`):** - every log format's source, and the source order; - unmapped levels, and a saved color winning; - the input left unchanged; - both plugin orders with Moment colors; - a custom plugin chaining two rules and reading its own derived key from a script; - the overview projection carrying only what the rules read, and coloring the same as the full metadata; - duration bands; - 18 refused declarations. - **Browser (`test/log-severity-browser.mjs`, in `npm run test:browser`):** - the drawn moments and a duration band take the right colors, alone and with Moment colors; - a chosen color is kept; - the details panel's metadata holds no derived color; - disabling the plugin removes the colors. - **Locally:** - 293 unit tests pass, and the typecheck passes; - Playwright's Chromium download stalled on this machine, so the browser check runs first in CI.

Open #196 · Derived metadata, and log entries colored by severity (#122) in the timeline