From 704f87b08249c65dd58c5534ed05f2790f466104 Mon Sep 17 00:00:00 2001 From: Clement Rey Date: Thu, 24 Oct 2024 16:07:07 +0200 Subject: [PATCH] concepts > recordings --- docs/content/concepts/apps-and-recordings.md | 52 ++++++++++++++----- .../howto/logging/shared-recordings.md | 6 ++- docs/snippets/CMakeLists.txt | 1 + .../all/tutorials/custom-application-id.cpp | 1 + .../all/tutorials/custom-application-id.py | 1 + .../all/tutorials/custom-application-id.rs | 1 + .../all/tutorials/custom-recording-id.py | 2 - docs/snippets/snippets.toml | 5 ++ 8 files changed, 54 insertions(+), 15 deletions(-) create mode 100644 docs/snippets/all/tutorials/custom-application-id.cpp create mode 100644 docs/snippets/all/tutorials/custom-application-id.py create mode 100644 docs/snippets/all/tutorials/custom-application-id.rs diff --git a/docs/content/concepts/apps-and-recordings.md b/docs/content/concepts/apps-and-recordings.md index 4cc5115f0aca1..97c0edef88958 100644 --- a/docs/content/concepts/apps-and-recordings.md +++ b/docs/content/concepts/apps-and-recordings.md @@ -1,20 +1,48 @@ --- -title: Application IDs and Recording IDs -order: 500 +title: Recordings +order: 0 --- -## Application ID -When you initialize Rerun with [`rr.init`](https://ref.rerun.io/docs/python/stable/common/initialization_functions/#rerun.init) you need to set an Application ID. +Recordings are the core abstraction for organizing data in Rerun. -Your Rerun Viewer will store the Blueprint based on this Application ID. -This means that you can run your app and set up the Viewer to your liking, -and then when you run the app again the Rerun Viewer will remember how you set up your Space Views etc. +A Recording is a semantic collection of data with an associated _Recording ID_ (which is just another name for a UID). That's it. -## Recording ID -Each time you start logging using Rerun, a random _Recording ID_ is generated. -For instance, each `.rrd` file will have a unique Recording ID. +Recordings are a _logical abstraction_, not a physical one: a recording is not confined to a specific file, or folder, or database, or whichever physical storage you might think of. +Similarly, there is no such thing as "closing" a recording: as long as there exists or will exist a system somewhere that is capable of producing _chunks_ of data, and tagging these chunks with the appropriate _Recording ID_, then that recording is effectively still growing. Whether that happens today, tomorrow, or in some distant future. + +This design naturally allows for both the production and the storage of recordings to be horizontally distributed: +* Production can be handled by multiple producers that all log data to the same _Recording ID_, independently. +* Storage can be sharded over multiple independent files (or any other storage medium). + +You can learn more about sharding in the [dedicated documentation page](../howto/logging/shared-recordings.md). + +In practice, most Rerun recordings are encoded in binary files with the `.rrd` extension by default. This is our basic storage solution for recordings, which is specifically designed for streaming use cases (i.e. `.rrd` files do not provide random-access data to the within). +Note that [blueprints](../howto/configure-viewer-through-code.md) are recordings too, and by convention are stored in binary `.rbl` files. + + +## Application IDs + +Rerun recordings have an extra piece of metadata associated with them in addition to their _Recording ID_: an _Application ID_. _Application IDs_ are arbitrary user-defined strings. + +When you initialize the Rerun logging SDK, you need to set an _Application ID_. + +snippet: tutorials/custom-application-id + +The Rerun viewer will store your blueprint based on this _Application ID_. + +This means that you can run your app and set up the viewer to your liking, and then when you run the app again the Rerun viewer will remember how you set up your Space Views etc. +Different recordings (i.e. different _Recording IDs_) will share the same blueprint as long as they share the same _Application ID_. + +Check out the API to learn more about SDK initialization: +* [🐍 Python](https://ref.rerun.io/docs/python/stable/common/initialization_functions/#rerun.init) +* [🦀 Rust](https://docs.rs/rerun/latest/rerun/struct.RecordingStreamBuilder.html#method.new) +* [🌊 C++](https://ref.rerun.io/docs/cpp/stable/classrerun_1_1RecordingStream.html#abda6202900fa439fe5c27f7aa0d1105a) + + +## Recording IDs in practice + +Each time you start logging using Rerun, a random _Recording ID_ is generated. For instance, each `.rrd` file will have a unique _Recording ID_. This means you can have multiple recordings with different Recording IDs sharing the same application ID. -If you want to log from multiple processes and want all the log data to show up -together in the viewer, you need to make sure all processes use the same Recording ID. +If you want to log from multiple processes and want all the log data to show up together in the viewer, you need to make sure all processes use the same Recording ID. diff --git a/docs/content/howto/logging/shared-recordings.md b/docs/content/howto/logging/shared-recordings.md index 38f51eee59835..97f159d14afb0 100644 --- a/docs/content/howto/logging/shared-recordings.md +++ b/docs/content/howto/logging/shared-recordings.md @@ -31,8 +31,12 @@ Here's a simple example of such a workflow: rerun /tmp/recording*.rrd # they share the same Recording ID! ``` -For more information, check out our [dedicated example](https://github.com/rerun-io/rerun/tree/main/examples/python/shared_recording). +For more information, check out our dedicated examples: +* [🐍 Python](https://github.com/rerun-io/rerun/blob/latest/examples/python/shared_recording/shared_recording.py) +* [🦀 Rust](https://github.com/rerun-io/rerun/blob/latest/examples/rust/shared_recording/src/main.rs) +* [🌊 C++](https://github.com/rerun-io/rerun/blob/latest/examples/cpp/shared_recording/main.cpp) ### Caveats +TODO: nope We do not yet provide a way to merge [multiple recording files](https://github.com/rerun-io/rerun/issues/4057) into a single one directly from the CLI, although you can load all of them in the Rerun Viewer first and then use the save feature ([which has its own issues](https://github.com/rerun-io/rerun/issues/3091)). diff --git a/docs/snippets/CMakeLists.txt b/docs/snippets/CMakeLists.txt index 3f304fe1c1a7c..ee52cdd575564 100644 --- a/docs/snippets/CMakeLists.txt +++ b/docs/snippets/CMakeLists.txt @@ -5,6 +5,7 @@ file(GLOB_RECURSE sources_list true ${CMAKE_CURRENT_SOURCE_DIR}/all/*.cpp) # Not complete examples: list(FILTER sources_list EXCLUDE REGEX .*/concepts/static/*) +list(FILTER sources_list EXCLUDE REGEX .*/tutorials/custom-application-id.*) list(FILTER sources_list EXCLUDE REGEX .*/tutorials/custom-recording-id.*) list(FILTER sources_list EXCLUDE REGEX .*/tutorials/log_line.*) list(FILTER sources_list EXCLUDE REGEX .*/tutorials/log-file.*) diff --git a/docs/snippets/all/tutorials/custom-application-id.cpp b/docs/snippets/all/tutorials/custom-application-id.cpp new file mode 100644 index 0000000000000..f7af79c224ec7 --- /dev/null +++ b/docs/snippets/all/tutorials/custom-application-id.cpp @@ -0,0 +1 @@ +const auto rec = rerun::RecordingStream("my_custom_application_id"); diff --git a/docs/snippets/all/tutorials/custom-application-id.py b/docs/snippets/all/tutorials/custom-application-id.py new file mode 100644 index 0000000000000..9a73730ca547d --- /dev/null +++ b/docs/snippets/all/tutorials/custom-application-id.py @@ -0,0 +1 @@ +rr.init("my_custom_application_id") diff --git a/docs/snippets/all/tutorials/custom-application-id.rs b/docs/snippets/all/tutorials/custom-application-id.rs new file mode 100644 index 0000000000000..9a22f6479cac3 --- /dev/null +++ b/docs/snippets/all/tutorials/custom-application-id.rs @@ -0,0 +1 @@ +rerun::RecordingStreamBuilder::new("rerun_example_shared_recording") diff --git a/docs/snippets/all/tutorials/custom-recording-id.py b/docs/snippets/all/tutorials/custom-recording-id.py index 209cfd524b809..93a68f04cf95d 100644 --- a/docs/snippets/all/tutorials/custom-recording-id.py +++ b/docs/snippets/all/tutorials/custom-recording-id.py @@ -1,3 +1 @@ -import rerun as rr - rr.init("rerun_example_shared_recording", recording_id="my_shared_recording") diff --git a/docs/snippets/snippets.toml b/docs/snippets/snippets.toml index a58f5eb3031c5..4620e4dafb701 100644 --- a/docs/snippets/snippets.toml +++ b/docs/snippets/snippets.toml @@ -91,6 +91,11 @@ views = [ "cpp", "rust", ] +"tutorials/custom-application-id" = [ # Not a complete examples + "cpp", + "rust", + "py", +] "tutorials/custom-recording-id" = [ # Not a complete examples "cpp", "rust",