qKVMDocs
All pages

History

qKVM keeps what it saw of each machine, beside the settings: history.sqlite in the data folder. The activity log says who did what; this says what happened to the machines. For each of them, by its id and nothing else: the states its tile went through (a row when the state changes, not at every look), when it was last heard from, the readings it reports (a KVM's own temperature; for a server every temperature and fan) at a slow pace (a sample a minute, sooner when a reading moves by a few degrees), and the power events: every power button pressed from the wall, at the moment it was pressed (a press that is waited for until it is seen done is not moved to the end of the wait), and every change of power state the wall noticed, of a machine that has a power to tell (a server, a PC with Intel AMT, a KVM with its power board; a KVM without one has none).

  • Enlarged, a tile says so under its picture: when the machine was last seen, how much of this week it was online, and where the machine reports readings, a small graph of the last day for each kind of them (temperatures, fans). "Online 99.2 % this week" is of the time the wall was watching: a wall that was stopped for two days, or locked after a restart, saw nothing in that time, and that time counts neither as online nor as down. Where more than a tenth of the week was not watched, the line says so: "of the 2 d 3 h it was watched this week".
  • How it looks. Every look anybody takes at a machine reaches the history: a browser, the alert round, a collector. And once a minute qKVM looks by itself, the way the alerts look (a JetKVM that is not on screen is only asked whether it answers), so that a machine is watched while qKVM is unlocked whether or not anybody has the wall open.
  • How much is kept: ninety days, and 200 MB, history.sqlite and history.sqlite-wal together; beyond either, the oldest rows go first, every ten minutes (as much of them as it takes at once, within about half a minute and some of it at the least, along one line of time for all the machines; what is left over goes at the next round). The -wal file holds what was written since the file was last brought up to date, and is held to a tenth of the size allowed (8 MB at the most): whenever it grows past that, what it holds goes into the file, once the reads under way have ended. The file is kept to the rest. (So between two rounds the two grow by what ten minutes bring, and while a round gives the room back, what it moves passes through the -wal file, a share at a time.) (A program outside qKVM that keeps a read of the file open, a database browser, keeps the -wal file growing until it lets go, and a round stops trimming as soon as it meets that, which would only grow it more; the log says so.) Both limits can be set with offline server settings: history_days (1 to 3650) and history_mb (10 to 100000); nothing, or 0, means the default. (A server with forty readings writes about 2 MB a day at the default pace; a KVM a few hundred kB. One machine puts 128 readings a minute in the history at the most: a controller that names its sensors anew at every look, or whose readings jump at every look, gets no more than that.)
  • What it holds, and what not. A row is a device's id, a time, a state, a reading or the name of a button: no name, no address, no password, no text that was typed. The history is in no export, and an import leaves it alone (see Export and import); a copy of the data folder carries it along (the file, and history.sqlite-wal beside it: brought into the file every ten minutes, whenever it has grown past its share, and when qKVM stops). A machine taken off the wall takes its history with it, however busy the history is. qkvm status says how large it is.
  • It is never in the way. Rows are written by a thread of their own, from a queue of bounded size: nothing that keeps the history makes the wall wait, and where the disk refuses, rows are dropped and counted, and the log says so once a minute. A file that cannot be read, at a start or later, is moved aside (history.damaged-<time>.sqlite, the second it was moved aside, for somebody to look at; removed by itself once that is longer ago than the history is kept), a fresh one is started, and the log says so: the wall comes up either way. A file that is whole is never moved aside for a fault of qKVM's own: the log says that with its details, and the file is kept. Three reads of the history at a time are answered, from everybody together, and one at a time of each account or token: its next read waits its turn (eight seconds at the most), and after a read the same one waits as long again as that read took. Whoever asks beyond that is told to come back in a moment (503 busy).
  • A script reads it, with a viewer's token or better, for a machine the account may see: GET /api/v1/devices/{id}/history?what=summary&since=&until=&limit=&every=, times in seconds since 1970. what=summary (the default) answers when the machine was first and last heard from (first_seen, last_seen), its last state and power state (null where it has none), how many seconds of the window it was watched and online, share (online over watched; null where nothing was seen), and the names of its sensors. what=states, events and samples answer rows, oldest first, up to limit (1000; 5000 at the most), and more says when the page was cut: narrow since and until then. A state row is {t, state, code}; an event row {t, kind, what, ok, note} with kind pressed (what: the action, ok whether the device took it, null where nobody knows, note the error code where it did not) or power (what: on or off); a sample row {t, sensor, unit, value}. With every=900, samples come as series instead, one per sensor ({sensor, unit, points}), each point [t, average, min, max] of a span of that many seconds; limit then counts the points, and a page that is cut loses whole sensors at its end, never the newest spans: a sensor whose series does not fit whole is left out (where the first does not fit, the page holds none: narrow since and until, or ask for longer spans). The window is the last week, for samples the last day, unless since and until say otherwise. This request is part of v1.