AITrace.Context (AITrace v0.2.0)

Copy Markdown View Source

An immutable context that carries trace and span identifiers through the call stack.

The Context is the core mechanism for correlating telemetry data. It contains:

  • trace_id: A unique identifier for the entire trace/transaction
  • span_id: The current span within the trace (nil if not in a span)
  • export_profile: Export sinks captured when the trace context is created
  • runtime_identity: Runtime identity captured when the context is created
  • governed-effect refs: effect, command, authority, and receipt refs carried explicitly
  • metadata: Additional key-value metadata for the trace

Summary

Types

t()

Functions

export_metadata(ctx)

Returns trace metadata derived from the explicit context.

generate_id()
get_metadata(ctx, key, default \\ nil)

Retrieves a metadata value by key.

governed_effect_refs(ctx)

Returns the governed-effect refs carried by a context.

new()

Creates a new context with a generated trace_id.

new(trace_id)

Creates a new context with the provided trace_id.

with_export_profile(ctx, export_profile)

Returns a new context with the export profile captured for trace finish.

with_governed_effect_refs(ctx, attrs)

Returns a new context with governed-effect refs carried as explicit fields.

with_metadata(ctx, metadata)

Returns a new context with merged metadata.

with_span_id(ctx, span_id)

Returns a new context with the updated span_id.

Types

t()

@type t() :: %AITrace.Context{
  authority_ref: String.t() | nil,
  command_ref: String.t() | nil,
  effect_ref: String.t() | nil,
  export_profile: AITrace.ExportProfile.t() | nil,
  metadata: map(),
  receipt_ref: String.t() | nil,
  runtime_identity: AITrace.RuntimeIdentity.snapshot(),
  span_id: String.t() | nil,
  trace_id: String.t(),
  trace_id_source: map()
}

Functions

export_metadata(ctx)

@spec export_metadata(t()) :: map()

Returns trace metadata derived from the explicit context.

generate_id()

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

get_metadata(ctx, key, default \\ nil)

@spec get_metadata(t(), atom(), any()) :: any()

Retrieves a metadata value by key.

Examples

iex> ctx = AITrace.Context.new() |> AITrace.Context.with_metadata(%{user_id: 42})
iex> AITrace.Context.get_metadata(ctx, :user_id)
42
iex> AITrace.Context.get_metadata(ctx, :missing, :default)
:default

governed_effect_refs(ctx)

@spec governed_effect_refs(t()) :: map()

Returns the governed-effect refs carried by a context.

new()

@spec new() :: t()

Creates a new context with a generated trace_id.

Examples

iex> ctx = AITrace.Context.new()
iex> is_binary(ctx.trace_id)
true
iex> ctx.span_id
nil

new(trace_id)

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

Creates a new context with the provided trace_id.

Examples

iex> ctx = AITrace.Context.new("my_trace_123")
iex> ctx.trace_id
"my_trace_123"

with_export_profile(ctx, export_profile)

@spec with_export_profile(t(), AITrace.ExportProfile.t()) :: t()

Returns a new context with the export profile captured for trace finish.

with_governed_effect_refs(ctx, attrs)

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

Returns a new context with governed-effect refs carried as explicit fields.

with_metadata(ctx, metadata)

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

Returns a new context with merged metadata.

Examples

iex> ctx = AITrace.Context.new()
iex> new_ctx = AITrace.Context.with_metadata(ctx, %{user_id: 42})
iex> new_ctx.metadata
%{user_id: 42}

with_span_id(ctx, span_id)

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

Returns a new context with the updated span_id.

Examples

iex> ctx = AITrace.Context.new()
iex> new_ctx = AITrace.Context.with_span_id(ctx, "span_123")
iex> new_ctx.span_id
"span_123"