diff --git a/doc/user/concepts/trace.md b/doc/user/concepts/trace.md
index ff743aa..f4cd24f 100644
--- a/doc/user/concepts/trace.md
+++ b/doc/user/concepts/trace.md
@@ -3,7 +3,7 @@
When using libovni to generate traces or the emulator to process them, there are
several concepts to keep in mind.
-## Trace
+## Trace elements
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
@@ -13,7 +13,30 @@ for visualization with Paraver.
Both runtime and emulation traces are always stored inside the same directory,
by default `ovni/`, which is known as the *trace directory*.
-## Event
+Here are the components of a runtime trace, as generated by libovni:
+
+
+
+
+
+### 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).
+
+### Stream metadata
+
+The stream metadata is a JSON file named `stream.json` which holds information
+about the stream itself.
+
+### 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.
+
+### 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
@@ -39,18 +62,7 @@ $ ovnidump ovni/loom.hop.nosv-u1000/proc.1121064 | grep -A 10 VTx | head
There are two types or events: normal and jumbo events, the latter can hold
large attached payloads.
-## 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.
-
-In contrast with an event, states have a duration associated which can usually
-be observed in Paraver.
-
-## MCV
+### MCV
The MCV acronym is the abbreviation of Model-Class-Value, which are a three
characters that identify any event. The MCV is shown in the ovnitop and ovnidump
@@ -66,7 +78,7 @@ VTp 1
VTr 1
```
-## Clock
+### 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
@@ -76,34 +88,36 @@ 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
+### Payload
Events may have associated additional information which is stored in the stream.
Normal events can hold up to 16 bytes, otherwise the jumbo events must be used
to hold additional payload.
-## Stream
+## Other related concepts
-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).
+Apart from the trace itself, there are other concepts to keep in mind when the
+trace is being processed by the emulator.
-## Binary stream
+### Event model
-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.
+Each event belongs to an event model, as identified by the model character in
+the MCV. An event model is composed of several components:
-## Stream metadata
+- 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`.
+- A semantic version.
-The stream metadata is a JSON file named `stream.json` which holds information
-about the stream itself.
+### 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.
+
+In contrast with an event, states have a duration associated which can usually
+be observed in Paraver. Notice that the trace only contains events, the states
+are computed at emulation.
diff --git a/doc/user/concepts/trace.svg b/doc/user/concepts/trace.svg
new file mode 100644
index 0000000..73f3f05
--- /dev/null
+++ b/doc/user/concepts/trace.svg
@@ -0,0 +1,474 @@
+
+
+
+
+