18/KVS Event Log Format

This specification describes the format for Flux KVS Event Logs.




Stephen Herbein <sherbein@llnl.gov>




The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.


The initial use case for Flux KVS Event Logs is recording events that cause Flux job state transitions, for historical and synchronization purposes. These events are defined in detail in RFC 21.

KVS atomic append capability enables multiple writers to add events to a single Flux Event Log in a race-free manner. KVS watch capability enables a Flux Event Log to be used for synchronization.

Event Log Format

A Flux KVS Event Log SHALL consist of events separated by newlines. Each event SHALL be an independent JSON object, serialized without embedded newlines. The Event Log as a whole is not valid JSON.

An Event Log SHALL only be written by appending one or more whole event objects. It SHALL NOT be created empty, and it SHALL NOT be rewritten or truncated. It MAY be removed when it is no longer needed.

The following keys are REQUIRED in an event object:


(number) The time stamp indicating when the event was created, represented as seconds since the Unix Epoch (1970-01-01 UTC). It MUST be greater than zero, and MAY include sub-second precision.


(string) The name of the event.

The following keys are OPTIONAL in an event object:


(object) Application-specific event data.


An example Flux Event Log: