veecle_telemetry/

span.rs

//! Distributed tracing spans for tracking units of work.
//!
//! This module provides the core span implementation for distributed tracing.
//! Spans represent units of work within a trace and can be nested to show
//! relationships between different operations.
//!
//! # Key Concepts
//!
//! - **Span**: A unit of work within a trace, with a name and optional attributes
//! - **Span Context**: The trace and span IDs that identify a span within a trace
//! - **Span Guards**: RAII guards that automatically handle span entry/exit
//!
//! # Basic Usage
//!
//! ```rust
//! use veecle_telemetry::{span, CurrentSpan};
//!
//! // Create and enter a span
//! let span = span!("operation", user_id = 123);
//! let _guard = span.entered();
//!
//! // Add events to the current span
//! CurrentSpan::add_event("checkpoint", &[]);
//!
//! // Span is automatically exited when guard is dropped
//! ```
//!
//! # Span Lifecycle
//!
//! 1. **Creation**: Spans are created with a name and optional attributes
//! 2. **Entry**: Spans are entered to make them the current active span
//! 3. **Events**: Events and attributes can be added to active spans
//! 4. **Exit**: Spans are exited when no longer active
//! 5. **Close**: Spans are closed when their work is complete
//!
//! # Nesting
//!
//! Spans can be nested to show relationships:
//!
//! ```rust
//! use veecle_telemetry::span;
//!
//! let parent = span!("parent_operation");
//! let _parent_guard = parent.entered();
//!
//! // This span will automatically be a child of the parent
//! let child = span!("child_operation");
//! let _child_guard = child.entered();
//! ```

use core::marker::PhantomData;

use crate::SpanContext;
#[cfg(feature = "enable")]
use crate::collector::get_collector;
#[cfg(feature = "enable")]
use crate::id::SpanId;
use crate::protocol::transient::KeyValue;

/// A distributed tracing span representing a unit of work.
///
/// Spans are the fundamental building blocks of distributed tracing.
/// They represent a unit of work within a trace and can be nested to show relationships between different operations.
///
/// # Examples
///
/// ```rust
/// use veecle_telemetry::Span;
/// use veecle_telemetry::protocol::transient::{KeyValue, Value};
///
/// // Create a span with attributes
/// let span = Span::new("database_query", &[
///     KeyValue::new("table", "users"),
///     KeyValue::new("operation", "SELECT"),
/// ]);
///
/// // Enter the span to make it active
/// let _guard = span.enter();
///
/// // Add events to the span
/// span.add_event("query_executed", &[]);
/// ```
///
/// # Conditional Compilation
///
/// When the `enable` feature is disabled, spans compile to no-ops with zero runtime overhead.
#[must_use]
#[derive(Default, Debug)]
pub struct Span {
    #[cfg(feature = "enable")]
    pub(crate) span_id: Option<SpanId>,
}

/// Utilities for working with the currently active span.
///
/// This struct provides static methods for interacting with the current span
/// in the thread-local context.
/// It allows adding events, links, and attributes to the currently active span without needing a direct reference to
/// it.
///
/// # Examples
///
/// ```rust
/// use veecle_telemetry::{CurrentSpan, span};
///
/// let span = span!("operation");
/// let _guard = span.entered();
///
/// // Add an event to the current span
/// CurrentSpan::add_event("milestone", &[]);
/// ```
#[derive(Default, Debug)]
pub struct CurrentSpan;

impl Span {
    /// Creates a no-op span that performs no tracing operations.
    ///
    /// This is useful for creating spans that may be conditionally enabled
    /// or when telemetry is completely disabled.
    #[inline]
    pub fn noop() -> Self {
        Self {
            #[cfg(feature = "enable")]
            span_id: None,
        }
    }

