clenaup examples

Author: rcoh

dial9-tokio-telemetry/Cargo.toml

@@ -40,11 +40,13 @@ metrique-writer = "0.1"
 metrique = { version = "0.1.20", features = ["local-format"] }
 
 [features]
+analysis = []
 cpu-profiling = ["dep:dial9-perf-self-profile"]
 task-dump = ["tokio/taskdump"]
 worker-s3 = ["dep:aws-sdk-s3-transfer-manager", "dep:aws-sdk-s3", "dep:aws-config", "dep:time"]
 
 [dev-dependencies]
+dial9-tokio-telemetry = { path = ".", features = ["analysis"] }
 assert2 = { workspace = true }
 criterion = "0.5"
 clap = { version = "4", features = ["derive"] }
@@ -62,7 +64,7 @@ async-trait = "0.1.89"
 uuid = { version = "1", features = ["v4"] }
 
 [target.'cfg(target_os = "linux")'.dev-dependencies]
-dial9-tokio-telemetry = { path = ".", features = ["cpu-profiling", "worker-s3"] }
+dial9-tokio-telemetry = { path = ".", features = ["cpu-profiling", "worker-s3", "analysis"] }
 nix = { version = "0.29", features = ["process"] }
 
 [[bench]]
@@ -96,15 +98,27 @@ required-features = ["cpu-profiling"]
 
 [[example]]
 name = "cpu_profile_workload"
-required-features = ["cpu-profiling"]
+required-features = ["cpu-profiling", "analysis"]
 
 [[example]]
 name = "s3_stress_test"
 required-features = ["worker-s3"]
 
+[[example]]
+name = "analyze_trace"
+required-features = ["analysis"]
+
+[[example]]
+name = "trace_to_jsonl"
+required-features = ["analysis"]
+
+[[example]]
+name = "trace_to_fat_jsonl"
+required-features = ["analysis"]
+
 [[example]]
 name = "kernel_sched_events"
-required-features = ["cpu-profiling"]
+required-features = ["cpu-profiling", "analysis"]
 
 [[bench]]
 name = "writer_encode"

dial9-tokio-telemetry/examples/analyze_trace.rs

