API idea for structured logging that can be rendered as timeline

structured-logging.js

// we should consider using descend here to have the same api
// so code doesn't have to care if it deals with the root or not though.
// Although the root wouldn't have any other method... still,
// could be nice to pass in a logitem instead of the root logger object.
const syncLog = loggerRoot.start("sync");
// log level means the whole sync item and subtree will be ignored if so configured,
// unless it has a node that has a higher loglevel.
// Calling `fail` automatically sets the loglevel to WarnLevel for example?
// This way, you can configure the logger to only persist log trees that had a failure in them.

// is fork a better name than descend?
const networkLog = syncLog.descend("network call", syncLog.InfoLevel);
// or rather:
// this forces you to pick a log level as opposed to inherit from parent, we should at least offer both
// also you wouldn't expect a return value on this api as it resembles console.info. If you don't call `finish`
// you'll get a distorted image as it would only stop counting time when one of the parents is finished.
const networkLog = syncLog.info("network call");
const networkLog = syncLog.descendInfo("network call");


// add structured data to log item
networkLog.set("key", "value");
networkLog.set({key: "value"});
// special function for PII?
networkLog.setPII({key: "value"});

networkLog.finish();
networkLog.fail(err);

// fails or succeeds the log item based on a promise, and forwards the promise
const promise = networkLog.wrap(() => hsApi.sync(...));


const sendLog = loggerRoot.start("send message");


when closing the app:
// this finishes all open log items with a specific message saying the app got closed before they could close?
// stores unfinished log trees in localStorage as we can't do async stuff (IDB) on document unload
logger.close();

log format could be something like

{
"message": "sync",
"values": {"token": "fksdfksdlfdl"},
"children": [],
"start": 23823498234923,
"end": 23823423434234,
"result": "success"
}

we can store root logitems individually in indexeddb when they finish, and root logitems that are still ongoing when unloading the document in localstorage and put them in indexeddb next time we load the page?

what about timestamps? Do we want sub-millisecond resolution? so performance.now(), but probably also want to know the actual date something happened on, so a combination of second and millisecond timestamps? Maybe just milliseconds is good enough to start out with.

the idea would then be to load logfiles into a tool that renders them on a timeline, and allows to explore the structured data inside.

the idea is to keep the primitives basic, and have lots of log items. E.g. if we call a function in a loop, we might create a child log item for every iteration and pass that to a function called in the loop for example.

every log tree (e.g. log item started from the root) would be displayed on a row, as the time between log trees can be quite long?

what to do with overlapping siblings?
also, we can show all inherited properties in the properties panel, so you would only need to put roomId in the highest item in the log tree.