grafos_observe/

export.rs

//! Span exporters for grafOS distributed tracing.
//!
//! - [`NullExporter`]: Collects spans in memory for test assertions.
//! - [`SpanExporter`]: Trait for pluggable export backends.

extern crate alloc;

#[cfg(feature = "std")]
use alloc::boxed::Box;
use alloc::vec::Vec;

use crate::span::ResourceSpan;

#[cfg(feature = "std")]
static GLOBAL_SPAN_EXPORTER: std::sync::OnceLock<Box<dyn SpanExporter + Send + Sync>> =
    std::sync::OnceLock::new();

/// Trait for exporting completed spans.
pub trait SpanExporter {
    /// Export a batch of spans. Implementations should not block the caller
    /// for extended periods; buffering and async flush are preferred.
    fn export(&self, spans: &[ResourceSpan]);

    /// Flush any buffered spans. Called on shutdown.
    fn flush(&self);
}

/// Install a process-wide span exporter.
///
/// Only the first call takes effect. Runtime and scheduler paths use
/// [`emit_span`] after this has been installed. The global exporter is
/// intentionally process-wide, mirroring the event sink: callers that
/// need per-subsystem routing should install a multiplexer exporter.
#[cfg(feature = "std")]
pub fn set_global_span_exporter(exporter: Box<dyn SpanExporter + Send + Sync>) -> bool {
    GLOBAL_SPAN_EXPORTER.set(exporter).is_ok()
}

/// Emit one completed [`ResourceSpan`] to the process-wide exporter.
///
/// If no exporter has been installed this is a no-op; the caller's
/// operation must not depend on observability delivery.
#[cfg(feature = "std")]
pub fn emit_span(span: ResourceSpan) {
    if let Some(exporter) = GLOBAL_SPAN_EXPORTER.get() {
        exporter.export(&[span]);
    }
}

/// Flush the process-wide span exporter when one has been installed.
#[cfg(feature = "std")]
pub fn flush_global_span_exporter() {
    if let Some(exporter) = GLOBAL_SPAN_EXPORTER.get() {
        exporter.flush();
    }
}

/// No-op in `no_std` builds.
#[cfg(not(feature = "std"))]
pub fn emit_span(_span: ResourceSpan) {}

/// A test exporter that collects spans in memory.
///
/// Thread-safe via `std::sync::Mutex` (available when `std` feature is on)
/// or via single-threaded usage in `no_std` tests.
///
/// # Examples
///
/// ```
/// use grafos_observe::export::NullExporter;
/// use grafos_observe::export::SpanExporter;
/// use grafos_observe::span::ResourceSpan;
/// use grafos_observe::trace::TraceContext;
///
/// let exporter = NullExporter::new();
/// let span = ResourceSpan::new("test", TraceContext::default());
/// exporter.export(&[span]);
/// assert_eq!(exporter.len(), 1);
///
/// let spans = exporter.drain();
/// assert_eq!(spans.len(), 1);
/// assert_eq!(spans[0].name, "test");
/// ```
pub struct NullExporter {
    #[cfg(feature = "std")]
    spans: std::sync::Mutex<Vec<ResourceSpan>>,
    #[cfg(not(feature = "std"))]
    spans: core::cell::RefCell<Vec<ResourceSpan>>,
}

impl NullExporter {
    /// Create a new null exporter.
    pub fn new() -> Self {
        NullExporter {
            #[cfg(feature = "std")]
            spans: std::sync::Mutex::new(Vec::new()),
            #[cfg(not(feature = "std"))]
            spans: core::cell::RefCell::new(Vec::new()),
        }
    }

    /// Number of spans collected so far.
    pub fn len(&self) -> usize {
        #[cfg(feature = "std")]
        {
            self.spans.lock().unwrap().len()
        }
        #[cfg(not(feature = "std"))]
        {
            self.spans.borrow().len()
        }
    }

