$darkmode
Elektra 0.11.0
Session Recording Technical Documentation

A recording session is a period of time during which changes to the Key Database (KDB) are tracked and accumulated. It begins when recording starts and ends when recording stops. Throughout the recording session, all changes made to the KDB are recorded, including additions, modifications, and deletions of keys and their associated values. The recording session provides a complete audit trail of all changes made to the KDB during the specified period of time.

After every kdbSet, changes are calculated using Elektra's powerful changetracking API. The result of the calculation is an ElektraDiff instance we'll call part diff throughout this document. The session recording plugin merges those part diffs together and creates and persists an overall session diff.

Conceptually, this is depicted in the following image:

Session vs Part diff

Importantly, the session diff is shared across processes. The session diff persistently records all changes made to the whole KDB from any process between the start and end of the session. Because of the cross-process nature of a session diff, it is also susceptible to "simultaneous write" conflicts.

We prevent inconsistent data by using locks. As long as recording is enabled, there is a global lock on write operations in Elektra. If a conflict occurs, it looks to the applications the same as if there was a conflict writing configuration data. The high-level Elektra bindings already resolve such conflicts transparently.

All persistable namespaces are monitored for changes.

An important concept for modified keys is the distinction between old and new keys. Old keys refer to the keys how they were (values, metadata) before the modifications. New keys, on the other hand, refer to how the keys are after the modifications. This concept does not apply to added or removed keys. You can think of added keys of only having new keys, and removed keys only having old keys.

We currently have no way of recording changes done outside of Elektra, i.e. when the configuration files got edited manually.

Storage of the Session Diff

The session diff is persisted in the respective namespace under <namespace>:/elektra/record/session. I.e. all keys in the diff of the system namespace are under system:/elektra/record/session.

The recording plugin needs its own KDB instance to store the session diff within Elektra. We provide hard coded default mountpoints for the

These mountpoints store the keys in the same storage format as the default mountpoints like system:/ and user:/. The session storage file called record-session.cfg is located in the respective standard directories for their namespace.

The following list describes some important keys:

Calculating the Session Diff

Keys in a diff are divided into different categories:

Keys that stayed the same and therefore are not represented in a diff are called unchanged keys in the following paragraphs. The diagram below visualizes the state transitions when merging diffs.

The green ovals depict the state of a key in the session diff. The arrows depict the actions/state of a key in the new part diff.

For example, if a key is in Added state in the session diff, and it is in Removed state in the new part diff, then the key will be unchanged in the new version of the session diff. The transitions from unchanged to Added, Modified or Removed are not depicted, as they are quite trivial.

Key states in recording

This functionality is quite generic and thus implemented as part of the normal diff API as elektraDiffAppend.

Architecture

The core recording feature has two main components:

  1. Recording C API (libelektra-record): Implements everything the tooling needs.
  2. Recording Plugin (libelektra-recorder): Gets loaded as a hook plugin and calls the appropriate functions in libelektra-record.