@rtcstats/rtcstats-js 2.0.2 → 2.2.0

package/README.md

@@ -39,6 +39,78 @@ trace.connect('ws://localhost:8080' + window.location.pathname);
 const pc = new RTCPeerConnection();
 ```
 
+### Nondefault options
+
+### Counting reloads
+
+rtcstats-js can count the number of times a user has reloaded the page by looking at the sessionStorage.
+If enabled with
+```
+const trace = new WebSocketTrace({countReloads: true});
+```
+this will read the key `rtcstatsReloadCount` from session storage, increment it and write it back.
+
+Reloading the page in the middle of a call is a last resort often used by users when something goes
+really wrong. This feature does not count actual page reloads which would require more DOM event
+listeners but the number of times the trace function has been instantiated which should be once
+per page load.
+
+### Tracing custom events
+Sometimes you may want to send your own events to RTCStats to have them all in one dump file.
+This can be accomplished with the `trace` function as well. The method signature for this is
+```
+trace(method name, e.g. `:userRating`,
+      peerconnection object to associate with or null if not associated,
+      javascript object with data or string)
+```
+
+* The first argument is the method name MUST start with a colon (`:`) to avoid conflicts with any method names that rtcstats-js and rtcstats-server use internally.
+* If the event is to be associated with a particular RTCPeerConnection, pass that connection as the second argument.
+  If it is not, e.g. for an end-of-call user rating, pass `null`.
+* The third argument can be a Javascript string or object which will be encoded using JSON when sent to the server. If there is no additional data, pass `null`.
+* The trace function will internally add a timestamp to the event.
+* rtcstats-server will not process such events by default.
+* A dump-importer should still display a generic rendering of the event.
+
+### Using a JWT to connect to rtcstats-server
+See [the server README](https://github.com/rtcstats/rtcstats/blob/main/packages/rtcstats-server/README.md) for how to
+generate JWT token with information about the user, session and conference.
+
+If the server is configured to require an authorization token, the websocket will
+be closed with a 1008 policy-violation error which can be seen when configuring the logging callback:
+```
+const trace = new WebSocketTrace({log: console.warn.bind(console)});
+```
+
+### Bundling
+To bundle rtcstats-js including its dependencies, use
+```
+npx webpack --entry ./packages/rtcstats-js/rtcstats.js --output-path ./packages/rtcstats-js/dist --output-filename rtcstats.bundle.js --mode production --output-library rtcstats
+```
+then include the resulting bundle which is exported as the global `rtcstats` object:
+```
+<script type="text/javascript" src="rtcstats.bundle.js"></script>
+<script type="text/javascript">
+const trace = rtcstats.wrapRTCStatsWithDefaultOptions();
+// Do something.
+</script>
+```
+
+### Ending a session
+RTCStats sessions create a single dump file for every websocket connection. For long-running pages it may be required
+to close the websocket when a "session" is done and reconnect (possibly with a new JWT):
+```
+trace.connect('ws://localhost:8080/?rtcstats-token=token-1');
+// Do something
+trace.close()
+
+// Reconnect.
+trace.connect('ws://localhost:8080/?rtcstats-token=token-2');
+```
+Note that RTCStats is not keeping track of whether all RTCPeerConnections have been closed and track  from getUserMedia/getDisplayMedia
+have been stopped.
+
+### See also
 See also the [end-to-end example](/example/) in `example/` directory and
 the (internal) API docs [here](docs/index.md).
 

package/media.js

@@ -34,7 +34,7 @@ function wrapTrackProperty(track, property, trace) {
  * Also wraps these methods on MediaStreamTrack
  * * stop
  * * applyConstraints
- * The `ended` event is wrapped as are the setters fro `enabled`
+ * The `ended` event is wrapped as are the setters for `enabled`
  * and `contentHint`.
  *
  * @protected

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@rtcstats/rtcstats-js",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "gather WebRTC API traces and statistics",
   "main": "rtcstats.js",
   "type": "module",
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4-fix.0",
     "@puppeteer/browsers": "^2.10.9",
-    "@web/test-runner": "^0.20.2"
+    "@web/test-runner": "^0.20.2",
+    "jsdoc-to-markdown": "^9.1.3"
   },
   "scripts": {
     "lint": "eslint *.js test/",

package/peerconnection.js

@@ -1,4 +1,9 @@
-import {statsCompression, descriptionCompression, compressMethod} from '@rtcstats/rtcstats-shared';
+import {
+    statsCompression,
+    descriptionCompression,
+    compressMethod,
+    computePressureTable,
+} from '@rtcstats/rtcstats-shared';
 import {map2obj, dumpTrackWithStreams, copyAndSanitizeConfig} from '@rtcstats/rtcstats-shared';
 
 /**
@@ -42,27 +47,27 @@ function wrapRTCRtpSender(trace, window) {
         const nativeMethod = window.RTCRtpSender.prototype[method];
         if (!nativeMethod) return;
 
-        window.RTCRtpSender.prototype[method] = function(...args) {
-            const serializedArgs = JSON.parse(JSON.stringify(args));
+        window.RTCRtpSender.prototype[method] = function(parameters, ...args) {
+            const serializedArgs = JSON.parse(JSON.stringify([parameters, ...args]));
             delete serializedArgs[0].transactionId;
             trace(method, this.__rtcStatsId,
                 serializedArgs,
                 this.__rtcStatsSenderId);
-            return nativeMethod.apply(this, args);
+            return nativeMethod.apply(this, [parameters, ...args]);
         };
     });
     ['replaceTrack'].forEach(method => {
         const nativeMethod = window.RTCRtpSender.prototype[method];
         if (!nativeMethod) return;
-        window.RTCRtpSender.prototype[method] = function(...args) {
+        window.RTCRtpSender.prototype[method] = function(track, ...args) {
             const serializedArgs = [
                 this.track === null ? null : dumpTrackWithStreams(this.track),
-                args[0] === null ? null : dumpTrackWithStreams(args[0]),
+                track === null ? null : dumpTrackWithStreams(track),
             ];
             trace(method, this.__rtcStatsId,
                 serializedArgs,
                 this.__rtcStatsSenderId);
-            return nativeMethod.apply(this, args);
+            return nativeMethod.apply(this, [track, ...args]);
         };
     });
 }
@@ -84,6 +89,14 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
         // Prevent double-wrapping.
         return;
     }
+    let lastComputePressureRecord;
+    if (window.PressureObserver) {
+        const observer = new PressureObserver((records) => {
+            const lastRecord = records[records.length - 1]; // Usually only one record.
+            lastComputePressureRecord = [Date.now(), lastRecord];
+        });
+        observer.observe('cpu', {sampleInterval: getStatsInterval});
+    }
     wrapRTCRtpTransceiver(trace, window);
     wrapRTCRtpSender(trace, window);
     const OrigPeerConnection = window.RTCPeerConnection;
@@ -108,6 +121,15 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
         }
 
         pc.addEventListener('icecandidate', (e) => {
+            // Browser intentionally don't serialize .url and .relayProtocol in .toJSON
+            // but we want them for rtcstats.
+            if (e.candidate && (e.candidate.url || e.candidate.relayProtocol)) {
+                const serializedCandidate = e.candidate.toJSON();
+                serializedCandidate.url = e.candidate.url;
+                serializedCandidate.relayProtocol = e.candidate.relayProtocol;
+                trace('onicecandidate', pcId, serializedCandidate);
+                return;
+            }
             trace('onicecandidate', pcId, e.candidate);
         });
         pc.addEventListener('icecandidateerror', (e) => {
@@ -176,6 +198,14 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
             if (pc.signalingState === 'closed') {
                 return;
             }
+            if (lastComputePressureRecord) {
+                const [timestamp, record] = lastComputePressureRecord;
+                stats['rtcStatsComputePressure'] = {
+                    type: 'compute-pressure',
+                    timestamp,
+                    cpuState: computePressureTable[record.state] || record.state,
+                };
+            }
             const baseStats = JSON.parse(JSON.stringify(stats)); // our new prevStats.
             const compressedStats = statsCompression(prevStats, stats, statsIdMap);
             if (reason) {
@@ -201,9 +231,9 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
     ['createDataChannel'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;
-        OrigPeerConnection.prototype[method] = function(...args) {
-            trace(method, this.__rtcStatsId, args);
-            return nativeMethod.apply(this, args);
+        OrigPeerConnection.prototype[method] = function(label, ...args) {
+            trace(method, this.__rtcStatsId, [label, ...args]);
+            return nativeMethod.apply(this, [label, ...args]);
         };
     });
 
@@ -219,11 +249,10 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
     ['addTrack'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;
-        OrigPeerConnection.prototype[method] = function(...args) {
-            const track = args[0];
-            const streams = args.slice(1);
+        OrigPeerConnection.prototype[method] = function(track, ...args) {
+            const streams = args;
             trace(method, this.__rtcStatsId, dumpTrackWithStreams(track, ...streams));
-            const sender = nativeMethod.apply(this, args);
+            const sender = nativeMethod.apply(this, [track, ...args]);
             sender.__rtcStatsId = this.__rtcStatsId;
             const transceiver = this.getTransceivers().find(t => t.sender === sender);
             if (transceiver) {
@@ -238,18 +267,18 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
     ['addTransceiver'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;
-        OrigPeerConnection.prototype[method] = function(...args) {
+        OrigPeerConnection.prototype[method] = function(trackOrKind, ...args) {
             const serializedArgs = [
-                typeof(args[0]) === 'string' ? args[0] : dumpTrackWithStreams(args[0]), // trackOrKind,
+                typeof(trackOrKind) === 'string' ? trackOrKind : dumpTrackWithStreams(trackOrKind),
             ];
-            if (args[1]) {
-                serializedArgs.push(JSON.parse(JSON.stringify(args[1])));
-                if (args[1].streams) {
-                    serializedArgs[serializedArgs.length - 1].streams = args[1].streams.map(s => s.id);
+            if (args[0]) {
+                serializedArgs.push(JSON.parse(JSON.stringify(args[0])));
+                if (args[0].streams) {
+                    serializedArgs[serializedArgs.length - 1].streams = args[0].streams.map(s => s.id);
                 }
             }
             trace(method, this.__rtcStatsId, serializedArgs);
-            const transceiver = nativeMethod.apply(this, args);
+            const transceiver = nativeMethod.apply(this, [trackOrKind, ...args]);
             transceiver.__rtcStatsId =  this.__rtcStatsId;
             transceiver.sender.__rtcStatsId = this.__rtcStatsId;
             transceiver.sender.__rtcStatsSenderId = transceiver.receiver.track.id;
@@ -261,9 +290,9 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
     ['removeTrack'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;
-        OrigPeerConnection.prototype[method] = function(...args) {
-            trace(method, this.__rtcStatsId, args[0].__rtcStatsSenderId);
-            return nativeMethod.apply(this, args);
+        OrigPeerConnection.prototype[method] = function(sender, ...args) {
+            trace(method, this.__rtcStatsId, sender.__rtcStatsSenderId);
+            return nativeMethod.apply(this, [sender, ...args]);
         };
     });
 
@@ -294,39 +323,33 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
         };
     });
 
-    ['setLocalDescription', 'setRemoteDescription'].forEach(method => {
+    ['setLocalDescription'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;
         OrigPeerConnection.prototype[method] = function(...args) {
             const trackingId = compressMethod(method) + '-' + (counters[method]++);
             let implicitBaseDescription;
-            if (method === 'setLocalDescription') {
-                if (args[0]) {
-                    let explicitBaseDescription;
-                    if (args[0].type === 'offer') { 
-                        explicitBaseDescription = this.__rtcStatsLastCreatedOffer;
-                    } else if (args[0].type === 'answer') {
-                        explicitBaseDescription = this.__rtcStatsLastCreatedAnswer;
-                    }
-                    delete this.__rtcStatsLastCreatedOffer;
-                    delete this.__rtcStatsLastCreatedAnswer;
-                    trace(method, this.__rtcStatsId,
-                        descriptionCompression(this.localDescription || explicitBaseDescription, args[0]),
-                        trackingId);
-                } else {
-                    // Save previous localDescription for delta.
-                    implicitBaseDescription = JSON.parse(JSON.stringify(this.localDescription));
-                    trace(method, this.__rtcStatsId, null, trackingId);
+            if (args[0]) {
+                let explicitBaseDescription;
+                if (args[0].type === 'offer') {
+                    explicitBaseDescription = this.__rtcStatsLastCreatedOffer;
+                } else if (args[0].type === 'answer') {
+                    explicitBaseDescription = this.__rtcStatsLastCreatedAnswer;
                 }
-            } else if (method === 'setRemoteDescription') {
+                delete this.__rtcStatsLastCreatedOffer;
+                delete this.__rtcStatsLastCreatedAnswer;
                 trace(method, this.__rtcStatsId,
-                    descriptionCompression(this.remoteDescription, args[0]),
+                    descriptionCompression(this.localDescription || explicitBaseDescription, args[0]),
                     trackingId);
+            } else {
+                // Save previous localDescription for delta.
+                implicitBaseDescription = JSON.parse(JSON.stringify(this.localDescription));
+                trace(method, this.__rtcStatsId, null, trackingId);
             }
 
             return nativeMethod.apply(this, args)
                 .then(() => {
-                    if (method === 'setLocalDescription' && args.length === 0) {
+                    if (args.length === 0) {
                         trace(method + 'OnSuccess', this.__rtcStatsId,
                             descriptionCompression(implicitBaseDescription, this.localDescription),
                             trackingId);
@@ -342,6 +365,27 @@ export function wrapRTCPeerConnection(trace, window, {getStatsInterval}) {
         };
     });
 
+    ['setRemoteDescription'].forEach(method => {
+        const nativeMethod = OrigPeerConnection.prototype[method];
+        if (!nativeMethod) return;
+        OrigPeerConnection.prototype[method] = function(description, ...args) {
+            const trackingId = compressMethod(method) + '-' + (counters[method]++);
+            trace(method, this.__rtcStatsId,
+                descriptionCompression(this.remoteDescription, description),
+                trackingId);
+
+            return nativeMethod.apply(this, [description, ...args])
+                .then(() => {
+                    trace(method + 'OnSuccess', this.__rtcStatsId, undefined,
+                        trackingId);
+                }, (err) => {
+                    trace(method + 'OnFailure', this.__rtcStatsId, err.toString(),
+                        trackingId);
+                    throw err;
+                });
+        };
+    });
+
     ['addIceCandidate'].forEach(method => {
         const nativeMethod = OrigPeerConnection.prototype[method];
         if (!nativeMethod) return;

package/rtcstats.js

@@ -8,7 +8,7 @@ import {WebSocketTrace} from './trace-websocket.js';
  * @returns {function} RTCStats trace function.
  */
 export function wrapRTCStatsWithDefaultOptions(config = {getStatsInterval: 1000}) {
-    const trace = new WebSocketTrace();
+    const trace = new WebSocketTrace(config);
 
     // Wrap RTCPeerConnection-related APIs and events
     wrapRTCPeerConnection(trace, window, config);

package/trace-websocket.js

@@ -1,11 +1,27 @@
 import {compressMethod} from '@rtcstats/rtcstats-shared';
 
 const PROTOCOL_VERSION = '5.0';
+const RELOAD_COUNT_KEY = 'rtcstatsReloadCount';
 
-export function WebSocketTrace() {
+export function WebSocketTrace(config = {}) {
     let buffer = [];
     let connection;
     let lastTime = 0;
+    let connectionStartTime = 0;
+    const createTime = Date.now();
+
+    // This counts the number of times the trace itself has been initialized.
+    // Typically this is done once per session and counting (re)loads based
+    // on that does not require listening for onload etc.
+    let reloadCount = undefined;
+    if (window.sessionStorage && config.countReloads) {
+        reloadCount =  window.sessionStorage.getItem(RELOAD_COUNT_KEY);
+        if (reloadCount === null || isNaN(reloadCount)) {
+            reloadCount = -1;
+        }
+        reloadCount = parseInt(reloadCount, 10) + 1;
+        window.sessionStorage.setItem(RELOAD_COUNT_KEY, reloadCount);
+    }
     const trace = function(...args) {
         const now = Date.now();
         args.push(now - lastTime);
@@ -32,40 +48,64 @@ export function WebSocketTrace() {
             buffer.push(args);
         }
     };
-    trace('create', null, {
-        hardwareConcurrency: navigator.hardwareConcurrency,
-        userAgentData: navigator.userAgentData,
-        deviceMemory: navigator.deviceMemory,
-        screen: {
-            width: window.screen.availWidth,
-            height: window.screen.availHeight,
-            devicePixelRatio: window.devicePixelRatio,
-        },
-        window: {
-            width: window.innerWidth,
-            height: window.innerHeight,
-        },
-    });
 
     trace.close = () => {
-        connection.close();
+        if (window.sessionStorage && config.countReloads) {
+            // A clean disconnect clears the reload count.
+            window.sessionStorage.removeItem(RELOAD_COUNT_KEY);
+        }
+        if (connection) {
+            connection.close();
+        }
     };
     trace.connect = (wsURL) => {
         if (connection) {
             connection.close();
         }
+        connectionStartTime = Date.now();
         connection = new WebSocket(wsURL, 'rtcstats#' + PROTOCOL_VERSION);
         connection.addEventListener('error', (e) => {
             // console.error('WS ERROR', e);
         });
 
-        connection.addEventListener('close', () => {
+        connection.addEventListener('close', (e) => {
+            if (e.code === 1008 && config.log) {
+                config.log('rtcstats websocket connection closed with error=1008. ' +
+                           'Typically this means authorization is required and failed.');
+            }
             // reconnect?
         });
 
         connection.addEventListener('open', () => {
+            // Note: open is called while the socket is still authenticating.
+            // This can lead to messages being send and dropped when the token
+            // is not valid.
+
+            // Note: this does not use trace so avoids the buffer.
+            connection.send(JSON.stringify(['create', null, {
+                hardwareConcurrency: navigator.hardwareConcurrency,
+                userAgentData: navigator.userAgentData,
+                deviceMemory: navigator.deviceMemory,
+                screen: {
+                    width: window.screen.availWidth,
+                    height: window.screen.availHeight,
+                    devicePixelRatio: window.devicePixelRatio,
+                },
+                window: {
+                    width: window.innerWidth,
+                    height: window.innerHeight,
+                },
+                reloadCount,
+            }, createTime]));
+            const connectionTime = Date.now() - connectionStartTime;
             setTimeout(function flush() {
                 if (!buffer.length) {
+                    trace('websocket', null, {
+                        connectionTime,
+                    });
+                    return;
+                }
+                if (connection.readyState !== WebSocket.OPEN) {
                     return;
                 }
                 connection.send(JSON.stringify(buffer.shift()));