class Logit::Span

• Logit::Span
• Reference
• Object

Overview

Represents a traced operation with timing, attributes, and trace context.

Spans are the core building block of Logit's tracing system. Each instrumented method call creates a span that tracks:

• Start and end times (for duration calculation)
• Trace and span IDs (for distributed tracing)
• Parent span ID (for call hierarchy)
• Custom attributes (for structured data)
• Exception information (if an error occurred)

Spans are stored in a fiber-local stack, allowing safe concurrent tracing across multiple fibers without interference.

Accessing the Current Span

Inside an instrumented method, you can access the current span to add custom attributes:

class OrderService
  @[Logit::Log]
  def process_order(order_id : Int32) : Bool
    # Add custom attributes to the current span
    if span = Logit::Span.current?
      span.attributes.set("order.priority", "high")
      span.attributes.set("order.items_count", 5_i64)
    end

    # ... process the order
    true
  end
end

Trace Context

Nested method calls automatically share the same trace ID and form a parent-child relationship through span IDs:

class PaymentService
  @[Logit::Log]
  def charge(amount : Float64) : Bool
    validate_amount(amount)  # Child span, same trace_id
    process_payment(amount)  # Child span, same trace_id
    true
  end

  @[Logit::Log]
  def validate_amount(amount : Float64) : Bool
    amount > 0
  end

  @[Logit::Log]
  def process_payment(amount : Float64) : Bool
    # ...
    true
  end
end

Defined in:

Constructors

• .current : Span

  Returns the current span for this fiber.

• .new(name : String, span_id : String = Utils::IDGenerator.span_id, parent_span_id : Nil | String = nil)

  Creates a new span with the given name.

Class Method Summary

• .current? : Span | Nil

  Returns the current span for this fiber, or nil if none is active.

• .pop(fiber_stack : Array(Span)) : Span | Nil

  Optimized version that takes the span stack directly to avoid repeated Fiber.current access.

• .pop : Span | Nil

  Pops the current span from the fiber-local span stack.

• .push(span : Span, fiber_stack : Array(Span)) : Nil

  Optimized version that takes the span stack directly to avoid repeated Fiber.current access.

• .push(span : Span) : Nil

  Pushes a span onto the fiber-local span stack.

Instance Method Summary

• #add_event(name : String, **attributes) : Nil

  Adds a span event (intermediate log within a span).

• #attributes : Event::Attributes

  Structured attributes attached to this span.

• #attributes=(attributes : Event::Attributes)

  Structured attributes attached to this span.

• #end_time : Time | Nil

  When this span ended (set when the span completes).

• #end_time=(end_time : Time | Nil)

  When this span ended (set when the span completes).

• #events : Array(SpanEvent)

  Span events that occurred during this span's lifetime.

• #exception : ExceptionInfo | Nil

  Exception information if an error occurred during this span.

• #exception=(exception : ExceptionInfo | Nil)

  Exception information if an error occurred during this span.

• #name : String

  Name of this span (typically the method name).

• #name=(name : String)

  Name of this span (typically the method name).

• #parent_span_id : String | Nil

  Span ID of the parent span, or nil if this is a root span.

• #parent_span_id=(parent_span_id : String | Nil)

  Span ID of the parent span, or nil if this is a root span.

• #span_id : String

  Unique identifier for this span (64-bit hex string).

• #span_id=(span_id : String)

  Unique identifier for this span (64-bit hex string).

• #start_time : Time

  When this span started.

• #start_time=(start_time : Time)

  When this span started.

• #to_event(trace_id : String, level : LogLevel, code_file : String, code_line : Int32, method_name : String, class_name : String) : Event

  Converts this span to an Event for logging.

• #trace_id : String

  W3C trace ID (128-bit hex string) shared across all spans in a trace.

• #trace_id=(trace_id : String)

  W3C trace ID (128-bit hex string) shared across all spans in a trace.

Constructor Detail

Class Method Detail

if span = Logit::Span.current?
  span.attributes.set("custom.field", "value")
end

Instance Method Detail

@[Logit::Log]
def process_large_file(path : String) : Result
  span = Logit::Span.current

  span.add_event("file.opened", path: path)

  results = process_chunks(path)

  span.add_event("file.processed",
    path: path,
    chunks: results.size
  )

  results
end