feat: Add tracing feature (#24)

* feat: Add --features tracing

Also includes new examples/tracing.rs

* chore: Remove outdated TODO

* example: Update tracing example to fallback to trace if RUST_LOG isn't set

Also refactor to assume tracing feature is enabled as specified in
Cargo.toml

* feat: Add `default` and `full` meta-features

* chore: Enable --features=full in .vscode/settings.json

* chore: Define private macros module to DRY out conditional compilation of tracing events

* docs: Document crate feature flags

* fix: Fix clippy lints and light refactor pass for readability

* fix: Fix doc test

Author: brannondorsey

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "rust-analyzer.cargo.features": ["full"]
+}

Cargo.lock

@@ -9,20 +9,30 @@ readme = "README.md"
 repository = "https://github.com/brannondorsey/mem-isolate"
 keywords = ["memory", "isolation", "sandbox", "unix"]
 categories = ["memory-management", "os::unix-apis", "rust-patterns"]
-exclude = [
-    ".github/*",
-]
+exclude = [".github/*"]
+
+[features]
+# Include no features by default
+default = []
+
+# Include all features
+full = ["tracing"]
+
+# Actual features
+tracing = ["dep:tracing"]
 
 [dependencies]
 bincode = "1"
 libc = "0.2"
 serde = { version = "1", features = ["derive"] }
 thiserror = "2"
+tracing = { version = "0.1.41", optional = true }
 
 [dev-dependencies]
 criterion = "0.5.1"
 rand = "0.9.0"
 tempfile = "3.18.0"
+tracing-subscriber = { version = "0.3.19", features = ["env-filter"] }
 
 [[bench]]
 name = "benchmarks"
@@ -35,3 +45,7 @@ test = true
 [[example]]
 name = "error-handling-complete"
 test = true
+
+[[example]]
+name = "tracing"
+required-features = ["tracing"]

Cargo.toml

@@ -0,0 +1,29 @@
+// Compile error if tracing is not enabled
+#[cfg(not(feature = "tracing"))]
+compile_error!(
+    "This example requires the 'tracing' feature to be enabled. Run with: cargo run --example tracing --features tracing"
+);
+
+use mem_isolate::MemIsolateError;
+use tracing::{Level, info, instrument};
+use tracing_subscriber::EnvFilter;
+
+#[instrument]
+fn main() -> Result<(), MemIsolateError> {
+    init_tracing_subscriber();
+
+    mem_isolate::execute_in_isolated_process(|| {
+        info!("look ma, I'm in the callable!");
+        42
+    })?;
+
+    Ok(())
+}
+
+/// Defaults to TRACE but can be overridden by the RUST_LOG environment variable
+fn init_tracing_subscriber() {
+    let env_filter = EnvFilter::builder()
+        .with_default_directive(Level::TRACE.into())
+        .from_env_lossy();
+    tracing_subscriber::fmt().with_env_filter(env_filter).init();
+}

examples/tracing.rs

@@ -18,7 +18,7 @@ pub struct PipeFds {
 }
 
 // Define the core trait for system functions
-pub trait SystemFunctions {
+pub trait SystemFunctions: std::fmt::Debug {
     fn fork(&self) -> Result<ForkReturn, io::Error>;
     fn pipe(&self) -> Result<PipeFds, io::Error>;
     fn close(&self, fd: c_int) -> Result<(), io::Error>;

src/c.rs

@@ -6,7 +6,7 @@ use std::io;
 use std::thread_local;
 
 // Type for representing a mock result
-#[derive(Clone)]
+#[derive(Clone, Debug)]
 enum MockResult<T> {
     Ok(T),
     Err(i32), // OS error code
@@ -37,7 +37,7 @@ impl<T> MockResult<T> {
 }
 
 /// Defines how a call should be implemented - real or mocked
-#[derive(Clone)]
+#[derive(Clone, Debug)]
 enum CallImplementation<T> {
     Real,                // Use real implementation
     Mock(MockResult<T>), // Use mocked result
@@ -50,7 +50,7 @@ pub enum CallBehavior<T> {
 }
 
 /// A generic queue of call implementations
-#[derive(Clone)]
+#[derive(Clone, Debug)]
 struct CallQueue<T> {
     queue: RefCell<VecDeque<CallImplementation<T>>>,
     name: &'static str, // For better error messages
@@ -93,7 +93,7 @@ impl<T: Clone> CallQueue<T> {
 }
 
 /// Mock implementation that returns predefined values and can fall back to real implementation
-#[derive(Clone)]
+#[derive(Clone, Debug)]
 pub struct MockableSystemFunctions {
     real_impl: RealSystemFunctions,
     fallback_enabled: Cell<bool>,