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.
CoordinatorClient.terminateUntilConfirmed has a client span naming the session, and each end it asks is a CoordinatorClient.terminate span of its own. Ledger.source has a span that carries the id of the session it resumed or opened, and Ledger.release has one too. References.locate, References.read, References.image and References.audio have spans that carry only the kind of location (reactor.reference.scheme: data, file or http) and, once read, the size (reactor.reference.bytes), never the path, the URL or the data; a download opens no HTTP client span, since one would record the URL.
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.
The hosted qualification runner saves connection phase events with timestamps relative to the run:
reactor.connect.described, prepared, registered, offered, answered and ready. These show
the last completed phase when a connection attempt fails or is still open at a save. The evidence
keeps only those fixed event names and their timestamps; event attributes are omitted. Older run
records have no events field.
To export the spans, provide a tracer at your application’s entry point, such as Effect’s OtlpTracer
from effect/observability, or Effect DevTools.