@spec current_span() :: Otel.API.Trace.SpanContext.t()

Application (OTel API SHOULD) — "Get the currently active span from the implicit context" (trace/api.md L177).

Equivalent to current_span(Otel.API.Ctx.current()) reading from the process-local ambient context.

@spec current_span(ctx :: Otel.API.Ctx.t()) :: Otel.API.Trace.SpanContext.t()

Application (OTel API MUST) — "Extract the Span from a Context instance" (trace/api.md L167).

Reads the SpanContext stored in ctx. When no span has been set, returns an empty SpanContext struct — the invalid sentinel (W3C §trace-id L103 + §parent-id L114).

@spec detach(token :: Otel.API.Ctx.t()) :: :ok

Application (OTel API MAY) — revert a make_current/1 call using the token it returned (trace/api.md L384-L386).

Restores the previous ambient context, undoing the most recent make_current/1 whose token is passed. Delegates to Otel.API.Ctx.detach/1.

@spec get_tracer(instrumentation_scope :: Otel.API.InstrumentationScope.t()) ::
  Otel.API.Trace.Tracer.t()

Application (Convenience) — facade over Otel.API.Trace.TracerProvider.

Returns a Tracer for the given instrumentation scope. Equivalent to calling Otel.API.Trace.TracerProvider.get_tracer/1 directly but exposed on Otel.API.Trace as the user-facing entry point.

@spec make_current(span_ctx :: Otel.API.Trace.SpanContext.t()) :: Otel.API.Ctx.t()

Application (OTel API MAY) — set span_ctx as the currently active span and return a detach token (trace/api.md L384-L386 "this functionality MAY be offered additionally as a separate operation").

For most call sites, prefer with_span/4,5 — it handles attach, exception recording, detach, and end_span in a single closure-safe call. make_current/1 exists for cases where the active span must outlive a single function scope — async handoff, test fixtures, or non-closure interop.

Callers MUST pair each make_current/1 with a detach/1 on every exit path. Use try/after or equivalent to guarantee revert on exceptions:

token = Otel.API.Trace.make_current(span_ctx)
try do
  # ... work ...
after
  Otel.API.Trace.detach(token)
end

Internally composes set_current_span/2 with Otel.API.Ctx.attach/1. Stacked calls are LIFO — nested make_current/detach pairs restore the prior active span in reverse order.

@spec set_current_span(span_ctx :: Otel.API.Trace.SpanContext.t()) :: :ok

Application (OTel API SHOULD) — "Set the currently active span into a new context, and make that the implicit context" (trace/api.md L178).

Writes span_ctx under the Tracing API's private key in the process-local ambient context.

@spec set_current_span(
  ctx :: Otel.API.Ctx.t(),
  span_ctx :: Otel.API.Trace.SpanContext.t()
) ::
  Otel.API.Ctx.t()

Application (OTel API MUST) — "Combine the Span with a Context instance, creating a new Context instance" (trace/api.md L168).

Returns a new context with span_ctx stored under the Tracing API's private key. ctx is not modified.

@spec start_span(
  tracer :: Otel.API.Trace.Tracer.t(),
  name :: String.t(),
  opts :: start_opts()
) ::
  Otel.API.Trace.SpanContext.t()

Application (OTel API MUST) — Span Creation using the implicit (process-local) context as parent (trace/api.md L378-L414).

Per spec L382, the newly created span is not automatically set as the current span. Use with_span/4,5 for automatic context management.

Per spec L403, adding attributes via opts[:attributes] at creation is preferred over Span.set_attribute/3 later — samplers can only consider information already present during creation.

@spec start_span(
  ctx :: Otel.API.Ctx.t(),
  tracer :: Otel.API.Trace.Tracer.t(),
  name :: String.t(),
  opts :: start_opts()
) :: Otel.API.Trace.SpanContext.t()

Application (OTel API MUST) — Span Creation with an explicit parent context (trace/api.md L378-L414).

Per spec L391-L392, only a full Context is accepted as the parent — not a raw Span or SpanContext. Per spec L382 the newly created span is not set as the current span.

@spec with_span(
  tracer :: Otel.API.Trace.Tracer.t(),
  name :: String.t(),
  opts :: start_opts(),
  fun :: (Otel.API.Trace.SpanContext.t() -> result)
) :: result
when result: term()

Application (OTel API MAY) — dispatches to the Tracer's with_span/5 callback using the implicit (process-local) context as parent (trace/api.md L385).

Forwards to the registered Tracer implementation which owns the full span lifecycle (attach/fun/detach/end). See Otel.API.Trace.Tracer.with_span/5 callback contract for lifecycle-ownership rationale.

@spec with_span(
  ctx :: Otel.API.Ctx.t(),
  tracer :: Otel.API.Trace.Tracer.t(),
  name :: String.t(),
  opts :: start_opts(),
  fun :: (Otel.API.Trace.SpanContext.t() -> result)
) :: result
when result: term()

Application (OTel API MAY) — same as with_span/4 but with an explicit parent context (trace/api.md L385).