    /// Creates a new span as a child of the current span.
    ///
    /// If there is no current span, this returns a new root span.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the span
    /// * `attributes` - Key-value attributes to attach to the span
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::Span;
    /// use veecle_telemetry::protocol::transient::{KeyValue, Value};
    ///
    /// let span = Span::new("operation", &[KeyValue::new("user_id", Value::I64(123))]);
    /// ```
    pub fn new<'a>(name: &'a str, attributes: &'a [KeyValue<'a>]) -> Self {
        #[cfg(not(feature = "enable"))]
        {
            let _ = (name, attributes);
            Self::noop()
        }

        #[cfg(feature = "enable")]
        {
            Self::new_inner(name, attributes)
        }
    }

    /// Creates a [`SpanContext`] from this [`Span`].
    /// For a noop span, this function will return `None`.
    ///
    /// # Examples
    ///
    /// ```
    /// use veecle_telemetry::Span;
    ///
    /// let span = Span::new("root_span", &[]);
    /// assert!(span.context().is_some());
    /// ```
    pub fn context(&self) -> Option<SpanContext> {
        #[cfg(not(feature = "enable"))]
        {
            None
        }

        #[cfg(feature = "enable")]
        {
            self.span_id
                .map(|span_id| SpanContext::new(get_collector().process_id(), span_id))
        }
    }

    /// Enters this span, making it the current active span.
    ///
    /// This method returns a guard that will automatically exit the span when dropped.
    /// The guard borrows the span, so the span must remain alive while the guard exists.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::Span;
    ///
    /// let span = Span::new("operation", &[]);
    /// let _guard = span.enter();
    /// // span is now active
    /// // span is automatically exited when _guard is dropped
    /// ```
    pub fn enter(&'_ self) -> SpanGuardRef<'_> {
        #[cfg(not(feature = "enable"))]
        {
            SpanGuardRef::noop()
        }

        #[cfg(feature = "enable")]
        {
            self.do_enter();
            SpanGuardRef::new(self)
        }
    }

    /// Enters this span by taking ownership of it.
    ///
    /// This method consumes the span and returns a guard that owns the span.
    /// The span will be automatically exited and closed when the guard is dropped.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::Span;
    ///
    /// let span = Span::new("operation", &[]);
    /// let _guard = span.entered();
    /// // span is now active and owned by the guard
    /// // span is automatically exited and closed when _guard is dropped
    /// ```
    pub fn entered(self) -> SpanGuard {
        #[cfg(not(feature = "enable"))]
        {
            SpanGuard::noop()
        }

        #[cfg(feature = "enable")]
        {
            self.do_enter();
            SpanGuard::new(self)
        }
    }

    /// Adds an event to this span.
    ///
    /// Events represent point-in-time occurrences within a span's lifetime.
    /// They can include additional attributes for context.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the event
    /// * `attributes` - Key-value attributes providing additional context
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::Span;
    /// use veecle_telemetry::protocol::transient::{KeyValue, Value};
    ///
    /// let span = Span::new("database_query", &[]);
    /// span.add_event("query_started", &[]);
    /// span.add_event("query_completed", &[KeyValue::new("rows_returned", Value::I64(42))]);
    /// ```
    pub fn add_event<'a>(&self, name: &'a str, attributes: &'a [KeyValue<'a>]) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = (name, attributes);
        }

        #[cfg(feature = "enable")]
        {
            if let Some(span_id) = self.span_id {
                get_collector().span_event(Some(span_id), name, attributes);
            }
        }
    }

    /// Creates a link from this span to another span.
    ///
    /// Links connect spans across different traces, allowing you to represent
    /// relationships between spans that are not parent-child relationships.
    ///
    /// # Examples
    ///
    /// ```
    /// use veecle_telemetry::{Span, SpanContext, SpanId, ProcessId};
    ///
    /// let span = Span::new("my_span", &[]);
    /// let external_context = SpanContext::new(ProcessId::from_raw(0x123), SpanId(0x456));
    /// span.add_link(external_context);
    /// ```
    pub fn add_link(&self, link: SpanContext) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = link;
        }

        #[cfg(feature = "enable")]
        {
            if let Some(span_id) = self.span_id {
                get_collector().span_link(Some(span_id), link);
            }
        }
    }

    /// Adds an attribute to this span.
    ///
    /// Attributes provide additional context about the work being performed
    /// in the span. They can be set at any time during the span's lifetime.
    ///
    /// # Arguments
    ///
    /// * `attribute` - The key-value attribute to set
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::Span;
    /// use veecle_telemetry::protocol::transient::{KeyValue, Value};
    ///
    /// let span = Span::new("user_operation", &[]);
    /// span.set_attribute(KeyValue::new("user_id", 123));
    /// span.set_attribute(KeyValue::new("operation_type", "update"));
    /// ```
    pub fn set_attribute<'a>(&self, attribute: KeyValue<'a>) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = attribute;
        }

        #[cfg(feature = "enable")]
        {
            if let Some(span_id) = self.span_id {
                get_collector().span_attribute(Some(span_id), attribute);
            }
        }
    }
}

