@observertc/observer-js is the server half of ObserveRTC. A WebRTC application — typically an SFU or a stats backend — feeds it ClientSample objects, and it maintains an in-memory model of every call, participant, peer connection and media stream, derives per-interval and cumulative metrics, and emits a single unified stream of typed events.

It answers the questions a browser structurally cannot: who else is in this state right now, what do they have in common, and where in publisher → SFU → subscriber does the fault begin?

Install

npm install @observertc/observer-js

import { Observer, ClientSample, createJsonlFileSinkFactory } from "@observertc/observer-js";

The same import line works in ESM and CommonJS projects — in ESM it resolves to the .mjs build, in CommonJS to the .js build, with type declarations for both.

Runtime dependencies: @bufbuild/protobuf, events, uuid. mediasoup is an optional peer dependency (>=3.11.0), needed only for router observation. No logger and no transport are bundled. This release ships ClientSample schema 3.7.0.

Sixty-second start

import { Observer, ClientSample } from "@observertc/observer-js";

const observer = new Observer({
    closeCallIfEmptyForMs: 20_000,
    closeClientIfIdleForMs: 60_000,
});

// One bus. Every payload carries its full ancestry.
observer.on("call-added", ({ observedCall }) => {
    console.log("new call", observedCall.callId);
});

observer.on("client-issue", ({ observedClient, issue }) => {
    console.warn(`[${observedClient.clientId}] ${issue.type}`, issue.payload);
});

observer.on("client-issue-resolved", ({ resolvedIssue }) => {
    console.info(resolvedIssue.type, "lasted", resolvedIssue.durationInMs, "ms");
});

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

observer.on("sample-rejected", ({ reason }) => console.warn("dropped a sample:", reason));

// One ingestion method.
function onClientStats(sample: ClientSample) {
    observer.accept(sample, { studioVersion: "1.2.3" });
}

process.on("SIGINT", () => observer.close());

Entities are created lazily by id — you never pre-create a call or a client.

The five ideas

1. One ingestion method

observer.accept(sample, context?);

accept() runs the global middleware chain, gets or creates the call and the client by id, fans the sample out to each peer connection, updates every derived metric, runs detectors, and emits. There is no second entry point, no queue to drain, and no timer inside the library.

2. One event bus

Subscribe on the Observer. Every payload is a single object carrying the ancestry from the observer down to the entity that raised the event:

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

You never walk the tree to attach a listener. The event bus →

3. Lazy entities

Observer
└── ObservedCall
    └── ObservedClient
        └── ObservedPeerConnection
            ├── ObservedInboundRtp / ObservedOutboundRtp
            ├── ObservedInboundTrack / ObservedOutboundTrack
            ├── ObservedRemoteInboundRtp / ObservedRemoteOutboundRtp
            ├── ObservedIceTransport / ObservedIceCandidate / ObservedIceCandidatePair
            ├── ObservedCodec / ObservedMediaSource / ObservedMediaPlayout
            ├── ObservedDataChannel / ObservedCertificate
            └── ObservedPeerConnectionTransport

Every node is created the first time it appears in a sample and garbage-collected when it stops appearing. Entities that go idle auto-close on a timeout you configure. Entities & API →

4. Warn, don’t throw

Operational problems degrade rather than crash: create* returns T | undefined, a malformed sample emits sample-rejected, a throwing middleware drops that one sample. Guard the result of create* / getOrCreate*.

5. Nothing implicit

A new Observer() has zero detectors. There is no default detector set and no detector configuration in ObserverConfig — an application says what it wants to watch, or it watches nothing. A detector nobody asked for is a detector nobody will act on. Detectors →

What the server sees that a client cannot

This is the whole reason the library exists. A client running client-monitor-js already decides what is wrong with that endpoint, with hysteresis and multi-signal confirmation behind every verdict.

If a condition is detectable on the client, the client’s issue is the source of truth.

observer-js does not repeat that work. It correlates across participants:

Issues arrive as intervals, not point-in-time reports

From client-monitor-js 4.6.0 the whole issue lifecycle reaches the server: a stateful issue arrives as two clientIssues[] entries sharing a key — the raise, and a <type>-resolved companion. The observer pairs them and emits client-issue-resolved with durationInMs and resolvedBy.

That turns “several clients reported congestion in the last 10 seconds” — a heuristic that has to guess whether the symptoms are still happening — into “several clients are congested right now, simultaneously”, which is ground truth. Overlapping intervals are much stronger evidence of a shared cause than near-in-time reports.

Extension points

Documentation map

Resources

• npm package
• GitHub repository
• Client-side library
• Schema definitions