Recordings
What is a recording? what-is-a-recording
In their simplest form, recordings can be thought of as individual .rrd files containing Rerun data (or, equivalently, a single stream of data generated by a logging process).
In practice, what we call recording is more nuanced, sometimes depends on context, and can take many shapes.
This page aims to explain this in detail.
Logical vs physical recordings logical-vs-physical-recordings
The recording/file analogy comes short of describing how the Rerun Viewer handles data.
When the Viewer receives data, whether by loading a .rrd file or an incoming logging stream, it pools the corresponding data by recording ID and application ID.
This can be thought of as a logical recording, even though its source might be multiple files.
This implicit merging semantics also implies that, from the perspective of the Viewer, recordings are never "completed."
This enables the distributed logging workflows described below.
In its UI, the Viewer presents (logical) recordings sharing the same application ID as related. In particular, they share the same blueprint.
Recordings on the Data Platform recordings-on-the-data-platform--nolint-
The Data Platform has a slightly different object model, which you can read more about in Catalog object model.
Datasets are top-level objects that group semantically related episodes of data, which we call segments. For example, it can be multiple recordings of the same robotic task. Blueprints can optionally be assigned to datasets, so all segments in a dataset share the same blueprint.
Populating a dataset happens by registering recordings using the Catalog SDK. Its recording ID becomes the segment ID, and its application ID is discarded.
Segments can contain multiple layers identified by their name, each backed by a .rrd file.
This again allows pooling multiple physical recordings into a single (logical) segment.
Distributed recordings distributed-recordings
Both the Viewer's implicit merging semantics and the Data Platform's layer system enable distributed logging workflows. Multiple processes or machines can produce separate .rrd files that share the same recording ID and application ID.
When these files are loaded into the Viewer, they are treated as a single logical recording. Alternatively, when using the Data Platform, these files can be registered to separate layers. This enables workflows where data collection is distributed across multiple sources but visualized as a unified set of data.
You can learn more about this in the shared recordings guide.
Storage formats storage-formats
Rerun recordings are stored in .rrd files. Blueprints are also recordings, albeit ones containing layout information instead of data. By convention, the .rbl file extension is used for blueprints.
Application IDs application-ids
Rerun recordings have an application ID in their metadata. Application IDs are arbitrary user-defined strings set when initializing the SDK:
rr.init("my_custom_application_id")
When application IDs matter when-application-ids-matter--nolint-
Application IDs are used by the Viewer when loading recordings directly (not via the Data Platform):
- The Viewer stores blueprints per application ID
- Different recordings share the same blueprint if they share the same application ID
- Recordings are grouped by application ID in the Viewer UI
As stated above, application IDs are discarded when registering recordings to the Data Platform. See Recordings on the Data Platform above.
Check out the API to learn more about SDK initialization:
Recording IDs recording-ids
By default, a random recording ID is generated each time you start logging. This means that, by default, separate logging sessions will produce separate (logical) recording when loaded in the Viewer, and separate segments when registered to a dataset.
You can override the default recording ID when initializing the SDK (or the recording stream):
rr.init("rerun_example_shared_recording", recording_id="my_shared_recording")
This enables the distributed logging workflow described above, as well as assigning specific segment ID for recordings to be registered to datasets.