Impact.Propagator (Impact v0.0.1)

Cross-process OpenTelemetry context propagation.

The BEAM has no shared memory between processes, so the OTel context (the active span + baggage from Impact.Context.put/1) does not automatically travel across GenServer.call/3, Task.async/1, or Oban job boundaries. If you want the spans on the other side to be children of the calling trace instead of orphans, you have to carry the context explicitly.

This module wraps the common patterns.

GenServer.call across a process boundary

# Caller side
def chat(session_id, message) do
  ctx = Impact.Propagator.current()
  GenServer.call(via(session_id), {:chat, message, ctx})
end

# GenServer side
def handle_call({:chat, message, ctx}, _from, state) do
  Impact.Propagator.attach(ctx)
  Impact.trace [type: :task, name: "agent.loop"] do
    ...
  end
end

Task.start with context

ctx = Impact.Propagator.current()

Task.start(fn ->
  Impact.Propagator.with_ctx(ctx, fn ->
    do_async_work()
  end)
end)

Oban jobs

# Enqueue side — inject W3C textmap into job args
args = Map.put(args, :_otel, Impact.Propagator.inject())
MyWorker.new(args) |> Oban.insert()

# Worker side — extract on perform
def perform(%Oban.Job{args: args}) do
  Impact.Propagator.extract_and_attach(args["_otel"])
  ...
end

Why two carrier formats

Two carrier formats are exposed, fit for different transports:

Opaque context term (current/0, attach/1) — cheap, no encoding cost, but only safe to pass via a BEAM message or capture in a closure that runs in the same node.
W3C textmap (inject/0, extract_and_attach/1) — traceparent + tracestate HTTP-header-style strings, serializable into JSON / DB columns / Oban job args / outbound HTTP headers.

Summary

Functions

attach(ctx)

Attach ctx to the current process. Returns the previous context token, which the caller can discard or pass to OpenTelemetry.Ctx.detach/1 to restore later.

current()

Return the current OTel context (opaque term).

extract_and_attach(map)

Extract OTel context from a textmap (e.g. an Oban job arg map) and install it on the current process. No-op when the input is nil or empty.

inject()

Serialize the current OTel context as W3C textmap headers. Returns a plain string-keyed map containing "traceparent" (and optionally "tracestate"), suitable for storing in Oban job args, JSON columns, or outbound HTTP headers.

with_ctx(ctx, fun)

Run fun inside ctx, restoring the previous context on exit (even if fun raises). Preferred pattern for Task.start/Task.async closures because it prevents context leakage into long-lived processes.