Jido.Signal.Trace.Context (Jido Signal v2.2.1)

View Source

Trace context struct for distributed tracing.

Represents W3C Trace Context compatible trace information that can be propagated across signal boundaries.

Fields

  • trace_id - 32 hex chars (128-bit) shared across entire workflow
  • span_id - 16 hex chars (64-bit) unique to this signal
  • parent_span_id - Parent's span_id for hierarchy linkage (optional)
  • causation_id - ID of the signal that caused this one (optional)
  • tracestate - W3C tracestate for vendor-specific data (optional)

W3C Trace Context Compatibility

IDs are generated in W3C-compatible format:

  • trace_id: 32 hex chars (128-bit)
  • span_id: 16 hex chars (64-bit)

Examples

# Create a new root context
{:ok, ctx} = Context.new()

# Create with causation
{:ok, ctx} = Context.new(causation_id: "external-123")

# Create a child context
{:ok, child} = Context.child_of(parent_ctx, "parent-signal-id")

Summary

Types

t()

Functions

child_from_traceparent(traceparent, opts \\ [])

Parses a W3C traceparent header and creates a child context.

child_of(parent, causation_id)

Creates a child trace context that continues the parent's trace.

child_of!(parent, causation_id)

Creates a child trace context, raising on error.

from_map(map)

Creates a context from a map.

from_map!(map)

Creates a context from a map, raising on error.

from_traceparent(traceparent)

Parses a W3C traceparent header into trace context.

new(opts \\ [])

Creates a new root trace context.

new!(opts \\ [])

Creates a new root trace context, raising on error.

schema()

Returns the Zoi schema for Context

to_map(ctx)

Converts the context to a map, filtering out nil values.

to_telemetry_metadata(ctx)

Converts context to telemetry metadata with jido_ prefixed keys.

to_traceparent(context)

Formats trace context as W3C traceparent header value.

valid?(arg1)

Checks if a trace context is valid.

Types

t()

@type t() :: %Jido.Signal.Trace.Context{
  causation_id: nil | nil | binary(),
  parent_span_id: nil | nil | binary(),
  span_id: binary(),
  trace_id: binary(),
  tracestate: nil | nil | binary()
}

Functions

child_from_traceparent(traceparent, opts \\ [])

@spec child_from_traceparent(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, :invalid_traceparent}

Parses a W3C traceparent header and creates a child context.

This is useful when receiving an external request with trace headers and you want to create a new span as a child of that trace.

Options

  • :causation_id - Optional causation ID for the child span
  • :tracestate - Optional tracestate to associate with the child

Examples

{:ok, child} = Context.child_from_traceparent(
  "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  causation_id: "http-request-123"
)

child_of(parent, causation_id)

@spec child_of(t(), String.t() | nil) :: {:ok, t()}

Creates a child trace context that continues the parent's trace.

The child:

  • Shares the parent's trace_id
  • Gets a new unique span_id
  • Sets parent_span_id to the parent's span_id
  • Sets causation_id to the causing signal's ID
  • Inherits tracestate

Examples

{:ok, child} = Context.child_of(parent_ctx, parent_signal.id)

child_of!(parent, causation_id)

@spec child_of!(t() | nil, String.t() | nil) :: t()

Creates a child trace context, raising on error.

Examples

child = Context.child_of!(parent_ctx, "signal-id")

from_map(map)

@spec from_map(map()) :: {:ok, t()} | {:error, term()}

Creates a context from a map.

Examples

{:ok, ctx} = Context.from_map(%{trace_id: "abc...", span_id: "def..."})

from_map!(map)

@spec from_map!(map()) :: t()

Creates a context from a map, raising on error.

Examples

ctx = Context.from_map!(%{trace_id: "abc...", span_id: "def..."})

from_traceparent(traceparent)

@spec from_traceparent(String.t()) :: {:ok, t()} | {:error, :invalid_traceparent}

Parses a W3C traceparent header into trace context.

Returns {:ok, context} on success, {:error, reason} on failure.

Examples

{:ok, ctx} = Context.from_traceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")

new(opts \\ [])

@spec new(keyword()) :: {:ok, t()}

Creates a new root trace context.

Generates new W3C-compatible trace_id (32 hex chars) and span_id (16 hex chars).

Options

  • :causation_id - Optional causation reference (e.g., external request ID)
  • :tracestate - Optional W3C tracestate string for vendor-specific data

Examples

{:ok, ctx} = Context.new()
{:ok, ctx} = Context.new(causation_id: "external-123")
{:ok, ctx} = Context.new(tracestate: "vendor1=value1")

new!(opts \\ [])

@spec new!(keyword()) :: t()

Creates a new root trace context, raising on error.

Examples

ctx = Context.new!()

schema()

Returns the Zoi schema for Context

to_map(ctx)

@spec to_map(t()) :: map()

Converts the context to a map, filtering out nil values.

Useful for storing in signal extensions where nil values may not be allowed.

Examples

Context.to_map(ctx)
#=> %{trace_id: "abc...", span_id: "def..."}

to_telemetry_metadata(ctx)

@spec to_telemetry_metadata(t() | nil) :: map()

Converts context to telemetry metadata with jido_ prefixed keys.

Examples

Context.to_telemetry_metadata(ctx)
#=> %{jido_trace_id: "abc...", jido_span_id: "def...", ...}

to_traceparent(context)

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

Formats trace context as W3C traceparent header value.

Format: {version}-{trace-id}-{span-id}-{flags}

Version is always "00" (current W3C spec). Flags is "01" (sampled).

Examples

Context.to_traceparent(ctx)
#=> "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"

valid?(arg1)

@spec valid?(t() | nil) :: boolean()

Checks if a trace context is valid.

A valid trace context has:

  • trace_id that is 32 lowercase hex characters
  • span_id that is 16 lowercase hex characters

Examples

Context.valid?(ctx) #=> true
Context.valid?(nil) #=> false