From ea7df30eaca20b7ce3ead54236ff418f17384bb3 Mon Sep 17 00:00:00 2001
From: Jay Bosamiya <jayb@microsoft.com>
Date: Mon, 15 Dec 2025 16:27:10 -0800
Subject: [PATCH] Add tracing support

---
 Cargo.lock                               |  3 +++
 litebox/Cargo.toml                       |  1 +
 litebox/src/litebox.rs                   |  6 +++++-
 litebox_runner_linux_userland/Cargo.toml |  2 ++
 litebox_runner_linux_userland/src/lib.rs | 19 +++++++++++++++++++
 5 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/Cargo.lock b/Cargo.lock
index c3cb77dc0..585fd5394 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -796,6 +796,7 @@ dependencies = [
  "spin 0.9.8",
  "tar-no-std",
  "thiserror",
+ "tracing",
  "windows-sys 0.60.2",
 ]
 
@@ -946,6 +947,8 @@ dependencies = [
  "litebox_syscall_rewriter",
  "memmap2",
  "sha2",
+ "tracing",
+ "tracing-subscriber",
  "walkdir",
 ]
 
diff --git a/litebox/Cargo.toml b/litebox/Cargo.toml
index 52ad04fff..9bb54ed53 100644
--- a/litebox/Cargo.toml
+++ b/litebox/Cargo.toml
@@ -18,6 +18,7 @@ ringbuf = { version = "0.4.8", default-features = false, features = ["alloc"] }
 buddy_system_allocator = { version = "0.11.0", default-features = false, features = ["use_spin"] }
 # Depend on (currently unreleased) slabmalloc `main`, which contains some fixes on top of `0.11.0`
 slabmalloc = { git = "https://github.com/gz/rust-slabmalloc.git", rev = "19480b2e82704210abafe575fb9699184c1be110" }
+tracing = { version = "0.1.43", default-features = false }
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.60.2", features = [
diff --git a/litebox/src/litebox.rs b/litebox/src/litebox.rs
index 9b5be4c87..e4c458575 100644
--- a/litebox/src/litebox.rs
+++ b/litebox/src/litebox.rs
@@ -61,10 +61,14 @@ impl<Platform: RawSyncPrimitivesProvider> LiteBox<Platform> {
         #[cfg(feature = "lock_tracing")]
         crate::sync::lock_tracing::LockTracker::init(platform);
 
+        let descriptors = RwLock::new(Descriptors::new_from_litebox_creation());
+
+        tracing::debug!("LiteBox instance initialized");
+
         Self {
             x: Arc::new(LiteBoxX {
                 platform,
-                descriptors: RwLock::new(Descriptors::new_from_litebox_creation()),
+                descriptors,
             }),
         }
     }
diff --git a/litebox_runner_linux_userland/Cargo.toml b/litebox_runner_linux_userland/Cargo.toml
index 821f384c4..8988ea53c 100644
--- a/litebox_runner_linux_userland/Cargo.toml
+++ b/litebox_runner_linux_userland/Cargo.toml
@@ -14,6 +14,8 @@ litebox_platform_multiplex = { version = "0.1.0", path = "../litebox_platform_mu
 litebox_shim_linux = { version = "0.1.0", path = "../litebox_shim_linux" }
 litebox_syscall_rewriter = { version = "0.1.0", path = "../litebox_syscall_rewriter" }
 memmap2 = "0.9.8"
+tracing = "0.1.43"
+tracing-subscriber = { version = "0.3.22", features = ["env-filter"] }
 
 [dev-dependencies]
 sha2 = "0.10"
diff --git a/litebox_runner_linux_userland/src/lib.rs b/litebox_runner_linux_userland/src/lib.rs
index 8cebe2dd2..7f697a7af 100644
--- a/litebox_runner_linux_userland/src/lib.rs
+++ b/litebox_runner_linux_userland/src/lib.rs
@@ -10,6 +10,14 @@ use std::time::Duration;
 extern crate alloc;
 
 /// Run Linux programs with LiteBox on unmodified Linux
+///
+/// # Tracing
+///
+/// LiteBox supports detailed tracing output controlled by the `LITEBOX_LOG` environment variable.
+///
+/// Examples:
+/// - `LITEBOX_LOG=debug` - Show debug and higher level logs
+/// - `LITEBOX_LOG=litebox=debug,litebox::fs=trace` - Multiple filters at different levels
 #[derive(Parser, Debug)]
 pub struct CliArgs {
     /// The program and arguments passed to it (e.g., `python3 --version`)
@@ -82,6 +90,17 @@ static REQUIRE_RTLD_AUDIT: core::sync::atomic::AtomicBool =
 /// panic. If it does actually panic, then ping the authors of LiteBox, and likely a better error
 /// message could be thrown instead.
 pub fn run(cli_args: CliArgs) -> Result<()> {
+    // Initialize tracing subscriber with LITEBOX_LOG environment variable
+    tracing_subscriber::fmt()
+        .with_timer(tracing_subscriber::fmt::time::uptime())
+        .with_level(true)
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::builder()
+                .with_env_var("LITEBOX_LOG")
+                .from_env_lossy(),
+        )
+        .init();
+
     if !cli_args.insert_files.is_empty() {
         unimplemented!(
             "this should (hopefully soon) have a nicer interface to support loading in files"