@peermetrics/webrtc-stats

WebRTCStats

WebRTCStats is the most complete utility belt that helps with everything related to getting and parsing the stats for WebRTC PeerConnections.

The main advantage of WebRTCStats is that it parses and groups the stats from PeerConnections and offers them in a easy to read way

On top of that, it offers the timeline which is a list of all the events fired while setting up a PeerConnection. Optionally, you can also wrap getUserMedia to get a better picture.

WebRTCStats extends EventEmitter and uses the same event system to communicate with the rest of the app.

Install

npm install @peermetrics/webrtc-stats

Usage

Loading the module

WebRTC Stats can be loaded as an ES6 module, node module or directly in the browser.

After loading, the library needs to be initialized. See Options for all the initialize options

import {WebRTCStats} from '@peermetrics/webrtc-stats'

let webrtcStats = new WebRTCStats({
    getStatsInterval: 5000
})

Add event listeners for stats:

webrtcStats.on('stats', (ev) => {
    console.log('stats', ev)
})

Use addConnection to add connections to the list of monitored peers:

let pc1 = new RTCPeerConnection({...})
webrtcStats.addConnection({
    pc: pc1, // RTCPeerConnection instance
    peerId: '1', // any string that helps you identify this peer,
   	connectionId: '06d54adc-e478-4f95-9144-bbb3562a2aad', // optional, an id that you can use to keep track of this connection
    remote: false // optional, override the global remote flag
})

Now every 5000 ms WebRTCStats will fire the stats event which will come with the object:

{
    event: 'stats',
    tag: 'stats',
    peerId: '1',
    timestamp: 'Sun Mar 22 2020 18:02:02', // a timestamp when this was fired
    data: {...}, // an object created after parsing the stats
    timeTaken: 5, // how many ms the .getStats() call took
    rawStats: RTCStatsReport, // the actual RTCStatsReport results from `getStats()`
    statsObject: {}, // an object created from RTCStatsReport that uses the `id` for each report as a key
    filteredStats: {}, // same as statsObject but with some report types filtered out (eg: `codec`, `certificate`)
}

Options

The module accepts the following options when initialized:

let stats = new WebRTCStats({
    // the interval in ms of how often we should get stats
    getStatsInterval: 5000, // Default: 1000

    // if we should include the original RTCStatsReport map when firing the `stats` event
    rawStats: false, // Default: false

    // include an object that resulted from transforming RTCStatsReport into an oject (`report.id` as the key)
    statsObject: true, // Default: false
    
    // if we should filter out some stats
    filteredStats: false, // Default: false

    // If the data object should contain a remote attribute that will contain stats for the remote peer, from `remote-inbound-rtp`, etc
    remote: true, // Default: true

    // If we should wrap the `geUserMedia` calls so we can gather events when the methods is called or success/error
    wrapGetUserMedia: false, // Default: false
    
    // If we should log messages
    debug: false, // Default: false
    
    // What kind of level of logs the lib should display. Values: 'none', 'error', 'warn', 'info', 'debug'
    logLevel: 'warn' // Default: 'none'
})

API

.addConnection(options)

Adds a connection to the watch list. options

• pc: the RTCPeerConnection instance
• peerId: String a unique Id to identify this peer Monitoring of a peer will automatically end when the connection is closed.
• connectionId: optional, string. A way to identify this connection. If a connectionId is not offered, the lib will assign a random one

Returns:

{
    connectionId: '', // the ID assigned to this connection
}

.removeConnection(options)

Removes the RTCPeerConnection from the list of watched connections for that peer.

options object:

• peerId: the peer id for which we want to remove the connection

• pc: The RTCPeerConnection instance we want to remove

  or

• connectionId: the id of the connection (the one returned when calling .addConnection())

.removePeer(peerId)

Stop listening for events/stats on all connections for this peer

.removeAllPeers()

Used to stop listening to all the peers and connections added.

.getTimeline([filter])

Return the array of events from the timeline up to that point. If the optional filter string is present it will filter out events. Possible values: peer, connection, track, stats, getUserMedia

.destroy()

Stop listening to all event listeners and reset the state of the instance. Useful for cleanup.

A new instance of WebRTCStats should be used if you would like to start monitoring again.

Events

The module uses EventEmitter to emit events. You can listen to them using .on()

stats.on('eventName', (ev) => {
    
})

ev will have the following structure:

{
    // The event name. Usually the method called (addTrack, createAnswer)
    event: '',
    // The tag for this event. `stats`, `sdp`, `getUserMedia`, etc
    tag: '',
    // The id for the peer that fired this event
    peerId: '',
    // A timestamp for when the event happened
    timestamp: '',
    // Data for each event type
    data: {},
    
    // The following attrs appear at certain times
    // The error that appeared in the method we were watching
    error: {},
    // These appear on the `stats` event
    rawStats: {},
    statsObject: {},
    filteredStats: {}
}

List of fired events

The tags for the events fired by WebRTCStats are:

• timeline: this will fire when something has been added to the timeline. This event is a duplicate of the following events
• stats: fired for each peer when we've collected stats for it
• getUserMedia: when getUserMedia is called initially
• peer: when a peer was added
• track: a track event: addTrack, removeTrack, mute, unmute, overconstrained
• connection: any event related to connection
• datachannel: any datachannel event

Developed by

License

MIT