[trace-guest] add Subscriber to capture traces/events

- Adds a type that implements the Subscriber trait of the tracing_core
crate that allows the type to be set as the global Subscriber of
the crate
- This way we can handle the adding of new spans and events
and store them where/how we want

Signed-off-by: Doru Blânzeanu <dblnz@pm.me>

Author: dblnz

src/hyperlight_guest_bin/src/guest_function/call.rs

@@ -128,6 +128,15 @@ pub(crate) extern "C" fn dispatch_function() {
     // part of the big identity-mapped region at the base of the
     // guest.
     crate::paging::flush_tlb();
+
+    // Read the current TSC to report it to the host with the spans/events
+    // This helps calculating the timestamps relative to the guest call
+    #[cfg(feature = "trace_guest")]
+    {
+        let guest_start_tsc = hyperlight_guest_tracing::invariant_tsc::read_tsc();
+        hyperlight_guest_tracing::set_start_tsc(guest_start_tsc);
+    }
+
     internal_dispatch_function();
     halt();
 }

src/hyperlight_guest_bin/src/lib.rs

@@ -181,6 +181,10 @@ static INIT: Once = Once::new();
 
 #[unsafe(no_mangle)]
 pub extern "C" fn entrypoint(peb_address: u64, seed: u64, ops: u64, max_log_level: u64) {
+    // Save the guest start TSC for tracing
+    #[cfg(feature = "trace_guest")]
+    let guest_start_tsc = hyperlight_guest_tracing::invariant_tsc::read_tsc();
+
     if peb_address == 0 {
         panic!("PEB address is null");
     }
@@ -229,6 +233,12 @@ pub extern "C" fn entrypoint(peb_address: u64, seed: u64, ops: u64, max_log_leve
                 .expect("Invalid log level");
             init_logger(max_log_level);
 
+            // It is important that all the tracing events are produced after the tracing is initialized.
+            #[cfg(feature = "trace_guest")]
+            if max_log_level != LevelFilter::Off {
+                hyperlight_guest_tracing::init_guest_tracing(guest_start_tsc);
+            }
+
             hyperlight_main();
         }
     });

src/hyperlight_guest_tracing/src/lib.rs

@@ -19,3 +19,55 @@ use heapless as hl;
 
 /// Expose invariant TSC module
 pub mod invariant_tsc;
+
+/// Defines internal guest state
+#[cfg(feature = "trace")]
+mod state;
+
+/// Defines guest tracing Subscriber
+#[cfg(feature = "trace")]
+mod subscriber;
+
+#[cfg(feature = "trace")]
+pub use trace::{init_guest_tracing, set_start_tsc};
+
+/// This module is gated because some of these types are also used on the host, but we want
+/// only the guest to allocate and allow the functionality intended for the guest.
+#[cfg(feature = "trace")]
+mod trace {
+    extern crate alloc;
+    use alloc::sync::{Arc, Weak};
+
+    use spin::Mutex;
+
+    use super::*;
+    use crate::state::GuestState;
+    use crate::subscriber::GuestSubscriber;
+
+    /// Weak reference to the guest state so we can manually trigger flush to host
+    static GUEST_STATE: spin::Once<Weak<Mutex<GuestState>>> = spin::Once::new();
+
+    /// Initialize the guest tracing subscriber as global default.
+    pub fn init_guest_tracing(guest_start_tsc: u64) {
+        // Set as global default if not already set.
+        if tracing_core::dispatcher::has_been_set() {
+            return;
+        }
+        let sub = GuestSubscriber::new(guest_start_tsc);
+        let state = sub.state();
+        // Store state Weak<GuestState> to use later at runtime
+        GUEST_STATE.call_once(|| Arc::downgrade(state));
+
+        // Set global dispatcher
+        let _ = tracing_core::dispatcher::set_global_default(tracing_core::Dispatch::new(sub));
+    }
+
+    /// Sets the guset starting timestamp reported to the host on a VMExit
+    pub fn set_start_tsc(guest_start_tsc: u64) {
+        if let Some(w) = GUEST_STATE.get() {
+            if let Some(state) = w.upgrade() {
+                state.lock().set_start_tsc(guest_start_tsc);
+            }
+        }
+    }
+}