    /// Whether any spans have been collected.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Drain all collected spans, returning them and clearing the buffer.
    pub fn drain(&self) -> Vec<ResourceSpan> {
        #[cfg(feature = "std")]
        {
            let mut guard = self.spans.lock().unwrap();
            core::mem::take(&mut *guard)
        }
        #[cfg(not(feature = "std"))]
        {
            let mut guard = self.spans.borrow_mut();
            core::mem::take(&mut *guard)
        }
    }

    /// Get a snapshot (clone) of all collected spans.
    pub fn snapshot(&self) -> Vec<ResourceSpan> {
        #[cfg(feature = "std")]
        {
            self.spans.lock().unwrap().clone()
        }
        #[cfg(not(feature = "std"))]
        {
            self.spans.borrow().clone()
        }
    }
}

impl Default for NullExporter {
    fn default() -> Self {
        Self::new()
    }
}

impl SpanExporter for NullExporter {
    fn export(&self, spans: &[ResourceSpan]) {
        #[cfg(feature = "std")]
        {
            let mut guard = self.spans.lock().unwrap();
            guard.extend(spans.iter().cloned());
        }
        #[cfg(not(feature = "std"))]
        {
            let mut guard = self.spans.borrow_mut();
            guard.extend(spans.iter().cloned());
        }
    }

    fn flush(&self) {
        // Nothing to flush — spans are already in memory.
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::trace::TraceContext;
    #[cfg(feature = "std")]
    use std::sync::{Arc, Mutex};

    #[test]
    fn null_exporter_collects_and_drains() {
        let exporter = NullExporter::new();
        assert!(exporter.is_empty());

        let span1 = ResourceSpan::new("op1", TraceContext::default());
        let span2 = ResourceSpan::new("op2", TraceContext::default());
        exporter.export(&[span1, span2]);

        assert_eq!(exporter.len(), 2);

        let drained = exporter.drain();
        assert_eq!(drained.len(), 2);
        assert_eq!(drained[0].name, "op1");
        assert_eq!(drained[1].name, "op2");
        assert!(exporter.is_empty());
    }

    #[test]
    fn null_exporter_snapshot_does_not_drain() {
        let exporter = NullExporter::new();
        let span = ResourceSpan::new("snap", TraceContext::default());
        exporter.export(&[span]);

        let snap = exporter.snapshot();
        assert_eq!(snap.len(), 1);
        assert_eq!(exporter.len(), 1); // still there
    }

    #[test]
    fn null_exporter_multiple_exports() {
        let exporter = NullExporter::new();
        for i in 0..10 {
            let name = alloc::format!("span_{i}");
            let span = ResourceSpan::new(&name, TraceContext::default());
            exporter.export(&[span]);
        }
        assert_eq!(exporter.len(), 10);
    }

    #[cfg(feature = "std")]
    #[derive(Clone)]
    struct SharedExporter {
        spans: Arc<Mutex<Vec<ResourceSpan>>>,
    }

    #[cfg(feature = "std")]
    impl SpanExporter for SharedExporter {
        fn export(&self, spans: &[ResourceSpan]) {
            self.spans.lock().unwrap().extend(spans.iter().cloned());
        }

        fn flush(&self) {}
    }

    /// Phase 219.1 slice 199 — span production paths should share a
    /// single grafos-observe exporter hook instead of each crate
    /// inventing a local global. This pins the real `emit_span`
    /// routing path used by scheduler/runtime integration slices.
    #[cfg(feature = "std")]
    #[test]
    fn global_span_exporter_receives_emit_span() {
        let spans = Arc::new(Mutex::new(Vec::new()));
        let exporter = SharedExporter {
            spans: spans.clone(),
        };

        let _ = set_global_span_exporter(Box::new(exporter));
        emit_span(ResourceSpan::new(
            crate::contract::PHASE_219_SPAN_NAMES[0],
            TraceContext::default(),
        ));

        let captured = spans.lock().unwrap();
        assert!(
            captured
                .iter()
                .any(|span| span.name == crate::contract::PHASE_219_SPAN_NAMES[0]),
            "global span exporter must receive spans emitted through emit_span()"
        );
    }
}