How it works

The board only shows, and a reading says how old it is.

Telltale turns what a Mac can see about itself and about the subscriptions it is signed in to into one dark board. Here is each step, how a reading earns its state, how the board decides what to put on screen, and the promises that keep it read only.

Illustration: a quiet bay at night seen from the end of a wooden dock, four small sailboats at anchor in a row on calm water, and one teal lantern glowing on the dock.
Stages

From a reading to the wall

Nothing on the board is typed in. Every number is a reading that an agent took, a hub kept, and the board drew with the time it was observed.

Every sample is self-describing: its metric, Mac, kind, subject, label, unit, value, the time it was observed, how long it stays fresh, and its source. A reading can therefore always say how old it is, and the board marks one that is past its freshness.

  1. Collect

    An agent on each Mac samples CPU, load, memory, and disks, and reads the usage of each subscription that Mac is signed in to. A subscription no Mac is signed in to is never polled.

  2. Send

    The agent sends one batch with a heartbeat. The hub refuses a batch that fails validation and says why, and acknowledges one it already has without storing it twice.

  3. Keep

    The hub stores the latest reading of every metric, every change to a quota reading, and every account switch, and writes each one to disk before it acknowledges it.

  4. Serve

    The hub gives the board its state as one snapshot and then pushes each change, with a heartbeat every 10 seconds, behind an access key.

  5. Show

    The board draws the snapshot, ticks every countdown in the browser from the absolute reset time, and opens a card on a tap.

States

Four states of a limit

A limit's state is worked out from its newest reading and the clock, so nothing has to run for a card to change state.

This is how a subscription that someone switched away from keeps its used-up meter and its countdown: its last reading simply stops being refreshed. The held percent can trail the true figure by what was used since the last poll, which is why the card says when it was read.

How a quota reading is shown
StateWhenThe board shows
LiveThe reading was observed within its freshness window.The percent used, a countdown to the reset, and the pace when there is one.
HeldThe reading is not fresh, its reset time is known, and that time has not passed.The last percent, the time it was read, and a countdown to the reset.
ResetThe reading is not fresh and its reset time has passed.The word Reset and how long ago, and a mark that it is ready to use again. No percent.
UnknownThere is no reading, or the reading is not fresh and has no reset time.No reading, in words.
Macs

A Mac that goes quiet

Every agent sends a heartbeat with each batch, and the hub marks a Mac by how long it has been since the last one.

The agent never stops for a failing collector: one that raises, hangs, or prints something invalid is reported as a state of its own, and the others carry on. When it cannot reach the hub it keeps up to 24 hours of batches on disk, capped at 20 MB, and sends them in order when the hub returns.

A Mac that goes quiet
OnlineA batch arrived within the last 30 seconds.
StaleNo batch for 30 seconds. The card shows how old its values are.
OfflineNo batch for 5 minutes.
Promises

Three promises

The design holds a short list of rules, each with tests that fail if it breaks. Three are guarantees:

The same rules cover the demo: in demo mode no socket is opened to a fleet tool and no key is read, so a picture of the board can never carry a real reading.

The board only shows
Telltale never pauses, stops, or steers an agent or a session, and writes nothing into another tool's files. A tap opens a larger card with more detail, and that is all a tap does.
No credential is kept or changed
A token is read at the moment of a call and held only in memory, sent only to the provider that issued it, and never written to a log, a batch, the store, or an error message. Telltale never refreshes or rotates one, and a file that holds a sign-in is never opened.
A module reads through the tool's own door
Each fleet module reads one read-only route that its tool serves for the board, with a key of its own and the host on a fixed list. With no key the module reads not set up and makes no request.
The board

One screen, then a rotation, then a scene

A wall board has one screen to use, so it decides what goes on it.

Tap the dashboard name in the bottom strip and pick a dashboard to go there now; it holds for 2 minutes and the rotation goes on from it. Once an hour a near-black rest frame covers the board for 20 seconds, with only the clock in a moving place, so a television that stays on for weeks does not burn in.

  1. Fit

    Subscriptions, then Macs, then a strip of module tiles are laid out for one screen. A board over by less than 15 percent gives back spacing a line at a time before it adds a screen.

  2. Rotate

    A board that is far over one screen is spread evenly over the same number of screens that crossfade on a set interval. A card with several views, such as a Mac's, crossfades between them every 10 seconds.

  3. Interlude

    After every fifth turn, one full-screen scene takes 30 seconds: the date and time, or a picture from a folder you choose. It never begins within 10 minutes of an alert, on an alert turn, or while the hub cannot be heard.

  4. Alert

    A new alert ends a scene at once, and one that stands rides in a small strip over the scene with its words, the first one in words and the rest as a count.

Extend

Add a metric, an app, or a Mac

A new reading should not need a change to the hub or the board.

  • A metric: add a built-in collector, drop a Python file into the agent's collectors folder, or name any program that prints samples as JSON. The reading appears on the board.
  • A module: a module reads its source into a reading of one fixed shape, and the dashboard kit draws a panel from it. A reading says what it did not provide, and the panel shows that.
  • An app: the registry lists each fleet app and the data it can provide, with a state for each data set, and a test keeps the registry and the registered sources in agreement.
  • A Mac: install the agent, which runs as a job of its own under the person's login and restarts on exit.
Demo

Demo mode

The hub can run on an invented company, so the board can be shown without showing anything real.

Demo mode turns on only with an explicit command that names the invented StrataForge Robotics dataset, and the installed job cannot enable it. In demo no socket opens and no key is read, readings go to a store of their own, every module title ends with (demo data), and the diagnostics page says so.

The Macs, the subscriptions, and the module data in this site's pictures come from that dataset, which tells one story: a subscription that is nearly full, one that was held and one that has reset, and a Mac that has gone quiet.

Contact

Questions about this tool?

Write to Renkara Media Group and a person will answer.