Observer on ObserveRTC

Observer on ObserveRTC/docs/observer-js/Recent content in Observer on ObserveRTCHugoenCopyright (c) 2020-2024 ThuliteSun, 13 Sep 2026 10:00:00 +0200What changed in 1.0/docs/observer-js/what-changed-in-1.0/Sun, 13 Sep 2026 10:00:00 +0200/docs/observer-js/what-changed-in-1.0/<p><code>1.0.0</code> is the first stable release: the API described across these pages follows semver from here, so a breaking change means a 2.0.0. Getting there meant removing several things rather than deprecating them, because each of them was a mechanism that had earned its way out.</p>Ingestion & lifecycle/docs/observer-js/ingestion-lifecycle/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/ingestion-lifecycle/<h2 id="the-data-flow">The data flow</h2> <div class="expressive-code"> <figure class="frame not-content"> <figcaption class="header"> <span class="title"></span> </figcaption> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">client getStats() ──► ClientSample ──► observer.accept(sample, ctx?) </span></span><span class="line"><span class="cl"> │ </span></span><span class="line"><span class="cl"> ┌────────────────────────────────┘ </span></span><span class="line"><span class="cl"> ▼ </span></span><span class="line"><span class="cl"> accept middlewares (global, in order) </span></span><span class="line"><span class="cl"> │ </span></span><span class="line"><span class="cl"> ▼ </span></span><span class="line"><span class="cl"> get-or-create ObservedCall ──► get-or-create ObservedClient ──► client.accept(sample, ctx) </span></span><span class="line"><span class="cl"> │ </span></span><span class="line"><span class="cl"> per peerConnections[] in the sample </span></span><span class="line"><span class="cl"> ▼ </span></span><span class="line"><span class="cl"> get-or-create ObservedPeerConnection </span></span><span class="line"><span class="cl"> .accept(pcSample, ctx) updates all sub-stats, </span></span><span class="line"><span class="cl"> derives deltas/bitrates/RTT, correlates remote RTP </span></span><span class="line"><span class="cl"> │ </span></span><span class="line"><span class="cl"> metrics roll up: PeerConnection → Client → Call → Observer </span></span><span class="line"><span class="cl"> │ </span></span><span class="line"><span class="cl"> events emitted on the Observer bus</span></span></code></pre></div> </figure> </div> <h2 id="observeracceptsample-context"><code>observer.accept(sample, context?)</code></h2> <p>The single entry point. It:</p>The event bus/docs/observer-js/the-event-bus/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/the-event-bus/<p>This is the primary API. <strong>Subscribe on the <code>Observer</code> instance</strong> — it is the single emitter for the entire hierarchy. The <code>ObservedCall</code> / <code>ObservedClient</code> / <code>ObservedPeerConnection</code> objects are <code>EventEmitter</code>s too, but those local events are reserved for internal lifecycle wiring; application code uses the observer bus.</p>Entities & API reference/docs/observer-js/entities-api-reference/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/entities-api-reference/<h2 id="the-hierarchy">The hierarchy</h2> <table> <thead> <tr> <th>Class</th> <th>Created by</th> <th>Keyed on its parent as</th> <th>Holds</th> </tr> </thead> <tbody> <tr> <td><code>Observer</code></td> <td><code>new Observer(config?)</code></td> <td>— (root)</td> <td><code>observedCalls</code>, global counters, the event bus</td> </tr> <tr> <td><code>ObservedCall</code></td> <td><code>observer.createObservedCall(settings)</code> / lazily by <code>accept</code></td> <td><code>observedCalls</code></td> <td><code>observedClients</code>, call-wide metrics, <code>detectors</code>, <code>scoreCalculator</code></td> </tr> <tr> <td><code>ObservedClient</code></td> <td><code>call.createObservedClient(settings)</code> / lazily</td> <td><code>observedClients</code></td> <td><code>observedPeerConnections</code>, per-client metrics</td> </tr> <tr> <td><code>ObservedPeerConnection</code></td> <td>lazily, from <code>sample.peerConnections[]</code></td> <td><code>observedPeerConnections</code></td> <td>the 15 sub-stat maps, transport/RTT/bitrate metrics</td> </tr> <tr> <td>Sub-stats</td> <td>lazily, from the <code>PeerConnectionSample</code></td> <td>maps on the PC</td> <td>individual WebRTC stat objects</td> </tr> </tbody> </table> <p><code>ObservedPeerConnection</code> holds fifteen <code>public readonly</code> sub-stat maps:</p>Detectors/docs/observer-js/detectors/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/detectors/<p><code>observer-js</code> ships <strong>ten detectors</strong>, each an opt-in extension you register explicitly. None are created automatically.</p> <div class="callout callout-tip d-flex flex-row mt-4 mb-4 pt-4 pe-4 pb-2 ps-3"> <div class="callout-content"> <div class="callout-title"> <p>The organising principle</p>Validators/docs/observer-js/validators/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/validators/<p>Every detector answers <em>“is something wrong right now?”</em> and runs on every tick, because the answer legitimately changes. A <strong>validator</strong> answers <em>“is this deployment built correctly?”</em> — which only changes when you deploy. So it is not configured on and left running: you <strong>start</strong> one, it runs until it can decide, reports once, and the observer drops it.</p>Call summaries/docs/observer-js/call-summaries/Sun, 13 Sep 2026 10:00:00 +0200/docs/observer-js/call-summaries/<p>Detectors answer “is something wrong right now”, validators answer a structural question once, and both read state the call throws away when it ends. A <strong>call summary</strong> is the one thing that outlives the call: who was in it, what was raised against it, how it scored.</p>SFU integration/docs/observer-js/sfu-integration/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/sfu-integration/<h2 id="remote-track-resolution">Remote track resolution</h2> <p>In an SFU, one participant’s <strong>outbound</strong> track is delivered to other participants as <strong>inbound</strong> tracks — one publisher, many subscribers. Correlation is <strong>opt-in per observer</strong>: set <code>ObserverConfig.createRemoteTrackResolver</code>, a factory invoked when each call is created that returns the call’s <code>RemoteTrackResolver</code> (or <code>undefined</code> for none).</p>Sinks & injection/docs/observer-js/sinks-injection/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/sinks-injection/<h2 id="sinks">Sinks</h2> <p>A <strong>sink</strong> receives the samples a client accepts — for archival, streaming, or later offline replay. Each <code>ObservedClient</code> gets its <strong>own</strong> sink, produced by the <code>ObserverConfig.createClientSink</code> factory when the client is created (return <code>undefined</code> for no sink). The client pushes every accepted sample to its sink and <code>end()</code>s it on close.</p>Recipes/docs/observer-js/recipes/Mon, 15 Jan 2024 10:00:00 +0200/docs/observer-js/recipes/<h2 id="a-complete-sfu-side-setup">A complete SFU-side setup</h2> <div class="expressive-code"> <figure class="frame not-content"> <figcaption class="header"> <span class="title"></span> </figcaption> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">Observer</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> <span class="nx">createDefaultMediasoupRemoteTrackResolverFactory</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> <span class="nx">createJsonlFileSinkFactory</span><span class="p">,</span> </span></span><span class="line"><span class="cl"><span class="p">}</span> <span class="kr">from</span> <span class="s1">'@observertc/observer-js'</span><span class="p">;</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">observer</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Observer</span><span class="p">({</span> </span></span><span class="line"><span class="cl"> <span class="nx">closeClientIfIdleForMs</span>: <span class="kt">60_000</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> <span class="nx">closeCallIfEmptyForMs</span>: <span class="kt">20_000</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"> <span class="c1">// Publisher ↔ subscriber links, which four detectors and two validators need. </span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="nx">createRemoteTrackResolver</span>: <span class="kt">createDefaultMediasoupRemoteTrackResolverFactory</span><span class="p">(),</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"> <span class="c1">// Archive every accepted sample, one file per client. </span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="nx">createClientSink</span>: <span class="kt">createJsonlFileSinkFactory</span><span class="p">({</span> <span class="nx">directory</span><span class="o">:</span> <span class="s1">'./stats'</span> <span class="p">}),</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"> <span class="c1">// The one record that outlives the call. </span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="nx">callSummary</span><span class="o">:</span> <span class="p">{</span> <span class="nx">include</span><span class="o">:</span> <span class="p">[</span><span class="s1">'clients'</span><span class="p">,</span> <span class="s1">'issues'</span><span class="p">,</span> <span class="s1">'turnServers'</span><span class="p">,</span> <span class="s1">'scores'</span><span class="p">]</span> <span class="p">},</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"> <span class="c1">// Bake the tenant into appData at birth, resolved once in a middleware. </span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="nx">createCallAppData</span><span class="o">:</span> <span class="p">({</span> <span class="nx">callId</span><span class="p">,</span> <span class="nx">acceptCtx</span> <span class="p">})</span> <span class="o">=></span> <span class="p">({</span> <span class="nx">callId</span><span class="p">,</span> <span class="nx">tenant</span>: <span class="kt">acceptCtx?.tenant</span> <span class="p">}),</span> </span></span><span class="line"><span class="cl"> <span class="nx">createClientAppData</span><span class="o">:</span> <span class="p">({</span> <span class="nx">clientId</span><span class="p">,</span> <span class="nx">observedCall</span> <span class="p">})</span> <span class="o">=></span> <span class="p">({</span> <span class="nx">clientId</span><span class="p">,</span> <span class="nx">tenant</span>: <span class="kt">observedCall.appData.tenant</span> <span class="p">}),</span> </span></span><span class="line"><span class="cl"><span class="p">});</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="c1">// Nothing is implicit — say what you want to watch. </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="nx">observer</span> </span></span><span class="line"><span class="cl"> <span class="p">.</span><span class="nx">addObserverDetector</span><span class="p">(</span><span class="s1">'observer-concurrent-issue-detector'</span><span class="p">,</span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">issueTypes</span><span class="o">:</span> <span class="p">[</span><span class="s1">'congestion'</span><span class="p">,</span> <span class="s1">'ice-disconnected'</span><span class="p">,</span> <span class="s1">'ice-connection-failed'</span><span class="p">],</span> </span></span><span class="line"><span class="cl"> <span class="nx">minAffectedCalls</span>: <span class="kt">3</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> <span class="p">})</span> </span></span><span class="line"><span class="cl"> <span class="p">.</span><span class="nx">addObserverDetector</span><span class="p">(</span><span class="s1">'client-population-issue-detector'</span><span class="p">,</span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">issueTypes</span><span class="o">:</span> <span class="p">[</span><span class="s1">'cpulimitation'</span><span class="p">],</span> </span></span><span class="line"><span class="cl"> <span class="nx">groupBy</span><span class="o">:</span> <span class="s1">'browser'</span><span class="p">,</span> </span></span><span class="line"><span class="cl"> <span class="p">})</span> </span></span><span class="line"><span class="cl"> <span class="p">.</span><span class="nx">addObserverDetector</span><span class="p">(</span><span class="s1">'turn-server-health-detector'</span><span class="p">)</span> </span></span><span class="line"><span class="cl"> <span class="p">.</span><span class="nx">addObserverDetector</span><span class="p">(</span><span class="s1">'turn-server-outage-detector'</span><span class="p">,</span> <span class="p">{</span> <span class="nx">minClientsAtPeak</span>: <span class="kt">10</span> <span class="p">});</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="nx">observer</span><span class="p">.</span><span class="nx">addCallDetector</span><span class="p">(</span><span class="s1">'call-concurrent-issue-detector'</span><span class="p">,</span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">issueTypes</span><span class="o">:</span> <span class="p">[</span><span class="s1">'congestion'</span><span class="p">,</span> <span class="s1">'video-flow-disrupted'</span><span class="p">,</span> <span class="s1">'invented-speech'</span><span class="p">],</span> </span></span><span class="line"><span class="cl"><span class="p">});</span> </span></span><span class="line"><span class="cl"><span class="nx">observer</span><span class="p">.</span><span class="nx">addCallDetector</span><span class="p">(</span><span class="s1">'track-delivery-mismatch-detector'</span><span class="p">,</span> <span class="p">{});</span> </span></span><span class="line"><span class="cl"><span class="nx">observer</span><span class="p">.</span><span class="nx">addCallDetector</span><span class="p">(</span><span class="s1">'publisher-fault-corroboration-detector'</span><span class="p">,</span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">publisherIssueTypes</span><span class="o">:</span> <span class="p">[</span><span class="s1">'encoder-bottleneck'</span><span class="p">,</span> <span class="s1">'video-capture-bottleneck'</span><span class="p">],</span> </span></span><span class="line"><span class="cl"> <span class="nx">receiverIssueTypes</span><span class="o">:</span> <span class="p">[</span><span class="s1">'video-flow-disrupted'</span><span class="p">,</span> <span class="s1">'dry-inbound-track'</span><span class="p">],</span> </span></span><span class="line"><span class="cl"><span class="p">});</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="c1">// Prove the resolver is actually wired — the failure mode is permanent silence. </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="nx">observer</span><span class="p">.</span><span class="nx">addValidator</span><span class="p">(</span><span class="s1">'remote-track-resolver'</span><span class="p">);</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="nx">process</span><span class="p">.</span><span class="nx">on</span><span class="p">(</span><span class="s1">'SIGINT'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=></span> <span class="nx">observer</span><span class="p">.</span><span class="nx">close</span><span class="p">());</span></span></span></code></pre></div> </figure> </div> <h2 id="http-ingestion">HTTP ingestion</h2> <div class="expressive-code"> <figure class="frame not-content"> <figcaption class="header"> <span class="title"></span> </figcaption> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">express</span> <span class="kr">from</span> <span class="s1">'express'</span><span class="p">;</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">app</span> <span class="o">=</span> <span class="nx">express</span><span class="p">();</span> </span></span><span class="line"><span class="cl"><span class="nx">app</span><span class="p">.</span><span class="nx">use</span><span class="p">(</span><span class="nx">express</span><span class="p">.</span><span class="nx">json</span><span class="p">({</span> <span class="nx">limit</span><span class="o">:</span> <span class="s1">'2mb'</span> <span class="p">}));</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="c1">// Carry the clientId outside the payload so routing never depends on decoding it. </span></span></span><span class="line"><span class="cl"><span class="c1"></span><span class="nx">app</span><span class="p">.</span><span class="nx">post</span><span class="p">(</span><span class="s1">'/api/samples/:clientId'</span><span class="p">,</span> <span class="p">(</span><span class="nx">req</span><span class="p">,</span> <span class="nx">res</span><span class="p">)</span> <span class="o">=></span> <span class="p">{</span> </span></span><span class="line"><span class="cl"> <span class="nx">observer</span><span class="p">.</span><span class="nx">accept</span><span class="p">(</span><span class="nx">req</span><span class="p">.</span><span class="nx">body</span><span class="p">,</span> <span class="p">{</span> <span class="nx">receivedAt</span>: <span class="kt">Date.now</span><span class="p">(),</span> <span class="nx">tenant</span>: <span class="kt">req.header</span><span class="p">(</span><span class="s1">'x-tenant'</span><span class="p">)</span> <span class="p">});</span> </span></span><span class="line"><span class="cl"> <span class="nx">res</span><span class="p">.</span><span class="nx">sendStatus</span><span class="p">(</span><span class="mi">202</span><span class="p">);</span> </span></span><span class="line"><span class="cl"><span class="p">});</span></span></span></code></pre></div> </figure> </div> <p>With a binary codec, one decoder per connection and in order — see <a href="/docs/samples-protobuf-codec/">the protobuf codec</a>:</p>