Bridges BEAM :telemetry.span/3 events into the OTel Trace pipeline. Trace pillar's analog of Otel.LoggerHandler (Logs) and Otel.TelemetryReporter (Metrics).

Add to your supervision tree with the event prefixes that should be promoted to OTel spans:

defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Otel.TelemetryTracer, events: [
        [:my_app, :checkout],
        [:phoenix, :endpoint],
        [:my_app, :repo, :query]
      ]}
    ]

    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

Each entry in events: is the prefix (matches the first argument of :telemetry.span/3); the bridge subscribes to the three lifecycle events derived from it (prefix ++ [:start | :stop | :exception]).

What lands in Tempo

Span kind defaults to INTERNAL. Pass metadata.span_kind: :server | :client | :producer | :consumer on the :start event to override.

Context propagation

The :start handler runs synchronously in the calling process before the user function executes; :stop / :exception handlers run after. Between them, the OTel current-span ctx is the new span (stored in process dictionary keyed by the :telemetry.span/3-issued ref). This means:

• Nested :telemetry.span/3 calls automatically form a parent-child chain.
• :telemetry.span/3 ↔ Otel.Trace.with_span/4 mixed in the same process also form a chain (both APIs share the process-dictionary ctx channel).
• Cross-process work (Task.async, GenServer.cast, etc.) still requires explicit Otel.Ctx.attach/1 of the captured parent ctx — same constraint as with_span/4.

Reserved metadata keys

:telemetry.span/3 inserts a few internal keys into the metadata map (notably :telemetry_span_context, the start/stop matching ref). The bridge filters these so they don't leak as span attributes. Keys filtered: :telemetry_span_context, :duration, :monotonic_time, :system_time, :kind, :reason, :stacktrace, :span_kind.

All remaining metadata keys are stringified (to_string/1) and merged onto the span as attributes.

Lifecycle

The bridge is a GenServer with trap_exit: true. Each configured event prefix attaches three handlers via :telemetry.attach/4 keyed by {__MODULE__, event_name, self()}. terminate/2 detaches all of them so a clean shutdown leaves no stale handlers.

Multiple instances under different supervisors can co-exist — each instance owns handlers keyed by its own pid.

References

• :telemetry.span/3: https://hexdocs.pm/telemetry/telemetry.html#span/3
• OTel Trace API §Span Creation: opentelemetry-specification/specification/trace/api.md L378-L414
• OTel Trace API §record_exception: trace/api.md L654-L705