RTCPeerConnection: getStats() method
The RTCPeerConnection
method
getStats()
returns a promise which resolves with data
providing statistics about either the overall connection or about the specified
MediaStreamTrack
.
Syntax
js
getStats()
getStats(selector)
getStats(selector, successCallback, failureCallback) // deprecated
Parameters
selector
Optional-
A
MediaStreamTrack
for which to gather statistics. If this isnull
(the default value), statistics will be gathered for the entireRTCPeerConnection
.
Deprecated parameters
In older code and documentation, you may see a callback-based version of this function.
This has been deprecated and its use is strongly discouraged. You
should update any existing code to use the Promise
-based version of
getStats()
instead. The parameters for the older form of
getStats()
are described below, to aid in updating existing code.
successCallback
Deprecated-
A callback function called once the report has been successfully generated.
failureCallback
Deprecated-
A callback function called once the report has failed to be generated.
Return value
A Promise
which resolves with an RTCStatsReport
object
providing connection statistics. The report's contents depend on the
selector
and 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
DOMException
-
Thrown when there is no
RTCRtpSender
orRTCRtpReceiver
whosetrack
matches the specifiedselector
, orselector
matches more than one sender or receiver.
Examples
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.
js
setInterval(() => {
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: Real-Time Communication in Browsers # widl-RTCPeerConnection-getStats-Promise-RTCStatsReport--MediaStreamTrack-selector |
Browser compatibility
BCD tables only load in the browser