Tracing

The client traces through Effect’s Tracer, so any tracer the application provides, such as OtlpTracer, receives its spans. An operation a caller can cancel has a client span at the call: Reactor.create and Reactor.attach, Session.connect and Session.reconnect (with an event per phase, from reactor.connect.described to reactor.connect.ready; each attempt of a session’s own reconnect is a Session.reconnect span too, the root of a trace of its own, linked to the span of the create or attach that acquired the session; that reconnect runs with the tracer, ErrorReporters and clock the acquisition ran with), Session.upload and Session.close, and CoordinatorClient.mintToken, pricing, inspect and terminate. A request the session owns past its caller’s wait, a command or control request (Session.command, Session.control) or an H3 enqueue (H3.enqueue, with H3.reconcile), has its span on its own execution, so the span ends with the request’s outcome even after the caller stopped waiting. Playout.submit, the playout’s other edits and Playout.place have spans, and so do H3Source.open and H3Source.resume. Termination returns a verdict rather than failing, so CoordinatorClient.terminate and Session.close carry it as reactor.termination.attempted, confirmed and evidence: a span that ended without error does not mean a paid session stopped. Spans name identity and outcome only, never a credential, command input, a reply, an upload’s name or bytes, or provider text. Frames, streams and heartbeats are not traced.

Playout retains each accepted item’s submitting span identity, including its sampling decision, through delayed dispatch, retries and session renewal. Idempotent resubmission keeps the original identity. Playout.command runs under that parent and ends with the source command’s outcome; item commands retain their ancestry after the submitter stops waiting. Autonomous commands, such as filler and ordinary autoplay, and Playout.open start separate traces linked to the playout’s acquisition. Workers keep the playout’s services and session scope; queued work carries trace identity rather than the caller’s service context. Retained identities are removed when item history is forgotten. Applications provide exporters or Effect DevTools at their runtime boundary.

LocalSource.build and LocalSource.present retain the clip’s enqueue parent and sampling decision through their queues, while hooks run with the source’s services and the clip’s scope. SDK spans record sanitized renderer failures; the original diagnostic stays in the source event’s Redacted provider field.

H3 control and read spans cover validation, reply interpretation and state synchronization, so a provider refusal fails its H3 span even when Session.command successfully received the reply. H3Source.recover traces each recovery through reconnect and readback as a root linked to acquisition. Session command, control, upload and close spans carry the known session identity. Locally refused commands record not-submitted without creating owned execution. CoordinatorClient.downloadClip covers the playlist wait and segment download; its span carries session identity and excludes playlist and segment URLs.

Work that an acquisition sets going and no caller causes starts a trace of its own, linked to the acquisition’s span: a session’s own Session.reconnect, Playout.open, an autonomous Playout.command, H3Source.recover, and the hooks of a LocalSource clip enqueued outside any span. Such a trace is unsampled when the acquisition’s span was, so a session, source or playout acquired under an unsampled span exports none of its own work; under a sampled one, MinimumTraceLevel decides, as for any root.

To export the spans, provide a tracer at your application’s entry point, such as Effect’s OtlpTracer from effect/unstable/observability, or Effect DevTools.