Extract trace structs

Author: smklein

nexus/src/app/background/tasks/mod.rs

@@ -43,6 +43,7 @@ pub mod region_snapshot_replacement_start;
 pub mod region_snapshot_replacement_step;
 pub mod saga_recovery;
 pub mod service_firewall_rules;
+pub mod support_bundle;
 pub mod support_bundle_collector;
 pub mod sync_service_zone_nat;
 pub mod sync_switch_configuration;

nexus/src/app/background/tasks/support_bundle/mod.rs

@@ -0,0 +1,7 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! Support bundle related types and utilities
+
+pub mod perfetto;

nexus/src/app/background/tasks/support_bundle/perfetto.rs

@@ -0,0 +1,51 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! Perfetto Trace Event format support for visualizing support bundle collection
+
+use serde::Deserialize;
+use serde::Serialize;
+
+/// Represents a Perfetto Trace Event format JSON file for visualization.
+///
+/// This format is used by the Perfetto trace viewer (https://ui.perfetto.dev/)
+/// to visualize timing information for operations.
+#[derive(Serialize, Deserialize)]
+pub struct Trace {
+    #[serde(rename = "traceEvents")]
+    pub trace_events: Vec<TraceEvent>,
+    /// Display unit for time values in the UI (e.g., "ms" for milliseconds)
+    #[serde(rename = "displayTimeUnit")]
+    pub display_time_unit: String,
+}
+
+/// A single event in the Perfetto Trace Event format.
+///
+/// This represents a complete event (duration event) showing when an operation
+/// started and how long it took.
+#[derive(Serialize, Deserialize)]
+pub struct TraceEvent {
+    /// Human-readable name of the event
+    pub name: String,
+    /// Category name (abbreviated as "cat" in Perfetto format).
+    /// Used to group related events together in the trace viewer.
+    pub cat: String,
+    /// Phase type (abbreviated as "ph" in Perfetto format).
+    /// "X" means a "Complete" event with both timestamp and duration.
+    pub ph: String,
+    /// Timestamp in microseconds (abbreviated as "ts" in Perfetto format).
+    /// Represents when the event started, as microseconds since the epoch.
+    pub ts: i64,
+    /// Duration in microseconds (abbreviated as "dur" in Perfetto format).
+    /// How long the event took to complete.
+    pub dur: i64,
+    /// Process ID. Used to separate events into different process lanes
+    /// in the trace viewer.
+    pub pid: u32,
+    /// Thread ID. Used to separate events into different thread lanes
+    /// within a process in the trace viewer.
+    pub tid: usize,
+    /// Arbitrary key-value pairs with additional event metadata
+    pub args: serde_json::Value,
+}

nexus/src/app/background/tasks/support_bundle_collector.rs

@@ -78,6 +78,8 @@ use zip::ZipArchive;
 use zip::ZipWriter;
 use zip::write::FullFileOptions;
 
+use super::support_bundle::perfetto;
+
 // We use "/var/tmp" to use Nexus' filesystem for temporary storage,
 // rather than "/tmp", which would keep this collected data in-memory.
 const TEMPDIR: &str = "/var/tmp";
@@ -1088,27 +1090,27 @@ impl BundleCollection {
                     .max(0);
                 let step_id = i + 1;
 
-                json!({
-                    "name": step.name,
-                    "cat": "bundle_collection",
-                    "ph": "X",  // Complete event (has duration)
-                    "ts": start_us,
-                    "dur": duration_us,
-                    "pid": 1,
-                    "tid": step_id,
-                    "args": {
+                perfetto::TraceEvent {
+                    name: step.name.clone(),
+                    cat: "bundle_collection".to_string(),
+                    ph: "X".to_string(),
+                    ts: start_us,
+                    dur: duration_us,
+                    pid: 1,
+                    tid: step_id,
+                    args: json!({
                         "status": step.status.to_string(),
-                    }
-                })
+                    }),
+                }
             })
             .collect();
 