@@ -1,7 +1,7 @@
-use dial9_tokio_telemetry::telemetry::{
-    TaskId, TelemetryEvent, TraceReader, UNKNOWN_TASK_ID, analyze_trace,
-    compute_wake_to_poll_delays, detect_idle_workers, print_analysis,
+use dial9_tokio_telemetry::analysis_unstable::{
+    TraceReader, analyze_trace, compute_wake_to_poll_delays, detect_idle_workers, print_analysis,
 };
+use dial9_tokio_telemetry::telemetry::{TaskId, TelemetryEvent, UNKNOWN_TASK_ID};
 use std::collections::HashMap;
 use std::env;
 

dial9-tokio-telemetry/examples/cpu_profile_workload.rs

@@ -60,7 +60,7 @@ fn main() {
 
     // Read back and report
     eprintln!("\n=== Reading trace from {trace_path} ===");
-    let reader = dial9_tokio_telemetry::telemetry::TraceReader::new(trace_path).unwrap();
+    let reader = dial9_tokio_telemetry::analysis_unstable::TraceReader::new(trace_path).unwrap();
     let events = &reader.runtime_events;
     let mut cpu_samples = 0;
     let mut polls = 0;

dial9-tokio-telemetry/examples/kernel_sched_events.rs

@@ -42,8 +42,9 @@
 //!   ...
 //!   start_thread
 
+use dial9_tokio_telemetry::analysis_unstable::TraceReader;
 use dial9_tokio_telemetry::telemetry::{
-    CpuSampleSource, RotatingWriter, SchedEventConfig, TelemetryEvent, TraceReader, TracedRuntime,
+    CpuSampleSource, RotatingWriter, SchedEventConfig, TelemetryEvent, TracedRuntime,
 };
 use std::time::Duration;
 

dial9-tokio-telemetry/examples/trace_to_fat_jsonl.rs

@@ -3,7 +3,8 @@
 //! Usage:
 //!   cargo run --example trace_to_fat_jsonl -- <input.bin> [output.jsonl]
 
-use dial9_tokio_telemetry::telemetry::{TelemetryEvent, TraceReader};
+use dial9_tokio_telemetry::analysis_unstable::TraceReader;
+use dial9_tokio_telemetry::telemetry::TelemetryEvent;
 use serde::Serialize;
 use std::io::{BufWriter, Write};
 

dial9-tokio-telemetry/examples/trace_to_jsonl.rs

@@ -5,7 +5,7 @@
 //!
 //! If output is omitted, writes to stdout.
 
-use dial9_tokio_telemetry::telemetry::TraceReader;
+use dial9_tokio_telemetry::analysis_unstable::TraceReader;
 use std::io::{BufWriter, Write};
 
 fn main() -> std::io::Result<()> {

dial9-tokio-telemetry/src/analysis_unstable.rs

@@ -0,0 +1,24 @@
+//! Trace analysis utilities (**unstable**).
+//!
+//! This module is feature-gated behind `analysis` and re-exports every public
+//! type and function from the internal `telemetry::analysis` implementation.
+//!
+//! The API surface here is still evolving — hence the `_unstable` suffix.
+//! Expect breaking changes between minor versions.
+//!
+//! # Quick start
+//!
+//! ```rust,ignore
+//! use dial9_tokio_telemetry::analysis_unstable::{TraceReader, analyze_trace, print_analysis};
+//!
+//! let reader = TraceReader::new("trace.0.bin")?;
+//! let analysis = analyze_trace(&reader);
+//! print_analysis(&analysis);
+//! ```
+
+pub use crate::telemetry::analysis::{
+    ActivePeriod, LongPoll, SampledPoll, SchedDelay, SpawnLocationStats, TraceAnalysis,
+    TraceReader, WakeDelay, WorkerStats, analyze_trace, compute_active_periods,
+    compute_wake_to_poll_delays, detect_idle_workers, detect_long_polls, detect_sampled_polls,
+    detect_sched_delays, detect_wake_delays, print_analysis,
+};

dial9-tokio-telemetry/src/lib.rs

@@ -1,5 +1,7 @@
 #![doc = include_str!("../README.md")]
 
+#[cfg(feature = "analysis")]
+pub mod analysis_unstable;
 pub mod background_task;
 pub(crate) mod metrics;
 pub mod telemetry;

dial9-tokio-telemetry/src/telemetry/mod.rs

@@ -3,6 +3,7 @@
 //! All public types are re-exported here — use `dial9_tokio_telemetry::telemetry::*`
 //! rather than reaching into sub-modules.
 
+#[cfg(feature = "analysis")]
 pub(crate) mod analysis;
 pub(crate) mod buffer;
 pub(crate) mod collector;
@@ -14,12 +15,6 @@ pub(crate) mod recorder;
 pub(crate) mod task_metadata;
 pub(crate) mod writer;
 
-pub use analysis::{
-    ActivePeriod, LongPoll, SampledPoll, SchedDelay, SpawnLocationStats, TraceAnalysis,
-    TraceReader, WakeDelay, WorkerStats, analyze_trace, compute_active_periods,
-    compute_wake_to_poll_delays, detect_idle_workers, detect_long_polls, detect_sampled_polls,
-    detect_sched_delays, detect_wake_delays, print_analysis,
-};
 #[cfg(feature = "cpu-profiling")]
 pub use cpu_profile::CpuProfilingConfig;
 #[cfg(feature = "cpu-profiling")]

dial9-tokio-telemetry/src/telemetry/recorder/mod.rs

@@ -811,6 +811,7 @@ mod tests {
     }
 
     #[test]
+    #[cfg(feature = "analysis")]
     fn test_spawn_locations_resolve_after_rotation() {
         use crate::telemetry::analysis::TraceReader;
         use crate::telemetry::format::WorkerId;
@@ -902,7 +903,7 @@ mod tests {
         );
     }
 
-    #[cfg(feature = "cpu-profiling")]
+    #[cfg(all(feature = "cpu-profiling", feature = "analysis"))]
     mod rotation_proptest {
         use super::*;
         use crate::telemetry::analysis::TraceReader;