impl CurrentSpan {
    /// Adds an event to the current span.
    ///
    /// Events represent point-in-time occurrences within a span's lifetime.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the event
    /// * `attributes` - Key-value attributes providing additional context
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::{CurrentSpan, span};
    /// use veecle_telemetry::protocol::transient::KeyValue;
    ///
    /// let _guard = span!("operation").entered();
    /// CurrentSpan::add_event("checkpoint", &[]);
    /// CurrentSpan::add_event("milestone", &[KeyValue::new("progress", 75)]);
    /// ```
    pub fn add_event<'a>(name: &'a str, attributes: &'a [KeyValue<'a>]) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = (name, attributes);
        }

        #[cfg(feature = "enable")]
        {
            get_collector().span_event(None, name, attributes);
        }
    }

    /// Creates a link from the current span to another span.
    ///
    /// Links connect spans across different traces, allowing you to represent
    /// relationships between spans that are not parent-child relationships.
    ///
    /// # Examples
    ///
    /// ```
    /// use veecle_telemetry::{CurrentSpan, Span, SpanContext, SpanId, ProcessId};
    ///
    /// let _guard = Span::new("my_span", &[]).entered();
    ///
    /// let external_context = SpanContext::new(ProcessId::from_raw(0x123), SpanId(0x456));
    /// CurrentSpan::add_link(external_context);
    /// ```
    pub fn add_link(link: SpanContext) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = link;
        }

        #[cfg(feature = "enable")]
        {
            get_collector().span_link(None, link);
        }
    }

    /// Sets an attribute on the current span.
    ///
    /// Attributes provide additional context about the work being performed
    /// in the span.
    ///
    /// # Arguments
    ///
    /// * `attribute` - The key-value attribute to set
    ///
    /// # Examples
    ///
    /// ```rust
    /// use veecle_telemetry::{CurrentSpan, span};
    /// use veecle_telemetry::protocol::transient::KeyValue;
    ///
    /// let _guard = span!("operation").entered();
    /// CurrentSpan::set_attribute(KeyValue::new("user_id", 123));
    /// CurrentSpan::set_attribute(KeyValue::new("status", "success"));
    /// ```
    pub fn set_attribute<'a>(attribute: KeyValue<'a>) {
        #[cfg(not(feature = "enable"))]
        {
            let _ = attribute;
        }

        #[cfg(feature = "enable")]
        {
            get_collector().span_attribute(None, attribute);
        }
    }
}

#[cfg(feature = "enable")]
impl Span {
    fn new_inner<'a>(name: &'a str, attributes: &'a [KeyValue<'a>]) -> Self {
        let span_id = SpanId::next_id();

        get_collector().new_span(span_id, name, attributes);

        Self {
            span_id: Some(span_id),
        }
    }

    fn do_enter(&self) {
        #[cfg(feature = "enable")]
        if let Some(span_id) = self.span_id {
            get_collector().enter_span(span_id);
        }
    }

    fn do_exit(&self) {
        #[cfg(feature = "enable")]
        if let Some(span_id) = self.span_id {
            get_collector().exit_span(span_id);
        }
    }
}

impl Drop for Span {
    fn drop(&mut self) {
        #[cfg(feature = "enable")]
        if let Some(span_id) = self.span_id.take() {
            get_collector().close_span(span_id);
        }
    }
}

/// Exits and drops the span when this is dropped.
#[derive(Debug)]
pub struct SpanGuard {
    #[cfg(feature = "enable")]
    pub(crate) inner: Option<SpanGuardInner>,

    /// ```compile_fail
    /// use veecle_telemetry::span::*;
    /// trait AssertSend: Send {}
    ///
    /// impl AssertSend for SpanGuard {}
    /// ```
    _not_send: PhantomNotSend,
}

#[cfg(feature = "enable")]
#[derive(Debug)]
pub(crate) struct SpanGuardInner {
    span: Span,
}

impl SpanGuard {
    #[cfg(not(feature = "enable"))]
    pub(crate) fn noop() -> Self {
        Self {
            #[cfg(feature = "enable")]
            inner: None,
            _not_send: PhantomNotSend,
        }
    }

    #[cfg(feature = "enable")]
    pub(crate) fn new(span: Span) -> Self {
        Self {
            #[cfg(feature = "enable")]
            inner: Some(SpanGuardInner { span }),
            _not_send: PhantomNotSend,
        }
    }
}

impl Drop for SpanGuard {
    fn drop(&mut self) {
        #[cfg(feature = "enable")]
        if let Some(inner) = self.inner.take() {
            inner.span.do_exit();
        }
    }
}

/// Exits the span when dropped.
#[derive(Debug)]
pub struct SpanGuardRef<'a> {
    #[cfg(feature = "enable")]
    pub(crate) inner: Option<SpanGuardRefInner<'a>>,

    _phantom: PhantomData<&'a ()>,
}

#[cfg(feature = "enable")]
#[derive(Debug)]
pub(crate) struct SpanGuardRefInner<'a> {
    span: &'a Span,
}

