RTCPeerConnection.getStats()
The RTCPeerConnection
method
getStats()
returns a promise which resolves with data
providing statistics about either the overall connection or about the specified
MediaStreamTrack
.
Syntax
promise = rtcPeerConnection.getStats(selector)
Parameters
selector
Optional-
A
MediaStreamTrack
for which to gather statistics. If this isnull
(the default value), statistics will be gathered for the entireRTCPeerConnection
.
Return value
A Promise
which resolves with an RTCStatsReport
object
providing connection statistics. The contents of the report depend on the
selector
as well as other details of the connection.
Exceptions
This method does not throw exceptions; instead, it rejects the returned promise with one of the following errors:
InvalidAccessError
-
There is no
RTCRtpSender
orRTCRtpReceiver
whosetrack
matches the specifiedselector
, orselector
matches more than one sender or receiver.
Obsolete syntax
Previously, getStats()
used success and failure callbacks to report the
results to you, instead of using a promise.
This version of getStats()
is obsolete; in addition, the data it returns
is entirely different from the current specification, and the form of that data was
never documented. This form of getStats()
has been or will soon be removed
from most browsers; you should not use it, and should update existing code to use
the new promise-based version. Check the Browser compatibility table
to verify the state of this method.
promise = rtcPeerConnection.getStats(selector, successCallback, failureCallback)
Parameters
selector
Optional-
A
MediaStreamTrack
for which to gather statistics. If this isnull
(the default value), statistics will be gathered for the entireRTCPeerConnection
. successCallback
-
A callback function to call when the stats have been retrieved. The function receives as input a single parameter: an
RTCStatsReport
with the collected statistics. No output is expected from the function. failureCallback
-
A function to call when an error occurs while attempting to collect statistics. The callback receives as input the exception (a
DOMException
object describing the error which occurred. No return value is expected from the callback.
Example
This example creates a periodic function using
setInterval()
that collects
statistics for an RTCPeerConnection
every second, generating an
HTML-formatted report and inserting it into a specific element in the DOM.
window.setInterval(function() {
myPeerConnection.getStats(null).then(stats => {
let statsOutput = "";
stats.forEach(report => {
statsOutput += `<h2>Report: ${report.type}</h2>\n<strong>ID:</strong> ${report.id}<br>\n` +
`<strong>Timestamp:</strong> ${report.timestamp}<br>\n`;
// Now the statistics for this report; we intentionally drop the ones we
// sorted to the top above
Object.keys(report).forEach(statName => {
if (statName !== "id" && statName !== "timestamp" && statName !== "type") {
statsOutput += `<strong>${statName}:</strong> ${report[statName]}<br>\n`;
}
});
});
document.querySelector(".stats-box").innerHTML = statsOutput;
});
}, 1000);
This works by calling getStats()
, then, when the promise is resolved,
iterates over the RTCStats
objects on the returned
RTCStatsReport
. A section is created for each report with a header and
all of the statistics below, with the type, ID, and timestamp handled specially to place
them at the top of the list.
Once the HTML for the report is generated, it is
injected into the element whose class is "stats-box"
by setting its
innerHTML
property.
Specifications
Specification |
---|
WebRTC 1.0: Real-Time Communication Between Browsers # widl-RTCPeerConnection-getStats-Promise-RTCStatsReport--MediaStreamTrack-selector |
Browser compatibility
BCD tables only load in the browser