@observertc/client-monitor-js

JavaScript library to monitor WebRTC applications

@observertc/client-monitor-js is a client-side library to monitor WebRTCStats and integrate your app with ObserveRTC components.

Live demo: webrtc-observer.org — an example web page running the client monitor.

Table of Contents

• Installation
• Quick Start
• Integrations
• Configuration
• Detectors
• Score Calculation
• Stats, Sampling and Adapters
• Events and Issues
• Derived Metrics
• Schema Reference
• Examples
• Troubleshooting
• API Reference
• Release candidates
• NPM Package
• Getting Involved
• Reference documents
• FAQ
• License

Installation

npm install @observertc/client-monitor-js

or

yarn add @observertc/client-monitor-js

Quick Start

import { ClientMonitor } from "@observertc/client-monitor-js";

// Create a monitor with default configuration
const monitor = new ClientMonitor({
    clientId: "my-client-id",
    callId: "my-call-id",
    collectingPeriodInMs: 5000,
    samplingPeriodInMs: 5000,
});

// Add a peer connection to monitor
monitor.addSource(peerConnection);

// Listen for samples
monitor.on("sample-created", ({ sample }) => {
    console.log("Sample created:", sample);
    // Send sample to your analytics backend
});

// Listen for issues
monitor.on("issue", (issue) => {
    console.log("Issue detected:", issue);
});

// Close when done
monitor.close();

Integrations

RTCPeerConnection Integration

Direct integration with native WebRTC PeerConnections:

import { ClientMonitor } from "@observertc/client-monitor-js";

const peerConnection = new RTCPeerConnection();
const monitor = new ClientMonitor();

// Add the peer connection for monitoring
monitor.addSource(peerConnection);

Mediasoup Integration

import { ClientMonitor } from "@observertc/client-monitor-js";
import mediasoup from "mediasoup-client";

const device = new mediasoup.Device();
const monitor = new ClientMonitor();

// Monitor the mediasoup device
monitor.addSource(device);

// The monitor will automatically detect new transports created after adding the device
const transport = device.createSendTransport(/* ... */);

// For transports created before adding the device, add them manually:
monitor.addSource(transport);

Important: When adding a mediasoup device, the monitor automatically hooks into the newtransport event to detect newly created transports. However, transports created before adding the device must be added manually.

Session Descriptions (SDP)

The stats API does not say whether DTX, in-band FEC, RED or simulcast were negotiated, whether the far end is ICE lite, or which DTLS role this endpoint took. Hand the monitor the descriptions you applied and it reads them out:

await pc.setLocalDescription(offer);
monitor.acceptLocalDescription(peerConnectionId, pc.localDescription);

await pc.setRemoteDescription(answer);
monitor.acceptRemoteDescription(peerConnectionId, pc.remoteDescription);

const pcMonitor = monitor.getPeerConnectionMonitor(peerConnectionId);
pcMonitor.receivingAudioDtx;      // this endpoint asked the far end to send Opus with DTX
pcMonitor.remoteIceLite;          // true behind an ICE-lite SFU
pcMonitor.negotiatedAudioCodecs;  // ['audio/opus']
pcMonitor.sdp.negotiatedMediaSections; // per mid: directions, codecs, DTX/FEC/RED, simulcast layers

For sources added with addSource this happens automatically: the RTCPeerConnection binding reads both descriptions on every signalingstatechange, and the mediasoup transport binding does the same on the transport's underlying connection (reached through mediasoup-client's private handler._pc; if a handler has none, the transport is still monitored, just without SDP).

With sendSdpMetadataToServer: true (default false), each accepted description is also added to the next sample as LOCAL_SDP / REMOTE_SDP metadata (payload: { peerConnectionId, type, sdp }, with a=ice-pwd redacted). An identical repeat is ignored, as are rollbacks. The flag only controls the wire: descriptions are read and the fields below are published either way. The SDP-derived fields on PeerConnectionMonitor stay undefined until the descriptions that decide them were accepted; most need a completed offer/answer pair.

Logger Integration

Customize logging behavior by providing your own logger to ClientMonitor. The same logger instance is propagated to source and monitor internals. Log messages include module prefixes such as [ClientMonitor]: and [Sources]:. If no logger is provided, the default logger logs warn and error to console and treats trace/debug/info as no-op.

Basic Custom Logger

import { ClientMonitor, Logger } from "@observertc/client-monitor-js";

const customLogger: Logger = {
    trace: (...args) => console.trace(...args),
    debug: (...args) => console.debug(...args),
    info: (...args) => console.info(...args),
    warn: (...args) => console.warn(...args),
    error: (...args) => console.error(...args),
};

const monitor = new ClientMonitor({
    logger: customLogger,
});

Production Logger Adapter

Map your existing app logger to the Logger interface:

This is the beginning of the README. Read the rest at the original. Read the full README ↗