The event bus

This is the primary API. The Observer is the single emitter for the entire hierarchy. ObservedCall, ObservedClient and ObservedPeerConnection are EventEmitters too, but those local events are reserved for internal teardown wiring — application code belongs on the bus.

Payload shape#

Every event delivers exactly one argument: an object containing the ancestry from the observer down to the entity that raised it, plus any event-specific subject.

type ObserverEventBase           = { observer: Observer; context?: AcceptContext };
type ObservedCallScope           = ObserverEventBase   & { observedCall: ObservedCall };
type ObservedClientScope         = ObservedCallScope   & { observedClient: ObservedClient };
type ObservedPeerConnectionScope = ObservedClientScope & { observedPeerConnection: ObservedPeerConnection };

So a peer-connection-level event hands you everything above it as well:

observer.on("inbound-rtp-added", ({
    observer, observedCall, observedClient, observedPeerConnection, observedInboundRtp,
}) => {
    // all five present and typed
});

on / off / once / emit are fully typed against the event map — the handler argument is inferred from the event name.

Observer level#

Scope { observer }.

Call level#

Scope { observer, observedCall }.

Client level#

Scope { observer, observedCall, observedClient }.

Peer-connection level#

Scope { observer, observedCall, observedClient, observedPeerConnection }.

mediasoup level#

Scope { observer, observedMediasoupRouter }. See SFU integration.

Local lifecycle events#

These stay on the individual entities, for teardown and coordination. You may listen to them, but prefer the bus for application logic.

Choosing a subscription strategy#

observer.on("peer-connection-updated", ({ observedPeerConnection, observedClient }) => {
    metrics.gauge("rtt_ms", observedPeerConnection.currentRttInMs, { client: observedClient.clientId });
});

observer.on("client-updated", ({ observedClient }) => {
    let worstRtt = 0;
    for (const pc of observedClient.observedPeerConnections.values()) {
        worstRtt = Math.max(worstRtt, pc.currentRttInMs ?? 0);
    }
    metrics.gauge("client_worst_rtt_ms", worstRtt, { client: observedClient.clientId });
});

observer.on("client-issue-resolved", ({ observedCall, observedClient, resolvedIssue }) => {
    incidents.record({
        callId: observedCall.callId,
        clientId: observedClient.clientId,
        type: resolvedIssue.type,
        durationInMs: resolvedIssue.durationInMs,
        resolvedBy: resolvedIssue.resolvedBy,
    });
});

observer.on("call-issue",     ({ issue }) => alerting.page(issue));
observer.on("observer-issue", ({ issue }) => alerting.page(issue));