Langfuse.OpenTelemetry.TraceContext (Langfuse v0.1.0)

W3C Trace Context support for distributed tracing.

This module implements the W3C Trace Context specification for propagating trace correlation across service boundaries.

Trace Context Headers

The W3C Trace Context uses two HTTP headers:

traceparent - Required. Contains trace-id, parent-id, and trace-flags
tracestate - Optional. Vendor-specific trace data

Traceparent Format

The traceparent header follows this format:

{version}-{trace-id}-{parent-id}-{trace-flags}
00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

Where:

version - 2 hex digits (currently 00)
trace-id - 32 hex digits (16 bytes)
parent-id - 16 hex digits (8 bytes)
trace-flags - 2 hex digits (sampled = 01)

Usage

Extract trace context from incoming HTTP headers:

context = Langfuse.OpenTelemetry.TraceContext.extract(conn.req_headers)

{:ok, trace} = Langfuse.trace(
  id: context.trace_id,
  name: "incoming-request",
  metadata: %{parent_span_id: context.parent_id}
)

Inject trace context into outgoing HTTP requests:

headers = Langfuse.OpenTelemetry.TraceContext.inject(trace.id, span.id)
Req.get(url, headers: headers)

Summary

Types

t()

Parsed trace context.

Functions

child(map)

Creates a child context from an existing trace context.

extract(headers)

Extracts W3C Trace Context from HTTP headers.

extract!(headers)

Extracts trace context, returning nil on failure.

inject(trace_id, span_id, opts \\ [])

Generates W3C Trace Context headers for outgoing requests.

new(opts \\ [])

Creates a new trace context with a fresh trace ID and span ID.

to_headers(context)

Converts a trace context to headers suitable for HTTP propagation.

Types

t()

@type t() :: %{
  trace_id: String.t(),
  parent_id: String.t(),
  trace_flags: integer(),
  sampled: boolean(),
  tracestate: String.t() | nil
}

Parsed trace context.

Functions

child(map)

@spec child(t()) :: t()

Creates a child context from an existing trace context.

Generates a new span ID while preserving the trace ID for correlation.

Examples

iex> parent = %{trace_id: "abc123", parent_id: "def456", trace_flags: 1, sampled: true, tracestate: nil}
iex> child = Langfuse.OpenTelemetry.TraceContext.child(parent)
iex> child.trace_id
"abc123"
iex> child.parent_id != "def456"
true

extract(headers)

@spec extract([{String.t(), String.t()}] | map()) :: {:ok, t()} | {:error, atom()}

Extracts W3C Trace Context from HTTP headers.

Parses the traceparent and optional tracestate headers to extract trace correlation information.

Examples

iex> headers = [{"traceparent", "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}]
iex> Langfuse.OpenTelemetry.TraceContext.extract(headers)
{:ok, %{
  trace_id: "0af7651916cd43dd8448eb211c80319c",
  parent_id: "b7ad6b7169203331",
  trace_flags: 1,
  sampled: true,
  tracestate: nil
}}

iex> Langfuse.OpenTelemetry.TraceContext.extract([])
{:error, :no_trace_context}

extract!(headers)

@spec extract!([{String.t(), String.t()}] | map()) :: t() | nil

Extracts trace context, returning nil on failure.

Examples

iex> headers = [{"traceparent", "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}]
iex> context = Langfuse.OpenTelemetry.TraceContext.extract!(headers)
iex> context.trace_id
"0af7651916cd43dd8448eb211c80319c"

iex> Langfuse.OpenTelemetry.TraceContext.extract!([])
nil

inject(trace_id, span_id, opts \\ [])

@spec inject(String.t(), String.t(), keyword()) :: [{String.t(), String.t()}]

Generates W3C Trace Context headers for outgoing requests.

Creates traceparent and optionally tracestate headers for propagating trace context to downstream services.

Options

:sampled - Whether the trace is sampled (default: true)
:tracestate - Optional vendor-specific trace state

Examples

iex> Langfuse.OpenTelemetry.TraceContext.inject("abc123def456", "span789")
[{"traceparent", "00-abc123def456000000000000000000000-span78900000000000-01"}]

iex> Langfuse.OpenTelemetry.TraceContext.inject(
...>   "0af7651916cd43dd8448eb211c80319c",
...>   "b7ad6b7169203331",
...>   sampled: false
...> )
[{"traceparent", "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00"}]

new(opts \\ [])

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

Creates a new trace context with a fresh trace ID and span ID.

Useful for starting a new distributed trace.

Options

:sampled - Whether to sample this trace (default: true)

Examples

iex> context = Langfuse.OpenTelemetry.TraceContext.new()
iex> String.length(context.trace_id)
32
iex> String.length(context.parent_id)
16
iex> context.sampled
true

to_headers(context)

@spec to_headers(t()) :: [{String.t(), String.t()}]

Converts a trace context to headers suitable for HTTP propagation.

Examples

iex> context = %{trace_id: "0af7651916cd43dd8448eb211c80319c", parent_id: "b7ad6b7169203331", trace_flags: 1, sampled: true, tracestate: nil}
iex> Langfuse.OpenTelemetry.TraceContext.to_headers(context)
[{"traceparent", "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}]