-        let trace_json = json!({
-            "traceEvents": trace_events,
-            "displayTimeUnit": "ms",
-        });
+        let trace = perfetto::Trace {
+            trace_events,
+            display_time_unit: "ms".to_string(),
+        };
 
-        let trace_content = serde_json::to_string_pretty(&trace_json)
+        let trace_content = serde_json::to_string_pretty(&trace)
             .context("Failed to serialize trace JSON")?;
 
         tokio::fs::write(&trace_path, trace_content).await.with_context(
@@ -1119,7 +1121,7 @@ impl BundleCollection {
             self.log,
             "Wrote trace file";
             "path" => %trace_path,
-            "num_events" => trace_events.len()
+            "num_events" => trace.trace_events.len()
         );
 
         Ok(())
@@ -2669,64 +2671,51 @@ mod test {
             .await
             .expect("Should be able to download trace file");
 
-        // Parse the trace file as JSON
+        // Parse the trace file using our Perfetto structs
         let body_bytes =
             response.into_body().collect().await.unwrap().to_bytes();
-        let trace_json: serde_json::Value = serde_json::from_slice(&body_bytes)
-            .expect("Trace file should be valid JSON");
+        let trace: perfetto::Trace = serde_json::from_slice(&body_bytes)
+            .expect("Trace file should be valid Perfetto JSON");
 
-        // Verify the structure matches Perfetto Trace Event format
-        let trace_events = trace_json
-            .get("traceEvents")
-            .expect("Should have traceEvents field")
-            .as_array()
-            .expect("traceEvents should be an array");
+        // Verify display time unit
+        assert_eq!(
+            trace.display_time_unit, "ms",
+            "Display time unit should be milliseconds"
+        );
 
         // We should have at least the main collection steps
         assert!(
-            !trace_events.is_empty(),
+            !trace.trace_events.is_empty(),
             "Should have at least one trace event"
         );
 
-        // Verify each event has the expected fields
-        for event in trace_events {
-            assert!(event.get("name").is_some(), "Event should have name");
+        // Verify each event has the expected structure
+        for event in &trace.trace_events {
+            // Verify category
             assert_eq!(
-                event.get("cat").and_then(|v| v.as_str()),
-                Some("bundle_collection"),
+                event.cat, "bundle_collection",
                 "Event should have category 'bundle_collection'"
             );
-            assert_eq!(
-                event.get("ph").and_then(|v| v.as_str()),
-                Some("X"),
-                "Event should be Complete event type"
-            );
-            assert!(
-                event.get("ts").and_then(|v| v.as_i64()).is_some(),
-                "Event should have timestamp"
-            );
-            assert!(
-                event.get("dur").and_then(|v| v.as_i64()).is_some(),
-                "Event should have duration"
-            );
-            assert!(
-                event.get("args").is_some(),
-                "Event should have args field"
-            );
+            // Verify phase type
+            assert_eq!(event.ph, "X", "Event should be Complete event type");
+            // Verify timestamps are positive
+            assert!(event.ts >= 0, "Event timestamp should be non-negative");
+            assert!(event.dur >= 0, "Event duration should be non-negative");
+            // Verify process and thread IDs are set
+            assert_eq!(event.pid, 1, "All events should have pid=1");
+            assert!(event.tid > 0, "Event thread ID should be positive");
         }
 
         // Verify we have the same number of events as steps in the report
         assert_eq!(
-            trace_events.len(),
+            trace.trace_events.len(),
             report.steps.len(),
             "Number of events should match number of steps"
         );
 
         // Verify step names match between report and trace
-        let trace_names: std::collections::HashSet<_> = trace_events
-            .iter()
-            .filter_map(|e| e.get("name").and_then(|v| v.as_str()))
-            .collect();
+        let trace_names: std::collections::HashSet<_> =
+            trace.trace_events.iter().map(|e| e.name.as_str()).collect();
         let report_names: std::collections::HashSet<_> =
             report.steps.iter().map(|s| s.name.as_str()).collect();
         assert_eq!(