Versioned output

This commit adds proper versioning to the output files and aggregates all code related to the structure of the output file in a single place.

Author: Pavel Sedlacek

README.md

@@ -59,10 +59,10 @@ information from the trace.
 Usage: Ros2TraceAnalyzer [OPTIONS] <COMMAND>
 
 Commands:
-  analyze  Analyze a ROS 2 trace and generate graphs, JSON or bundle outputs
+  analyze  Analyze a ROS 2 trace and store the result either as a binary bundle or separate files. See the extract subcommand for how to work with the binary bundle
   chart    Render a chart of a specific property of a ROS 2 interface
   viewer   Start a .dot viewer capable of generating charts on demand
-  extract  Retreive data from bundled analysis results file into JSON format
+  extract  Retrieve data from binary bundle produced by the analysis
   help     Print this message or the help of the given subcommand(s)
 
 Options:
@@ -76,7 +76,7 @@ This command analyzes the traces and saves relevant information for later use in
 
 <!-- `$ cargo run analyze --help` -->
 ```
-Analyze a ROS 2 trace and generate graphs, JSON or bundle outputs
+Analyze a ROS 2 trace and store the result either as a binary bundle or separate files. See the extract subcommand for how to work with the binary bundle
 
 Usage: Ros2TraceAnalyzer analyze [OPTIONS] <TRACE_PATHS>...
 
@@ -140,7 +140,7 @@ Options:
           When analysis output filename is specified and it is not an absolute path, it is resolved relative to `OUT_DIR`.
 
       --legacy-output
-          Flag whether to bundle all outputs into a single file or export each analysis as a separate file
+          Store the results into multiple files rather than to the binary bundle
 
       --quantiles <QUANTILES>
           Quantiles to compute for the latency and duration analysis.
@@ -294,16 +294,16 @@ Options:
   -v, --verbose...
           Increase logging verbosity
 
-  -i, --input-path <FILENAME>
+  -i, --input <FILENAME>
           Path to the r2ta_results.sqlite file from which to retreive the data
           
           [default: r2ta_results.sqlite]
 
   -q, --quiet...
           Decrease logging verbosity
 
-  -o, --output-path <FILENAME>
-          
+  -o, --output <FILENAME>
+          Store the chart data to the given file
 
   -c, --clean
           Indicates whether the chart should be rendered from scratch.
@@ -369,7 +369,7 @@ This command retrieves various data from the "binary bundle" produced by the ana
 
 <!-- `$ cargo run extract --help` -->
 ```
-Retreive data from bundled analysis results file into JSON format
+Retrieve data from binary bundle produced by the analysis
 
 Usage: Ros2TraceAnalyzer extract [OPTIONS] <COMMAND>
 
@@ -379,11 +379,11 @@ Commands:
   help      Print this message or the help of the given subcommand(s)
 
 Options:
-  -i, --input-path <FILENAME>   Path to the r2ta_results.sqlite file from which to retreive the data [default: r2ta_results.sqlite]
-  -v, --verbose...              Increase logging verbosity
-  -o, --output-path <FILENAME>  File to extract the data to, if not present the data is written to stdout
-  -q, --quiet...                Decrease logging verbosity
-  -h, --help                    Print help
+  -i, --input <FILENAME>   Path to the r2ta_results.sqlite file from which to retreive the data [default: r2ta_results.sqlite]
+  -v, --verbose...         Increase logging verbosity
+  -o, --output <FILENAME>  File to extract the data to, if not present the data is written to stdout
+  -q, --quiet...           Decrease logging verbosity
+  -h, --help               Print help
 ```
 
 [`ros2trace`]: https://index.ros.org/p/ros2trace/

src/analyses/mod.rs

@@ -7,7 +7,8 @@ use crate::analyses::analysis::AnalysisOutputExt;
 use crate::analyses::event_iterator::get_buf_writer_for_path;
 use crate::argsv2::analysis_args::AnalysisArgs;
 use crate::argsv2::extract_args::AnalysisProperty;
-use crate::utils::binary_sql_store::BinarySQLStore;
+use crate::utils::binary_sql_store::BinarySqlStore;
+use crate::utils::binary_sql_store::v1::{BinarySqlStoreV1, BinarySqlStoreV1Table};
 
 pub mod analysis;
 pub mod event_iterator;
@@ -99,32 +100,18 @@ impl Analyses {
         if args.bundle_output()
             && let Some(path) = args.binary_bundle_path()
         {
-            let mut store = BinarySQLStore::new(&path)?;
+            let mut store = BinarySqlStoreV1::from_file(&path, true)?;
 
             if let Some(a) = &self.dependency_graph {
                 let dot_graph = a.display_as_dot(false, false, 1.0);
 
-                store.define_table("metadata", &["version int", "graph text"])?;
-                store.write_into(
-                    "metadata",
-                    "(version, graph)",
-                    [(1, dot_graph.to_string())].into_iter(),
-                    2,
+                store.insert(
+                    BinarySqlStoreV1Table::Graphs,
+                    [("dependency_graph", dot_graph.to_string())].into_iter(),
                 )?;
 
-                store.define_table(
-                    AnalysisProperty::MessageLatencies.table_name(),
-                    &[
-                        "id int",
-                        "source_node text",
-                        "destination_node text",
-                        "topic text",
-                        "data blob",
-                    ],
-                )?;
-                store.write_into(
-                    AnalysisProperty::MessageLatencies.table_name(),
-                    "(id, source_node, destination_node, topic, data)",
+                store.insert(
+                    BinarySqlStoreV1Table::Property(AnalysisProperty::MessageLatencies),
                     a.message_latencies(&dot_graph).iter().map(|m| {
                         (
                             m.id,
@@ -134,16 +121,10 @@ impl Analyses {
                             postcard::to_allocvec(&m.messages_latencies).unwrap(),
                         )
                     }),
-                    5,
                 )?;
 
-                store.define_table(
-                    AnalysisProperty::ActivationDelays.table_name(),
-                    &["id int", "node text", "interface text", "data blob"],
-                )?;
-                store.write_into(
-                    AnalysisProperty::ActivationDelays.table_name(),
-                    "(id, node, interface, data)",
+                store.insert(
+                    BinarySqlStoreV1Table::Property(AnalysisProperty::ActivationDelays),
                     a.activation_delays(&dot_graph).iter().map(|m| {
                         (
                             m.id,
@@ -152,16 +133,10 @@ impl Analyses {
                             postcard::to_allocvec(&m.activation_delays).unwrap(),
                         )
                     }),
-                    4,
                 )?;
 
-                store.define_table(
-                    AnalysisProperty::PublicationDelays.table_name(),
-                    &["id int", "node text", "interface text", "data blob"],
-                )?;
-                store.write_into(
-                    AnalysisProperty::PublicationDelays.table_name(),
-                    "(id, node, interface, data)",
+                store.insert(
+                    BinarySqlStoreV1Table::Property(AnalysisProperty::PublicationDelays),
                     a.publication_delays(&dot_graph).iter().map(|m| {
                         (
                             m.id,
@@ -170,43 +145,30 @@ impl Analyses {
                             postcard::to_allocvec(&m.publication_delays).unwrap(),
                         )
                     }),
-                    4,
                 )?;
 
-                store.define_table(
-                    AnalysisProperty::MessageDelays.table_name(),
-                    &["id int", "node text", "interface text", "data blob"],
-                )?;
-                store.write_into(
-                    AnalysisProperty::MessageDelays.table_name(),
-                    "(id, node, interface, data)",
-                    a.message_delays(&dot_graph).iter().map(|m| {
+                store.insert(
+                    BinarySqlStoreV1Table::Property(AnalysisProperty::CallbackDurations),
+                    a.callback_durations(&dot_graph).iter().map(|m| {
                         (
                             m.id,
                             &m.name.node,
                             &m.name.interface,
-                            postcard::to_allocvec(&m.messages_delays).unwrap(),
+                            postcard::to_allocvec(&m.callback_durations).unwrap(),
                         )
                     }),
-                    4,
                 )?;
 
-                store.define_table(
-                    AnalysisProperty::CallbackDurations.table_name(),
-                    &["id int", "node text", "interface text", "data blob"],
-                )?;
-                store.write_into(
-                    AnalysisProperty::CallbackDurations.table_name(),
-                    "(id, node, interface, data)",
-                    a.callback_durations(&dot_graph).iter().map(|m| {
+                store.insert(
+                    BinarySqlStoreV1Table::Property(AnalysisProperty::MessageDelays),
+                    a.message_delays(&dot_graph).iter().map(|m| {
                         (
                             m.id,
                             &m.name.node,
                             &m.name.interface,
-                            postcard::to_allocvec(&m.callback_durations).unwrap(),
+                            postcard::to_allocvec(&m.messages_delays).unwrap(),
                         )
                     }),
-                    4,
                 )?;
             }
         } else {

src/argsv2/analysis_args.rs

@@ -92,7 +92,7 @@ pub struct AnalysisArgs {
     #[arg(long, short = 'o', value_hint = ValueHint::DirPath)]
     out_dir: Option<PathBuf>,
 
-    /// Flag whether to bundle all outputs into a single file or export each analysis as a separate file
+    /// Store the results into multiple files rather than to the binary bundle
     #[arg(long)]
     legacy_output: bool,
 

src/argsv2/chart_args.rs

@@ -15,8 +15,9 @@ pub struct ChartArgs {
     #[clap(long, short = 'i', value_name = "FILENAME", value_hint = ValueHint::FilePath, default_value = analysis_args::filenames::BINARY_BUNDLE)]
     input: Option<PathBuf>,
 
+    /// Store the chart data to the given file
     #[clap(long, short = 'o', value_name = "FILENAME", value_hint = ValueHint::AnyPath)]
-    output_path: Option<PathBuf>,
+    output: Option<PathBuf>,
 
     /// Indicates whether the chart should be rendered from scratch.
     ///
@@ -38,7 +39,7 @@ impl ChartArgs {
     }
 
     pub fn output_path(&self) -> Option<&Path> {
-        self.output_path.as_deref()
+        self.output.as_deref()
     }
 
     pub fn clean(&self) -> bool {

src/argsv2/extract_args.rs

@@ -13,7 +13,7 @@ pub struct ExtractArgs {
 
     /// File to extract the data to, if not present the data is written to stdout
     #[clap(long, short = 'o', value_name = "FILENAME", value_hint = ValueHint::FilePath)]
-    output_path: Option<PathBuf>,
+    output: Option<PathBuf>,
 
     #[clap(subcommand)]
     extract_content: ExtractContentArgs,
@@ -36,7 +36,7 @@ impl ExtractArgs {
     }
 
     pub fn output_path(&self) -> Option<&Path> {
-        self.output_path.as_deref()
+        self.output.as_deref()
     }
 
     pub fn content(&self) -> &ExtractContentArgs {
@@ -74,7 +74,7 @@ impl ExtractPropertyArgs {
     }
 }
 
-#[derive(Debug, Display, ValueEnum, Clone)]
+#[derive(Debug, Display, ValueEnum, Clone, PartialEq, Eq, Hash)]
 pub enum AnalysisProperty {
     /// Callback execution durations
     #[display("Callback execution time")]
@@ -99,7 +99,7 @@ pub enum AnalysisProperty {
 
 impl AnalysisProperty {
     /// Table name in the binary data blob for this property
-    pub fn table_name(&self) -> &'static str {
+    pub const fn table_name(&self) -> &'static str {
         match self {
             AnalysisProperty::CallbackDurations => "callback_duration",
             AnalysisProperty::ActivationDelays => "activations_delay",

src/argsv2/mod.rs

@@ -52,7 +52,9 @@ impl Args {
 
 #[derive(Debug, Subcommand, Clone, derive_more::Display)]
 pub enum TracerCommand {
-    /// Analyze a ROS 2 trace and generate graphs, JSON or bundle outputs
+    /// Analyze a ROS 2 trace and store the result either as a binary bundle
+    /// or separate files. See the extract subcommand for how to work with the
+    /// binary bundle.
     #[display("analyze")]
     Analyze(Box<analysis_args::AnalysisArgs>),
 
@@ -64,7 +66,7 @@ pub enum TracerCommand {
     #[display("viewer")]
     Viewer(viewer_args::ViewerArgs),
 
-    /// Retreive data from bundled analysis results file into JSON format
+    /// Retrieve data from binary bundle produced by the analysis
     #[display("extract")]
     Extract(#[clap(subcommand)] extract_args::ExtractArgs),
 }