impl<'a> SpanGuardRef<'a> {
    #[cfg(not(feature = "enable"))]
    pub(crate) fn noop() -> Self {
        Self {
            #[cfg(feature = "enable")]
            inner: None,
            _phantom: PhantomData,
        }
    }

    #[cfg(feature = "enable")]
    pub(crate) fn new(span: &'a Span) -> Self {
        Self {
            #[cfg(feature = "enable")]
            inner: Some(SpanGuardRefInner { span }),
            _phantom: PhantomData,
        }
    }
}

impl Drop for SpanGuardRef<'_> {
    fn drop(&mut self) {
        #[cfg(feature = "enable")]
        if let Some(inner) = self.inner.take() {
            inner.span.do_exit();
        }
    }
}

/// Technically, `SpanGuard` _can_ implement both `Send` *and*
/// `Sync` safely. It doesn't, because it has a `PhantomNotSend` field,
/// specifically added in order to make it `!Send`.
///
/// Sending an `SpanGuard` guard between threads cannot cause memory unsafety.
/// However, it *would* result in incorrect behavior, so we add a
/// `PhantomNotSend` to prevent it from being sent between threads. This is
/// because it must be *dropped* on the same thread that it was created;
/// otherwise, the span will never be exited on the thread where it was entered,
/// and it will attempt to exit the span on a thread that may never have entered
/// it. However, we still want them to be `Sync` so that a struct holding an
/// `Entered` guard can be `Sync`.
///
/// Thus, this is totally safe.
#[derive(Debug)]
struct PhantomNotSend {
    ghost: PhantomData<*mut ()>,
}

#[allow(non_upper_case_globals)]
const PhantomNotSend: PhantomNotSend = PhantomNotSend { ghost: PhantomData };

/// # Safety:
///
/// Trivially safe, as `PhantomNotSend` doesn't have any API.
unsafe impl Sync for PhantomNotSend {}

#[cfg(all(test, feature = "std"))]
mod tests {
    use super::*;
    use crate::protocol::transient::{KeyValue, ProcessId, SpanContext, SpanId};

    #[test]
    fn span_noop() {
        let span = Span::noop();
        assert!(span.span_id.is_none());
    }

    #[test]
    fn span_context_from_span() {
        let span = Span::new("test_span", &[]);

        let extracted_context = span.context();
        let context = extracted_context.unwrap();
        assert_eq!(context.process_id, get_collector().process_id());
    }

    #[test]
    fn span_context_from_noop_span() {
        let span = Span::noop();
        let extracted_context = span.context();
        assert!(extracted_context.is_none());
    }

    #[test]
    fn span_event() {
        let span = Span::new("test_span", &[]);

        let event_attributes = [KeyValue::new("event_key", "event_value")];

        span.add_event("test_event", &event_attributes);

        let noop_span = Span::noop();
        noop_span.add_event("noop_event", &event_attributes);
    }

    #[test]
    fn span_link() {
        let span = Span::new("test_span", &[]);

        let link_context = SpanContext::new(ProcessId::from_raw(0), SpanId(0));
        span.add_link(link_context);

        let noop_span = Span::noop();
        noop_span.add_link(link_context);
    }

    #[test]
    fn span_attribute() {
        let span = Span::new("test_span", &[]);

        let attribute = KeyValue::new("test_key", "test_value");
        span.set_attribute(attribute.clone());

        let noop_span = Span::noop();
        noop_span.set_attribute(attribute);
    }

    #[test]
    fn span_methods_with_entered_span() {
        let span = Span::new("test_span", &[]);

        let _guard = span.enter();

        // All these should work while span is entered
        span.add_event("entered_event", &[]);
        span.add_link(SpanContext::new(ProcessId::from_raw(0), SpanId(0)));
        span.set_attribute(KeyValue::new("entered_key", true));
    }

    #[test]
    fn current_span_event_with_active_span() {
        let _root_guard = Span::new("test_span", &[]).entered();

        let event_attributes = [KeyValue::new("current_event_key", "current_event_value")];
        CurrentSpan::add_event("current_test_event", &event_attributes);
    }

    #[test]
    fn current_span_link_with_active_span() {
        let _root_guard = Span::new("test_span", &[]).entered();

        let link_context = SpanContext::new(ProcessId::from_raw(0), SpanId(0));
        CurrentSpan::add_link(link_context);
    }

    #[test]
    fn current_span_attribute_with_active_span() {
        let span = Span::new("test_span", &[]);

        let _guard = span.enter();
        let attribute = KeyValue::new("current_attr_key", "current_attr_value");
        CurrentSpan::set_attribute(attribute);
    }
}