@spec add_event(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  event :: Otel.API.Trace.Event.t()
) :: :ok

Application (OTel API MUST) — "AddEvent" (trace/api.md L525-L557).

Records an event on the span. The caller constructs the Event via Otel.API.Trace.Event.new/3 — per spec L543-L544 if no timestamp is supplied the implementation sets it to the time at which the API is called.

Per spec L547 events SHOULD preserve the order in which they are recorded. This facade dispatches to the SDK-registered module, so ordering is the SDK implementation's responsibility; API users relying on order should confirm their SDK honours it.

@spec add_link(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  link :: Otel.API.Trace.Link.t()
) :: :ok

Application (OTel API MUST) — "Add Link" (trace/api.md L562-L564).

Adds a link to another span after creation. Per spec L563 adding links at span creation (via Tracer.start_span/4 opts) is preferred — samplers may not consider links added later.

Per spec L820-L823 SHOULD — "Implementations SHOULD record links containing SpanContext with empty TraceId or SpanId (all zeros) as long as either the attribute set or TraceState is non-empty." SDKs implementing the add_link/2 callback are responsible for honouring this recording rule (the API facade is a pure dispatcher).

@spec end_span(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  timestamp :: non_neg_integer()
) :: :ok

Application (OTel API MUST) — "End" (trace/api.md L647-L682).

Signals that the operation described by the span has ended.

• L672-L673 if timestamp is omitted, the current time is used ("MUST be treated equivalent to passing the current time") — the default arg evaluates System.system_time(:nanosecond) at call time
• L652-L653 implementations SHOULD ignore subsequent calls to end_span and any other Span methods — the span becomes non-recording by being ended
• L677 this operation MUST NOT perform blocking I/O on the calling thread
• L665-L668 ending the span MUST NOT inactivate it in any Context it is active in — ended spans remain usable as parents

L429-L430: "Any span that is created MUST also be ended. This is the responsibility of the user."

Values are Unix epoch nanoseconds (OTLP time_unix_nano, a fixed64 unsigned proto3 field). The typespec is non_neg_integer() enforcing the unsigned invariant at the API boundary.

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

Application (OTel API MUST) — "Get Context" (trace/api.md L458-L461).

Returns the SpanContext associated with this span. On BEAM the SpanContext is itself the handle, so this is identity; per spec L461 the returned value MUST be the same for the entire Span lifetime — satisfied automatically by value semantics.

@spec record_exception(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  exception :: Exception.t(),
  stacktrace :: list(),
  attributes :: %{required(String.t()) => primitive_any()}
) :: :ok

Application (OTel API SHOULD) — "Record Exception" (trace/api.md L684-L704, specialized AddEvent variant).

Records an exception as an event on the span. Per spec L688 this is a specialized variant of AddEvent; per L697-L699 the method MUST accept an optional parameter for additional event attributes, which take precedence over attributes generated from the exception object.

The event follows trace/exceptions.md §Attributes L44-L55:

• event name: "exception" (MUST)
• exception.message (SHOULD)
• exception.stacktrace (SHOULD)
• exception.type (SHOULD)

@spec recording?(span_ctx :: Otel.API.Trace.SpanContext.t()) :: boolean()

Application (OTel API MUST) — "IsRecording" (trace/api.md L463-L493).

Returns whether the span is currently recording data. Per spec L472-L476 IsRecording is independent of the sampled flag in TraceFlags — a span may be recording locally while the trace is not sampled for export. Per spec L478-L481 an ended span SHOULD become non-recording.

Without an SDK installed always returns false via Otel.API.Trace.Span.Noop.

@spec set_attribute(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  key :: String.t(),
  value :: primitive_any()
) :: :ok

Application (OTel API MUST) — "SetAttribute" (trace/api.md L495-L520).

Sets a single attribute on the span. Per spec L513-L514 setting an attribute with the same key as an existing attribute SHOULD overwrite the previous value.

Silently ignored if the span is non-recording (L468-L469) or already ended (L652-L653).

@spec set_attributes(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  attributes :: %{required(String.t()) => primitive_any()}
) :: :ok

Application (OTel API MAY) — "SetAttributes" convenience (trace/api.md L506-L508).

Sets multiple attributes in a single call. Per spec this is a MAY convenience over repeated set_attribute/3; same overwrite and recording-state rules apply.

@spec set_module(module :: module()) :: :ok

SDK (installation hook) — register the SDK Span operations module.

Called by Otel.SDK.Application.start/2 to register the SDK's Span operations module. The Application-tier operations in this module dispatch to the registered module; when no SDK has been installed, get_module/0 falls back to Otel.API.Trace.Span.Noop.

module must implement the Otel.API.Trace.Span behaviour.

@spec set_status(
  span_ctx :: Otel.API.Trace.SpanContext.t(),
  status :: Otel.API.Trace.Status.t()
) :: :ok

Application (OTel API MUST) — "SetStatus" (trace/api.md L565-L624).

Sets the status of the span. Per spec L590 status values form the total order Ok > Error > Unset. The MUST/SHOULD rules (L599 description IGNORE on :ok/:unset, L604 ignore :unset writes, L619-L620 :ok is final) are recording-time invariants and belong to the SDK implementation — see the @callback set_status/2 contract below.

This facade is a pure dispatcher; it forwards the caller-supplied Status verbatim. Callers building a Status via Otel.API.Trace.Status.new/2 are protected from the L599 trap at construction time.

@spec update_name(span_ctx :: Otel.API.Trace.SpanContext.t(), name :: String.t()) ::
  :ok

Application (OTel API MUST) — "UpdateName" (trace/api.md L628-L645).

Updates the span name. Per spec L632-L634 any sampling behaviour based on span name is implementation-dependent — samplers can only consider information already present during span creation.