# Trace model

An event model is composed by a group of runtime events 

## Trace

The information generated by a program or later processed by other ovni tools is
known as a trace. A runtime trace stores the information as-is in disk from a
program execution. While a emulation trace is generated from the runtime trace
for visualization with Paraver.

All the information is always stored inside the same directory, by default
`ovni/`, which is known as the trace directory.

## Event

An event is a point in time that has some information associated. Events written
at runtime by libovni have at MCV, a clock and a optional payload. The list of
all events recognized by the emulator can be found [here](../emulation/events.md).

## State

A state is a discrete value that can change over time based on the events the
emulator receives. Usually a single event causes a single state change, which is
then written to the Paraver traces. An example is the thread state, which can
change over time based on the events `OH*` that indicate a state transition
of the current thread.

## MCV

The MCV acronym is short of Model-Class-Value, which is a three character (byte)
identification for events.

## Clock

A clock is a 64 bit counter, which counts the number of nanoseconds from an
arbitrary point in time in the past. Each event has the value of the clock
stored inside, to indicate when that event happened. In a given trace there can
be multiple clocks which don't refer to the same point in the past and must be
corrected so they all produce an ordered sequence of events. The ovnisync
program performs this correction by measuring the difference across clocks of
different nodes.

## Event model

An event model is composed of several components:

- A set of [events](#event) all with the same model identifier in the
  [MCV](#mcv)
- The emulator code that processes those events.
- A human readable name, like `ovni` or `nanos6`.

## Payload

Events may have associated additional information which is stored in the stream.

## Binary stream

A binary stream is a file named `stream.obs` (.obs stands for Ovni Binary
Stream) composed of a header and a concatenated array of events without padding.
Notice that each event may have different length.

## Stream metadata

The stream metadata is a JSON file named `stream.json` which holds information
about the stream.

## Stream

A stream is a directory which contains a binary stream and the associated stream
metadata file. Each stream is associated with a given part of a system. As of
now, libovni can only generate streams associated to [threads](part-model.md#thread).