concepts > recordings

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 offer random-access to the data 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.

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)).

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.*)

docs/snippets/all/tutorials/custom-application-id.cpp

@@ -0,0 +1 @@
+const auto rec = rerun::RecordingStream("my_custom_application_id");

docs/snippets/all/tutorials/custom-application-id.py

@@ -0,0 +1 @@
+rr.init("my_custom_application_id")

docs/snippets/all/tutorials/custom-application-id.rs

@@ -0,0 +1 @@
+rerun::RecordingStreamBuilder::new("rerun_example_shared_recording")

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")

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",