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!(@detached, "name")` | `Context` | Detached span (no automatic guard) |
/// | `span!(@detached, "name", "k" => v)` | `Context` | Detached with attributes |
/// | `span!(@detached, @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!(@detached, "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!(@detached, "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!(@detached, "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!(@detached, "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!(@detached, "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!(@detached, "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!(@detached, "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!(@detached, "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 {

  (@maybe_cx $cx:ident, $tracer:ident, $name:expr $(, $($key:expr => $value:expr),+)?) => {
    let $cx = $crate::span!(@build $tracer, $name $(, $($key => $value),+)?);
  };
  (@maybe_cx $tracer:ident, $name:expr $(, $($key:expr => $value:expr),+)?) => {
    let _cx = $crate::span!(@build $tracer, $name $(, $($key => $value),+)?);
  };

  (@maybe_guard $cx:ident, $guard:ident) => {
    let $guard = $cx.clone().attach();
  };
  (@maybe_guard $cx:ident,) => {};
  (@maybe_guard $cx:ident) => {};
  (@maybe_guard) => {};


    // Internal: build span context with automatic attributes and optional custom attributes
    (@build $tracer:expr, $name:expr $(, $($key:expr => $value:expr),+)?) => {{
        use opentelemetry::trace::{Tracer as _, TraceContextExt as _};
        let thread = std::thread::current();

        opentelemetry::Context::current_with_span(
            $tracer
                .span_builder($name)
                .with_attributes([
                  opentelemetry::KeyValue::new("code.namespace", file!()),
                  opentelemetry::KeyValue::new("code.lineno", line!() as i64),
                  opentelemetry::KeyValue::new("code.column", column!() as i64),

                    // waiting on (feature = "thread_id_value", issue = "67939")
                    // opentelemetry::KeyValue::new("thread.id", std::thread::current().id()),
                    opentelemetry::KeyValue::new("thread.name", format!("{}",thread.name().unwrap_or("unnamed"))),

                    $($(opentelemetry::KeyValue::new($key, $value)),+)?
                ])
                .start_with_context(&*$tracer, &opentelemetry::Context::current())
        )
    }};

    // Default TRACER, no attributes, with closure
    ($name:expr, in |$($cx:ident)? $(,$guard:ident)?| $body:expr) => {{
        $crate::span!(@maybe_cx $($cx,)? TRACER, $name);
        $crate::span!(@maybe_guard $($cx,)? $($guard)?);

        $body
    }};

    // Default TRACER with attributes and closure
    ($name:expr, $($key:expr => $value:expr),+, in |$($cx:ident)? $(,$guard:ident)?| $body:expr) => {{
        $crate::span!(@maybe_cx $($cx,)? TRACER, $name , $($key => $value),+);
        $crate::span!(@maybe_guard $($cx,)? $($guard)?);
        $body
    }};

    // Explicit tracer, no attributes, with closure
    (@$tracer:ident, $name:expr, in |$($cx:ident)? $(,$guard:ident)?| $body:expr) => {{
      $crate::span!(@maybe_cx $($cx,)? $tracer, $name);
      $crate::span!(@maybe_guard $($cx,)? $($guard)?);
        $body
    }};

    // Explicit tracer with attributes and closure
    (@$tracer:ident, $name:expr, $($key:expr => $value:expr),+, in |$($cx:ident)? $(,$guard:ident)?| $body:expr) => {{
        $crate::span!(@maybe_cx $($cx,)? $tracer, $name , $($key => $value),+);
        $crate::span!(@maybe_guard $($cx,)? $($guard)?);

        $body
    }};

    // Default TRACER, no attributes (statement form with internal guard)
    ($name:expr $(,)?) => {{
        let cx = $crate::span!(@build TRACER, $name);
        let _otel_guard = cx.clone().attach();
    }};

    // Default TRACER with attributes (statement form with internal guard)
    ($name:expr, $($key:expr => $value:expr),+ $(,)?) => {{
        let cx = $crate::span!(@build TRACER, $name, $($key => $value),+);
        let _otel_guard = cx.clone().attach();
    }};

    // Explicit tracer, no attributes (statement form with internal guard)
    (@$tracer:ident, $name:expr $(,)?) => {{
        let cx = $crate::span!(@build $tracer, $name);
        let _otel_guard = cx.clone().attach();
    }};

    // Explicit tracer with attributes (statement form with internal guard)
    (@$tracer:ident, $name:expr, $($key:expr => $value:expr),+ $(,)?) => {{
        let cx = $crate::span!(@build $tracer, $name, $($key => $value),+);
        let _otel_guard = cx.clone().attach();
    }};

    // Detached span (no guard) - default TRACER, no attributes
    (@detached, $name:expr $(,)?) => {
        $crate::span!(@build TRACER, $name)
    };

    // Detached span (no guard) - default TRACER with attributes
    (@detached, $name:expr, $($key:expr => $value:expr),+ $(,)?) => {
        $crate::span!(@build TRACER, $name, $($key => $value),+)
    };

    // Detached span (no guard) - explicit tracer, no attributes
    (@detached, @$tracer:ident, $name:expr $(,)?) => {
        $crate::span!(@build $tracer, $name)
    };

    // Detached span (no guard) - explicit tracer with attributes
    (@detached, @$tracer:ident, $name:expr, $($key:expr => $value:expr),+ $(,)?) => {
        $crate::span!(@build $tracer, $name, $($key => $value),+)
    };
}

/// 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:expr => $value:expr)* $(,)?) => {{
        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
    }};
}

/// 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:expr => $value:expr)* $(,)?) => {
        opentelemetry::Context::current().span().add_event(
            $event_name,
            vec![
                $(opentelemetry::KeyValue::new($key, $value)),*
            ],
        );
    };
}

#[cfg(test)]
mod tests {
  use super::*;

  tracer!();

  #[test]
  fn span_with_closure_returns_value() {
    let result = span!("test.closure", in |_cx| {
        42
    });
    assert_eq!(result, 42);
  }

  #[test]
  fn span_with_closure_and_attributes() {
    let result = span!("test.closure_attrs", "foo" => "bar", in |_cx| {
        "hello"
    });
    assert_eq!(result, "hello");
  }

  #[test]
  fn span_with_closure_explicit_tracer() {
    let result = span!(@TRACER, "test.explicit", in |_cx| {
        100
    });
    assert_eq!(result, 100);
  }

  #[test]
  fn span_with_closure_explicit_tracer_and_attributes() {
    let result = span!(@TRACER, "test.explicit_attrs", "key" => "value", in |_cx| {
        vec![1, 2, 3]
    });
    assert_eq!(result, vec![1, 2, 3]);
  }
}