gather WebRTC API traces and statistics
npm install @rtcstats/rtcstats-jsThis is part of the monorepo for rtcstats-js
(clientside monitoring), rtcstats-server (serverside dump collection) and the updated
dump-importer (supporting rtcstats and webrtc-internals formats).
It is part of a bigger offering that includes rtcstats.com,
an online service for debugging and troubleshooting WebRTC statistics.
The Javascript SDK provides low-level logging on peerconnection API calls and periodic getStats calls for analytics/debugging purposes.
It was designed to add a negligible overhead to the application’s performance with minimal integration efforts and remains
inspired by chrome's webrtc-internals page.
This repository is the current iteration of the 2015 rtcstats.js. The principle is still the same:
* Transparent integration by overriding RTCPeerConnection et al with techniques used by adapter.js
* Trace all RTCPeerConnection and getUserMedia API calls and events.
* Send them to a server over Websocket.
The main rtcstats.js exports a number of methods that facilitate this:
* WebSocketTrace instantiates a trace function that is passed to the other methods. It connects to a server over WebSocket.
* wrapRTCPeerConnection wraps RTCPeerConnection and related APIs on the supplied window
object and generates traces using the supplied trace method.
* wrapGetUserMedia and wrapEnumerateDevices do the same for the getUserMedia/getDisplayMedia,
enumerateDevices and related APIs such as MediaStreamTracks and HTMLVideoElement.
Typical usage looks like this:
``
import {wrapRTCStatsWithDefaultOptions} from '@rtcstats/rtcstats-js';
// Instantiate a trace function, using the helper with default options.
// See the example for a more fine-grained approach to wrapping.
const trace = wrapRTCStatsWithDefaultOptions();
// Connect to the rtcstats-server instance.
trace.connect('ws://localhost:8080' + window.location.pathname);
const pc = new RTCPeerConnection();
`
If the server is configured to require an authorization token, the websocket will
be closed with a 1008 policy-violation error and a console warning is emitted.
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:
`
`$3
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.$3
See also the end-to-end example in example/` directory and