AITrace.Span (AITrace v0.2.0)

Copy Markdown View Source

A Span represents a timed operation within a trace.

Spans form a tree structure through parent-child relationships and contain:

  • Timing information (start_time, end_time)
  • Hierarchical information (span_id, parent_span_id)
  • Metadata (attributes)
  • Point-in-time events
  • Status (ok, error)

Summary

Types

status()
t()

Functions

add_event(span, event)

Adds an event to the span.

duration(span)

Returns the duration of the span in microseconds. Returns nil if the span has not been finished.

finish(span)

Marks the span as finished by setting its end_time.

generate_id()
new(name)

Creates a new span with the given name.

new(name, parent_span_id)

Creates a new span with the given name and parent span ID.

with_attributes(span, attributes)

Adds or merges attributes into the span.

with_persistence_posture(span, attrs)

Sets the capture/persistence posture for the span.

with_status(span, status)

Sets the status of the span.

Types

status()

@type status() :: :ok | :error

t()

@type t() :: %AITrace.Span{
  attributes: map(),
  clock_domain: map(),
  end_time: integer() | nil,
  end_wall_time: DateTime.t() | nil,
  events: [AITrace.Event.t()],
  name: String.t(),
  parent_span_id: String.t() | nil,
  parent_span_id_source: map() | nil,
  persistence_posture: AITrace.PersistencePosture.t(),
  span_id: String.t(),
  span_id_source: map(),
  start_time: integer(),
  start_wall_time: DateTime.t(),
  status: status()
}

Functions

add_event(span, event)

@spec add_event(t(), AITrace.Event.t()) :: t()

Adds an event to the span.

Examples

iex> span = AITrace.Span.new("operation")
iex> event = %AITrace.Event{name: "cache_hit", timestamp: System.monotonic_time(:microsecond)}
iex> span = AITrace.Span.add_event(span, event)
iex> length(span.events)
1

duration(span)

@spec duration(t()) :: integer() | nil

Returns the duration of the span in microseconds. Returns nil if the span has not been finished.

Examples

iex> span = AITrace.Span.new("operation") |> AITrace.Span.finish()
iex> is_integer(AITrace.Span.duration(span))
true

finish(span)

@spec finish(t()) :: t()

Marks the span as finished by setting its end_time.

Examples

iex> span = AITrace.Span.new("operation")
iex> finished = AITrace.Span.finish(span)
iex> is_integer(finished.end_time)
true

generate_id()

@spec generate_id() :: String.t()

new(name)

@spec new(String.t()) :: t()

Creates a new span with the given name.

Examples

iex> span = AITrace.Span.new("llm_call")
iex> is_binary(span.span_id)
true
iex> span.name
"llm_call"

new(name, parent_span_id)

@spec new(String.t(), String.t()) :: t()

Creates a new span with the given name and parent span ID.

Examples

iex> span = AITrace.Span.new("child_operation", "parent_123")
iex> span.parent_span_id
"parent_123"

with_attributes(span, attributes)

@spec with_attributes(t(), map()) :: t()

Adds or merges attributes into the span.

Examples

iex> span = AITrace.Span.new("operation")
iex> span = AITrace.Span.with_attributes(span, %{user_id: 42})
iex> span.attributes
%{user_id: 42}

with_persistence_posture(span, attrs)

@spec with_persistence_posture(t(), map() | keyword()) :: t()

Sets the capture/persistence posture for the span.

with_status(span, status)

@spec with_status(t(), status()) :: t()

Sets the status of the span.

Examples

iex> span = AITrace.Span.new("operation")
iex> span = AITrace.Span.with_status(span, :error)
iex> span.status
:error