otel/

lib.rs

#![doc = include_str!("../README.md")]

/// OpenTelemetry specification version used for schema URLs.
///
/// This version is included in all tracer configurations to indicate
/// which OpenTelemetry semantic conventions are being followed.
pub const OTEL_SPEC_VERSION: &str = "1.38.0";

/// Creates a static OpenTelemetry tracer for instrumentation.
///
/// This macro creates a `LazyLock<BoxedTracer>` static that initializes on first use
/// from the global tracer provider. Declare at crate or module root, then import
/// where needed.
///
/// # Prerequisites
///
/// The global tracer provider must be initialized before any spans are created.
/// Typically done in `main()` before calling into application code:
///
/// ```ignore
/// fn main() {
///     let provider = opentelemetry_otlp::new_pipeline()
///         .tracing()
///         .with_exporter(opentelemetry_otlp::new_exporter().tonic())
///         .install_batch(opentelemetry_sdk::runtime::Tokio)
///         .expect("Failed to initialize tracer");
///
///     opentelemetry::global::set_tracer_provider(provider);
///
///     run_app();  // Now TRACER can be used
///
///     opentelemetry::global::shutdown_tracer_provider();
/// }
/// ```
///
/// # Variants
///
/// ## Default tracer (no arguments)
///
/// Creates a `TRACER` static using the crate's package name as the instrumentation scope:
///
/// ```ignore
/// // In lib.rs or main.rs
/// otel::tracer!();
///
/// // Creates: pub(crate) static TRACER: LazyLock<BoxedTracer>
/// // Scope name: env!("CARGO_PKG_NAME")
/// ```
///
/// ## Named tracer
///
/// Creates a tracer with a custom name suffix, useful for subsystems:
///
/// ```ignore
/// // In src/client/mod.rs
/// otel::tracer!(lsp_client);
///
/// // Creates: pub(crate) static LSP_CLIENT_TRACER: LazyLock<BoxedTracer>
/// // Scope name: "{CARGO_PKG_NAME}.lsp_client"
/// ```
///
/// # Tracer Configuration
///
/// Each tracer is configured with:
///
/// | Property | Value |
/// |----------|-------|
/// | Scope name | Crate name, or `{crate}.{subsystem}` for named tracers |
/// | Version | `CARGO_PKG_VERSION` |
/// | Schema URL | `https://opentelemetry.io/schemas/{OTEL_SPEC_VERSION}` |
///
/// # Multiple Tracers
///
/// Use named tracers to separate instrumentation by subsystem. This makes it easy
/// to filter traces by scope in your observability backend:
///
/// ```ignore
/// // src/lib.rs - default tracer for general use
/// otel::tracer!();
///
/// // src/client/mod.rs - client subsystem
/// otel::tracer!(client);
///
/// // src/server/mod.rs - server subsystem
/// otel::tracer!(server);
/// ```
///
/// Use explicit tracer syntax in `span!` to select which tracer to use:
///
/// ```ignore
/// use crate::client::CLIENT_TRACER;
///
/// fn send_request() {
///     let (_cx, _guard) = otel::span!(@CLIENT_TRACER, "request.send");
/// }
/// ```
///
/// # Example: Full Setup
///
/// ```ignore
/// // src/lib.rs
/// otel::tracer!();
///
/// pub mod engine;
/// ```
///
/// ```ignore
/// // src/engine.rs
/// use crate::TRACER;
///
/// pub fn run() {
///     let (_cx, _guard) = otel::span!("engine.run");
///     // ...
/// }
/// ```
#[macro_export]
macro_rules! tracer {
  ($name:ident) => {
    paste::paste! {
      pub(crate) static [<$name:snake:upper _TRACER>]: std::sync::LazyLock<opentelemetry::global::BoxedTracer> =
        std::sync::LazyLock::new(|| {
          use opentelemetry::trace::TracerProvider;

          opentelemetry::global::tracer_provider().tracer_with_scope(
            opentelemetry::InstrumentationScope::builder(concat!(
              env!("CARGO_PKG_NAME"),
              ".", stringify!([<$name:snake>])
            ))
            .with_version(env!("CARGO_PKG_VERSION"))
            .with_schema_url(format!("https://opentelemetry.io/schemas/{}", $crate::OTEL_SPEC_VERSION))
            .build(),
          )
        });
    }
  };

  () => {
    paste::paste! {
      pub(crate) static TRACER: std::sync::LazyLock<opentelemetry::global::BoxedTracer> =
        std::sync::LazyLock::new(|| {
          use opentelemetry::trace::TracerProvider;

          opentelemetry::global::tracer_provider().tracer_with_scope(
            opentelemetry::InstrumentationScope::builder(concat!(
              env!("CARGO_PKG_NAME"),
            ))
            .with_version(env!("CARGO_PKG_VERSION"))
            .with_schema_url(format!("https://opentelemetry.io/schemas/{}", $crate::OTEL_SPEC_VERSION))
            .build(),
          )
        });
    }
  };
}