src/hyperlight_guest_tracing/src/state.rs

@@ -0,0 +1,71 @@
+/*
+Copyright 2025  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+extern crate alloc;
+
+use core::sync::atomic::{AtomicU64, Ordering};
+
+use heapless as hl;
+use hyperlight_common::outb::OutBAction;
+use tracing_core::Event;
+use tracing_core::span::{Attributes, Id, Record};
+
+/// Internal state of the tracing subscriber
+pub(crate) struct GuestState {
+    /// The timestamp counter at the start of the guest execution.
+    guest_start_tsc: u64,
+}
+
+impl GuestState {
+    pub(crate) fn new(guest_start_tsc: u64) -> Self {
+        Self { guest_start_tsc }
+    }
+
+    /// Set a new guest start tsc
+    pub(crate) fn set_start_tsc(&mut self, guest_start_tsc: u64) {
+        self.guest_start_tsc = guest_start_tsc;
+    }
+
+    /// Create a new span and push it on the stack
+    pub(crate) fn new_span(&mut self, attrs: &Attributes) -> Id {
+        unimplemented!()
+    }
+
+    /// Record an event in the current span (top of the stack)
+    pub(crate) fn event(&mut self, event: &Event<'_>) {
+        unimplemented!()
+    }
+
+    /// Record new values for an existing span
+    pub(crate) fn record(&mut self, id: &Id, values: &Record<'_>) {
+        unimplemented!()
+    }
+
+    /// Enter a span (push it on the stack)
+    pub(crate) fn enter(&mut self, id: &Id) {
+        unimplemented!()
+    }
+
+    /// Exit a span (pop it from the stack)
+    pub(crate) fn exit(&mut self, _id: &Id) {
+        unimplemented!()
+    }
+
+    /// Try to close a span by ID, returning true if successful
+    /// Records the end timestamp for the span.
+    pub(crate) fn try_close(&mut self, id: Id) -> bool {
+        unimplemented!()
+    }
+}

src/hyperlight_guest_tracing/src/subscriber.rs

@@ -0,0 +1,78 @@
+/*
+Copyright 2025  The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+extern crate alloc;
+
+use alloc::sync::Arc;
+
+use spin::Mutex;
+use tracing_core::span::{Attributes, Id, Record};
+use tracing_core::subscriber::Subscriber;
+use tracing_core::{Event, Metadata};
+
+use crate::state::GuestState;
+
+/// The subscriber is used to collect spans and events in the guest.
+pub(crate) struct GuestSubscriber {
+    /// Internal state that holds the spans and events
+    /// Protected by a Mutex for inner mutability
+    /// A reference to this state is stored in a static variable
+    state: Arc<Mutex<GuestState>>,
+}
+
+impl GuestSubscriber {
+    pub(crate) fn new(guest_start_tsc: u64) -> Self {
+        Self {
+            state: Arc::new(Mutex::new(GuestState::new(guest_start_tsc))),
+        }
+    }
+    pub(crate) fn state(&self) -> &Arc<Mutex<GuestState>> {
+        &self.state
+    }
+}
+
+impl Subscriber for GuestSubscriber {
+    fn enabled(&self, _md: &Metadata<'_>) -> bool {
+        true
+    }
+
+    fn new_span(&self, attrs: &Attributes<'_>) -> Id {
+        self.state.lock().new_span(attrs)
+    }
+
+    fn record(&self, id: &Id, values: &Record<'_>) {
+        self.state.lock().record(id, values)
+    }
+
+    fn event(&self, event: &Event<'_>) {
+        self.state.lock().event(event)
+    }
+
+    fn enter(&self, id: &Id) {
+        self.state.lock().enter(id)
+    }
+
+    fn exit(&self, id: &Id) {
+        self.state.lock().exit(id)
+    }
+
+    fn try_close(&self, id: Id) -> bool {
+        self.state.lock().try_close(id)
+    }
+
+    fn record_follows_from(&self, _span: &Id, _follows: &Id) {
+        // no-op: we don't track follows-from relationships
+    }
+}