AITrace.Trace (AITrace v0.2.0)

Copy Markdown View Source

A Trace represents the complete record of a single transaction.

A trace contains:

  • A unique trace_id
  • A collection of all spans that occurred during the transaction
  • Metadata about the trace itself
  • Creation timestamp

Summary

Types

t()

Functions

add_span(trace, span)

Adds a span to the trace.

get_children(trace, parent_span_id)

Returns all child spans of a given parent span_id.

get_root_spans(trace)

Returns all root spans (spans with no parent).

get_span(trace, span_id)

Retrieves a span by its span_id.

mark_replay_addressable(trace, replay_addressable?)

Marks whether the trace can be replayed from exported refs.

new(trace_id, opts \\ [])

Creates a new trace with the given trace_id.

replay_addressable?(trace)

Returns true when the trace carries replay-addressable export posture.

with_metadata(trace, metadata)

Adds or merges metadata into the trace.

with_persistence_posture(trace, attrs)

Sets the capture/persistence posture for the trace.

Types

t()

@type t() :: %AITrace.Trace{
  clock_domain: map(),
  created_at: integer(),
  created_at_wall_time: DateTime.t(),
  metadata: map(),
  persistence_posture: AITrace.PersistencePosture.t(),
  replay_addressable?: boolean(),
  spans: [AITrace.Span.t()],
  trace_id: String.t(),
  trace_id_source: map()
}

Functions

add_span(trace, span)

@spec add_span(t(), AITrace.Span.t()) :: t()

Adds a span to the trace.

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> span = AITrace.Span.new("operation")
iex> trace = AITrace.Trace.add_span(trace, span)
iex> length(trace.spans)
1

get_children(trace, parent_span_id)

@spec get_children(t(), String.t()) :: [AITrace.Span.t()]

Returns all child spans of a given parent span_id.

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> root = AITrace.Span.new("root")
iex> child = AITrace.Span.new("child", root.span_id)
iex> trace = trace |> AITrace.Trace.add_span(root) |> AITrace.Trace.add_span(child)
iex> children = AITrace.Trace.get_children(trace, root.span_id)
iex> length(children)
1

get_root_spans(trace)

@spec get_root_spans(t()) :: [AITrace.Span.t()]

Returns all root spans (spans with no parent).

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> root = AITrace.Span.new("root")
iex> trace = AITrace.Trace.add_span(trace, root)
iex> roots = AITrace.Trace.get_root_spans(trace)
iex> length(roots)
1

get_span(trace, span_id)

@spec get_span(t(), String.t()) :: AITrace.Span.t() | nil

Retrieves a span by its span_id.

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> span = AITrace.Span.new("operation")
iex> trace = AITrace.Trace.add_span(trace, span)
iex> retrieved = AITrace.Trace.get_span(trace, span.span_id)
iex> retrieved == span
true

mark_replay_addressable(trace, replay_addressable?)

@spec mark_replay_addressable(t(), boolean()) :: t()

Marks whether the trace can be replayed from exported refs.

new(trace_id, opts \\ [])

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

Creates a new trace with the given trace_id.

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> trace.trace_id
"trace_123"
iex> trace.spans
[]

replay_addressable?(trace)

@spec replay_addressable?(t()) :: boolean()

Returns true when the trace carries replay-addressable export posture.

with_metadata(trace, metadata)

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

Adds or merges metadata into the trace.

Examples

iex> trace = AITrace.Trace.new("trace_123")
iex> trace = AITrace.Trace.with_metadata(trace, %{user_id: 42})
iex> trace.metadata
%{user_id: 42}

with_persistence_posture(trace, attrs)

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

Sets the capture/persistence posture for the trace.