/// Creates an OpenTelemetry span for tracing execution.
///
/// This macro creates a span with automatic code location attributes and returns
/// both the span's [`Context`] and a [`ContextGuard`] that keeps the span active.
///
/// # Return Value
///
/// Returns `(Context, ContextGuard)`:
///
/// - **Context**: The OpenTelemetry context containing the active span. Clone this
///   to propagate through async boundaries or pass to child operations.
/// - **ContextGuard**: RAII guard that keeps the context attached to the current thread.
///   When dropped, the span ends and is exported.
///
/// **Important**: The span is only active while the guard is held. Dropping the guard
/// ends the span, so keep it in scope for the duration of the traced operation.
///
/// # Syntax Variants
///
/// | Syntax | Returns | Use Case |
/// |--------|---------|----------|
/// | `span!("name")` | `()` | Default tracer, creates internal guard |
/// | `span!("name", "k" = v, ...)` | `()` | With custom attributes, internal guard |
/// | `span!("name", in \|cx\| { ... })` | `T` | With closure (auto-managed lifetime) |
/// | `span!("name", "k" = v, in \|cx\| { ... })` | `T` | Closure + attributes |
/// | `span!(@TRACER, "name")` | `()` | Explicit tracer, internal guard |
/// | `span!(@TRACER, "name", "k" = v)` | `()` | Explicit tracer + attributes, internal guard |
/// | `span!(@TRACER, "name", in \|cx\| { ... })` | `T` | Explicit tracer with closure |
/// | `span!(@TRACER, "name", "k" = v, in \|cx\| { ... })` | `T` | Explicit tracer + attributes + closure |
/// | `span!(^ "name")` | `Context` | Detached span (no automatic guard) |
/// | `span!(^ "name", "k" = v)` | `Context` | Detached with attributes |
/// | `span!(^ @TRACER, "name")` | `Context` | Detached with explicit tracer |
///
/// # Automatic Attributes
///
/// All spans automatically include:
///
/// | Attribute | Description |
/// |-----------|-------------|
/// | `code.file.path` | Source file (workspace-relative via [`relative_filepath`]) |
/// | `code.line.number` | Line number where span was created |
/// | `code.column.number` | Column number |
/// | `thread.id` | Current thread ID |
/// | `thread.name` | Current thread name (or "unnamed") |
///
/// # Synchronous Usage
///
/// ## Pattern 1: Statement form (automatic guard management)
///
/// The simplest form creates an internal guard that manages span lifetime automatically:
///
/// ```ignore
/// fn process_item(item: &Item) {
///     otel::span!("item.process", "item.id" = item.id);
///
///     validate(item);
///     transform(item);
///     save(item);
///
///     // Span ends automatically at end of scope
/// }
/// ```
///
/// Nested spans automatically form parent-child relationships:
///
/// ```ignore
/// fn process_batch(items: &[Item]) {
///     otel::span!("batch.process", "count" = items.len() as i64);
///
///     for item in items {
///         // Automatically becomes a child of "batch.process"
///         otel::span!("item.process", "item.id" = item.id);
///         process_item(item);
///     }
/// }
/// ```
///
/// ## Pattern 2: Closure-based spans
///
/// Use `in` closure syntax for automatic span lifetime management:
///
/// ```ignore
/// use crate::TRACER;
///
/// fn process_item(item: &Item) -> Result<ProcessedItem> {
///     otel::span!("item.process", "item.id" = item.id, in |cx| {
///         validate(item)?;
///         let transformed = transform(item)?;
///         save(&transformed)?;
///         Ok(transformed)
///     })
/// }
/// ```
///
/// The closure receives the `Context` as a parameter and can return any value.
/// The span ends automatically when the closure completes or panics:
///
/// ```ignore
/// // Simple computation
/// let result = otel::span!("compute", in |cx| {
///     expensive_calculation()
/// });
///
/// // With attributes
/// let user = otel::span!("db.fetch", "user.id" = user_id, in |cx| {
///     db.get_user(user_id)
/// })?;
///
/// // Explicit tracer
/// let data = otel::span!(@CUSTOM_TRACER, "custom.operation", in |cx| {
///     do_work()
/// });
/// ```
///
/// # Asynchronous Usage
///
/// OpenTelemetry context is stored in thread-local storage. Since async tasks can
/// migrate between threads at `.await` points, you must explicitly propagate context
/// using [`FutureExt::with_context`].
///
/// ## Pattern 1: Closure form for single async operation
///
/// ```ignore
/// use opentelemetry::trace::FutureExt;
///
/// async fn fetch_user(id: u64) -> Result<User> {
///     otel::span!("user.fetch", "user.id" = id as i64, in |cx| {
///         db.get_user(id)
///             .with_context(cx)
///     }).await
/// }
/// ```
///
/// ## Pattern 2: Detached form for sequential awaits
///
/// Use the detached form (`@detached`) to get a context variable for multiple await points:
///
/// ```ignore
/// use opentelemetry::trace::FutureExt;
///
/// async fn process_order(order_id: u64) -> Result<()> {
///     let cx = otel::span!(^ "order.process", "order.id" = order_id as i64);
///
///     let order = fetch_order(order_id)
///         .with_context(cx.clone())
///         .await?;
///
///     validate_order(&order)
///         .with_context(cx.clone())
///         .await?;
///
///     submit_order(&order)
///         .with_context(cx)  // Last use, no clone needed
///         .await
/// }
/// ```
///
/// ## Pattern 3: Concurrent/spawned tasks
///
/// Use detached form and clone the context for each spawned task:
///
/// ```ignore
/// use opentelemetry::trace::FutureExt;
///
/// async fn fetch_all(ids: Vec<u64>) -> Vec<Result<Item>> {
///     let cx = otel::span!(^ "items.fetch_all", "count" = ids.len() as i64);
///
///     let futures: Vec<_> = ids
///         .into_iter()
///         .map(|id| {
///             let cx = cx.clone();
///             async move {
///                 fetch_item(id)
///                     .with_context(cx)
///                     .await
///             }
///         })
///         .collect();
///
///     futures::future::join_all(futures).await
/// }
/// ```
///
/// ## Pattern 4: Child spans in async blocks
///
/// Use detached form for parent span, then create child spans inside async blocks:
///
/// ```ignore
/// use opentelemetry::trace::FutureExt;
///
/// async fn pipeline() -> Result<()> {
///     let cx = otel::span!(^ "pipeline.run");
///
///     async {
///         otel::span!("pipeline.phase1");
///         do_phase1().await
///     }
///     .with_context(cx.clone())
///     .await?;
///
///     async {
///         otel::span!("pipeline.phase2");
///         do_phase2().await
///     }
///     .with_context(cx)
///     .await
/// }
/// ```
///
/// # Detached Spans
///
/// Use `@detached` to create a span that returns only the `Context`, without a guard:
///
/// ```ignore
/// let cx = otel::span!(^ "background.task", "priority" = "low");
/// ```
///
/// The span remains open until explicitly ended or the underlying span object is dropped.
/// Use detached spans when:
///
/// - Passing context to a spawned task that will manage its own lifetime
/// - You need manual control over context attachment
/// - The span lifetime doesn't match lexical scope
///
/// ```ignore
/// async fn spawn_background_work() {
///     let cx = otel::span!(^ "background.work");
///
///     tokio::spawn(async move {
///         // Attach context in the spawned task
///         let _guard = cx.attach();
///         do_background_work().await;
///         // Span ends when _guard drops here
///     });
/// }
/// ```
///
/// # Span Naming Conventions
///
/// Use dot-separated hierarchical names describing the component and operation:
///
/// ```text
/// component.operation          → scheduler.run, cache.get, db.connect
/// component.subcomponent.op    → lsp.request.send, http.client.fetch
/// noun.verb                    → file.read, user.authenticate, order.submit
/// ```
///
/// # Common Mistakes
///
/// ## Forgetting to propagate context in async code
///
/// ```ignore
/// // WRONG: Context lost at await point
/// async fn bad_example() {
///     otel::span!("operation");
///     do_work().await;  // Span may not be active here!
/// }
///
/// // CORRECT: Use closure form or detached form for async
/// async fn good_example() {
///     otel::span!("operation", in |cx| {
///         do_work().with_context(cx)
///     }).await;
/// }
///
/// // ALSO CORRECT: Detached form for multiple awaits
/// async fn also_good() {
///     let cx = otel::span!(^ "operation");
///     do_work().with_context(cx).await;
/// }
/// ```
///
/// ## Using statement form in expression position
///
/// ```ignore
/// // WRONG: Statement form returns (), not a value
/// fn bad_example() -> Result<Data> {
///     let result = otel::span!("operation");  // result = ()
///     get_data()
/// }
///
/// // CORRECT: Use closure form to return values
/// fn good_example() -> Result<Data> {
///     otel::span!("operation", in |cx| {
///         get_data()
///     })
/// }
/// ```
///
/// ## Moving context without cloning for concurrent use
///
/// ```ignore
/// // WRONG: cx moved into first iteration
/// async fn bad_example(ids: Vec<u64>) {
///     let cx = otel::span!(^ "fetch_all");
///     for id in ids {
///         tokio::spawn(fetch(id).with_context(cx));  // cx moved on first iteration!
///     }
/// }
///
/// // CORRECT: Clone context for each task
/// async fn good_example(ids: Vec<u64>) {
///     let cx = otel::span!(^ "fetch_all");
///     for id in ids {
///         let cx = cx.clone();
///         tokio::spawn(async move {
///             fetch(id).with_context(cx).await
///         });
///     }
/// }
/// ```
///
/// # Requirements
///
/// - For variants without `@tracer`: `TRACER` must be in scope (`use crate::TRACER;`)
/// - For `@tracer` variants: The named tracer must be in scope
/// - A tracer must have been declared with [`tracer!`]
#[macro_export]
macro_rules! span {
    // -------------------------------------------------------------------------
    // @build rules - 3 variants for context handling
    // -------------------------------------------------------------------------
    //
    // Keyword order: kind → context → links → attrs
    //
    // Note: We need 3 @build rules because $($ctx:tt)+ is greedy and would
    // consume tokens beyond the context expression. Using $ctx:expr is bounded.

    // @build with context = None (literal match, must come first)
    (@build $tracer:expr, $name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?) => {{
        use opentelemetry::trace::{Tracer as _, TraceContextExt};
        let thread = std::thread::current();
        let parent_cx = opentelemetry::Context::new();

        TraceContextExt::with_span(
            &parent_cx,
            $tracer
                .span_builder($name)
                $(.with_kind($kind))?
                $(.with_links(vec![$($link),*]))?
                .with_attributes([
                    opentelemetry::KeyValue::new("code.namespace", file!()),
                    opentelemetry::KeyValue::new("code.lineno", line!() as i64),
                    opentelemetry::KeyValue::new("code.column", column!() as i64),
                    opentelemetry::KeyValue::new("thread.name", format!("{}", thread.name().unwrap_or("unnamed"))),
                    $($(opentelemetry::KeyValue::new($key, $value)),+)?
                ])
                .start_with_context(&*$tracer, &parent_cx)
        )
    }};

    // @build with context = $ctx:expr (expression match)
    (@build $tracer:expr, $name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?) => {{
        use opentelemetry::trace::{Tracer as _, TraceContextExt};
        let thread = std::thread::current();
        let parent_cx = $ctx;

        TraceContextExt::with_span(
            &parent_cx,
            $tracer
                .span_builder($name)
                $(.with_kind($kind))?
                $(.with_links(vec![$($link),*]))?
                .with_attributes([
                    opentelemetry::KeyValue::new("code.namespace", file!()),
                    opentelemetry::KeyValue::new("code.lineno", line!() as i64),
                    opentelemetry::KeyValue::new("code.column", column!() as i64),
                    opentelemetry::KeyValue::new("thread.name", format!("{}", thread.name().unwrap_or("unnamed"))),
                    $($(opentelemetry::KeyValue::new($key, $value)),+)?
                ])
                .start_with_context(&*$tracer, &parent_cx)
        )
    }};

    // @build without context (uses current context)
    (@build $tracer:expr, $name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?) => {{
        use opentelemetry::trace::{Tracer as _, TraceContextExt};
        let thread = std::thread::current();
        let parent_cx = opentelemetry::Context::current();

        TraceContextExt::with_span(
            &parent_cx,
            $tracer
                .span_builder($name)
                $(.with_kind($kind))?
                $(.with_links(vec![$($link),*]))?
                .with_attributes([
                    opentelemetry::KeyValue::new("code.namespace", file!()),
                    opentelemetry::KeyValue::new("code.lineno", line!() as i64),
                    opentelemetry::KeyValue::new("code.column", column!() as i64),
                    opentelemetry::KeyValue::new("thread.name", format!("{}", thread.name().unwrap_or("unnamed"))),
                    $($(opentelemetry::KeyValue::new($key, $value)),+)?
                ])
                .start_with_context(&*$tracer, &parent_cx)
        )
    }};

    // -------------------------------------------------------------------------
    // CONSOLIDATED USER-FACING RULES
    // -------------------------------------------------------------------------
    //
    // Keyword order: kind → context → links → attrs
    //
    // Note: Closure forms need separate rules for context = None, context = $expr,
    // and no context, to avoid ambiguity between $($ctx:tt)+ and ", in |...|"
    // -------------------------------------------------------------------------

    // -------------------------------------------------------------------------
    // CLOSURE FORMS - with context = None (literal match, must come first)
    // -------------------------------------------------------------------------

    // Default TRACER with context = None
    ($name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // Explicit @TRACER with context = None
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // -------------------------------------------------------------------------
    // CLOSURE FORMS - with explicit context expression
    // -------------------------------------------------------------------------

    // Default TRACER with explicit context
    ($name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // Explicit @TRACER with explicit context
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // -------------------------------------------------------------------------
    // CLOSURE FORMS - without context (uses current)
    // -------------------------------------------------------------------------

    // Default TRACER without context
    ($name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // Explicit @TRACER without context
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        , in |$($cx_var:ident)? $(,$guard:ident)?| $body:expr) => {{
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _guard = cx.clone().attach();
        $(let $cx_var = cx.clone();)?
        $(let $guard = _guard;)?
        $body
    }};

    // -------------------------------------------------------------------------
    // DETACHED FORM - context = None (literal match, must come first)
    // -------------------------------------------------------------------------

    // Default TRACER with context = None
    (^ $name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // Explicit @TRACER with context = None
    (^ @$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // -------------------------------------------------------------------------
    // DETACHED FORM - context = $ctx:expr (expression match)
    // -------------------------------------------------------------------------

    // Default TRACER with explicit context
    (^ $name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // Explicit @TRACER with explicit context
    (^ @$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // -------------------------------------------------------------------------
    // DETACHED FORM - without context (uses current)
    // -------------------------------------------------------------------------

    // Default TRACER without context
    (^ $name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // Explicit @TRACER without context
    (^ @$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?)
    };

    // -------------------------------------------------------------------------
    // STATEMENT FORM - context = None (literal match, must come first)
    // -------------------------------------------------------------------------

    // Default TRACER with context = None
    ($name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };

    // Explicit @TRACER with context = None
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = None
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = None
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };

    // =-------------------------------------------------------------------------    // STATEMENT FORM - context = $ctx:expr (expression match)
    // -------------------------------------------------------------------------

    // Default TRACER with explicit context
    ($name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };

    // Explicit @TRACER with explicit context
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        , context = $ctx:expr
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            , context = $ctx
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };

    // -------------------------------------------------------------------------
    // STATEMENT FORM - without context (uses current)
    // -------------------------------------------------------------------------

    // Default TRACER without context
    ($name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build TRACER, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };

    // Explicit @TRACER without context
    (@$tracer:ident, $name:expr
        $(, kind = $kind:expr)?
        $(, links = [$($link:expr),* $(,)?])?
        $(, $($key:literal = $value:expr),+)?
        $(,)?) => {
        let cx = $crate::span!(@build $tracer, $name
            $(, kind = $kind)?
            $(, links = [$($link),*])?
            $(, $($key = $value),+)?);
        let _otel_guard = cx.clone().attach();
    };
}

/// Records an exception event on the current span and returns an error value.
///
/// This macro adds an exception event to the current OpenTelemetry span following
/// the semantic conventions, then evaluates to the provided error value.
///
/// # Syntax
///
/// ```ignore
/// // In closures (ok_or_else, map_err, etc.)
/// .ok_or_else(|| otel::exception!("invalid_params", Error::new("msg")))?
///
/// // In function bodies with explicit return
/// return Err(otel::exception!("invalid_params", Error::new("msg")));
///
/// // With additional attributes
/// otel::exception!("source_not_found", error, "uri" => uri.to_string())
/// ```
///
/// # Parameters
///
/// - `exception_type`: String literal for the exception.type attribute
/// - `error_value`: The error value to return (must implement Display for exception.message)
/// - Additional key-value pairs: Optional extra attributes to add to the exception event
///
/// # Examples
///
/// ```ignore
/// // In ok_or_else closure
/// let arg = arguments.first().ok_or_else(|| {
///     otel::exception!("invalid_params",
///         jsonrpc::Error::invalid_params("Missing arguments"))
/// })?;
///
/// // In map_err closure
/// let uri = Uri::parse(uri_str).map_err(|e| {
///     otel::exception!("invalid_uri",
///         jsonrpc::Error::invalid_params(format!("Invalid URI: {}", e)),
///         "uri_str" => uri_str.to_string()
///     )
/// })?;
///
/// // Direct return
/// if cache.is_empty() {
///     return Err(otel::exception!("cache_empty",
///         jsonrpc::Error::internal_error("Cache is empty"),
///         "operation" => "lookup"
///     ));
/// }
/// ```
///
/// # OpenTelemetry Semantic Conventions
///
/// The macro follows the [OpenTelemetry semantic conventions for exceptions](https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/):
///
/// - Event name: `"exception"`
/// - Required attributes:
///   - `exception.type`: The type/category of the exception
///   - `exception.message`: The error message extracted via Display
/// - Additional attributes: Any extra key-value pairs provided
#[macro_export]
macro_rules! exception {
    ($exception_type:expr, $error:expr $(, $key:literal = $value:expr)* $(,)?) => {{
        use opentelemetry::trace::TraceContextExt as _;
        let error_value = $error;
        let error_message = format!("{}", error_value);

        opentelemetry::Context::current().span().add_event(
            "exception",
            vec![
                opentelemetry::KeyValue::new("exception.type", $exception_type),
                opentelemetry::KeyValue::new("exception.message", error_message),
                $(opentelemetry::KeyValue::new($key, $value)),*
            ],
        );

        error_value
    }};
}

/// Records an error event on the current span and returns an error value.
///
/// This macro adds an error event to the current OpenTelemetry span following
/// the semantic conventions, then evaluates to the provided error value.
///
/// # Syntax
///
/// ```ignore
/// // In closures (ok_or_else, map_err, etc.)
/// .ok_or_else(|| otel::error!("timeout", Error::new("msg")))?
///
/// // In function bodies with explicit return
/// return Err(otel::error!("validation_failed", Error::new("msg")));
///
/// // With additional attributes
/// otel::error!("database_unavailable", error, "retry_count" = 3)
/// ```
///
/// # Parameters
///
/// - `error_type`: String literal for the error.type attribute
/// - `error_value`: The error value to return (must implement Display for error.message)
/// - Additional key-value pairs: Optional extra attributes to add to the error event
///
/// # Examples
///
/// ```ignore
/// // In ok_or_else closure
/// let config = load_config().ok_or_else(|| {
///     otel::error!("config_not_found",
///         jsonrpc::Error::internal_error("Configuration file not found"))
/// })?;
///
/// // In map_err closure
/// let connection = establish_connection().map_err(|e| {
///     otel::error!("connection_failed",
///         jsonrpc::Error::internal_error(format!("Failed to connect: {}", e)),
///         "host" = host.to_string(),
///         "port" = port as i64
///     )
/// })?;
///
/// // Direct return
/// if !is_valid {
///     return Err(otel::error!("invalid_state",
///         jsonrpc::Error::internal_error("System is in an invalid state"),
///         "state" = current_state
///     ));
/// }
/// ```
///
/// # OpenTelemetry Semantic Conventions
///
/// The macro follows the [OpenTelemetry semantic conventions for errors](https://opentelemetry.io/docs/specs/semconv/attributes-registry/error/):
///
/// - Event name: `"error"`
/// - Required attributes:
///   - `error.type`: Describes the class of error the operation ended with
///   - `error.message`: A human-readable message providing more detail about the error
/// - Additional attributes: Any extra key-value pairs provided
///
/// # Difference from `exception!`
///
/// While both macros record error-related events, they follow different semantic conventions:
///
/// - `error!`: For general error conditions (uses `error.type` and `error.message`)
/// - `exception!`: For programming exceptions with stack traces (uses `exception.type` and `exception.message`)
///
/// Use `error!` for application-level errors and `exception!` for exception handling.
#[macro_export]
macro_rules! error {
    ($error_type:expr, $error:expr $(, $key:literal = $value:expr)* $(,)?) => {{
        use opentelemetry::trace::TraceContextExt as _;
        let error_value = $error;
        let error_message = format!("{}", error_value);

        opentelemetry::Context::current().span().add_event(
            "error",
            vec![
                opentelemetry::KeyValue::new("error.type", $error_type),
                opentelemetry::KeyValue::new("error.message", error_message),
                $(opentelemetry::KeyValue::new($key, $value)),*
            ],
        );

        error_value
    }};
}

/// Adds an event to the current span with optional attributes.
///
/// # Examples
///
/// ```ignore
/// // Simple event
/// otel::event!("query.start");
///
/// // Event with attributes
/// otel::event!("query.result",
///   "record_count" = 42,
///   "partition_key" = "users"
/// );
/// ```
#[macro_export]
macro_rules! event {
    ($event_name:expr $(, $key:literal = $value:expr)* $(,)?) => {{
        #[allow(unused)]
        use opentelemetry::trace::TraceContextExt as _;
        opentelemetry::Context::current().span().add_event(
            $event_name,
            vec![
                $(opentelemetry::KeyValue::new($key, $value)),*
            ],
        );
    }};
}

/// Creates a span [`Link`](opentelemetry::trace::Link) from a context for use with `span!` macro's `links` parameter.
///
/// Links are used to associate spans across trace boundaries when there's a causal
/// relationship but not a parent-child relationship. Common use cases include:
///
/// - Background tasks spawned from a request (linked to spawning context)
/// - Batch processing where one span triggers multiple independent operations
/// - Fan-out/fan-in patterns
///
/// # Syntax
///
/// ```ignore
/// // Link from current context
/// let link = otel::link!();
///
/// // Link from explicit context
/// let link = otel::link!(parent_cx);
///
/// // Link with attributes
/// let link = otel::link!(parent_cx, "link.type" = "spawned_from");
/// ```
///
/// # Examples
///
/// ## Background task with link to spawner
///
/// ```ignore
/// fn spawn_background_task(data: Data) {
///     // Capture link BEFORE spawning (while still in parent context)
///     let parent_link = otel::link!("link.type" = "spawned_from");
///
///     tokio::spawn(async move {
///         // New root trace, linked back to spawner
///         otel::span!("background.task", context = None, links = [parent_link], in |_cx| {
///             process(data).await
///         })
///     });
/// }
/// ```
///
/// ## Explicit context with attributes
///
/// ```ignore
/// fn process_batch(items: Vec<Item>, trigger_cx: Context) {
///     let trigger_link = otel::link!(trigger_cx, "link.type" = "batch_trigger");
///
///     for item in items {
///         // Each item gets its own trace, linked to the batch trigger
///         otel::span!("item.process", context = None, links = [trigger_link.clone()], in |_cx| {
///             process_item(item)
///         });
///     }
/// }
/// ```
///
/// # OpenTelemetry Semantic Conventions
///
/// Links follow the [OpenTelemetry link specification](https://opentelemetry.io/docs/concepts/signals/traces/#span-links).
/// The `link.type` attribute is commonly used to describe the relationship.
#[macro_export]
macro_rules! link {
    // Link from current context (no attributes)
    () => {{
        use opentelemetry::trace::TraceContextExt as _;
        let cx = opentelemetry::Context::current();
        opentelemetry::trace::Link::new(cx.span().span_context().clone(), vec![], 0)
    }};

    // Link from current context with attributes
    ($($key:literal = $value:expr),+ $(,)?) => {{
        use opentelemetry::trace::TraceContextExt as _;
        let cx = opentelemetry::Context::current();
        opentelemetry::trace::Link::new(
            cx.span().span_context().clone(),
            vec![$(opentelemetry::KeyValue::new($key, $value)),+],
            0
        )
    }};

    // Link from explicit context (no attributes)
    ($cx:expr) => {{
        use opentelemetry::trace::TraceContextExt as _;
        opentelemetry::trace::Link::new($cx.span().span_context().clone(), vec![], 0)
    }};

    // Link from explicit context with attributes
    ($cx:expr, $($key:literal = $value:expr),+ $(,)?) => {{
        use opentelemetry::trace::TraceContextExt as _;
        opentelemetry::trace::Link::new(
            $cx.span().span_context().clone(),
            vec![$(opentelemetry::KeyValue::new($key, $value)),+],
            0
        )
    }};
}

#[cfg(test)]
mod tests;