RTCStatsReport

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

Die RTCStatsReport-Schnittstelle der WebRTC API bietet einen Statistikbericht für eine RTCPeerConnection, RTCRtpSender oder RTCRtpReceiver.

Eine RTCStatsReport-Instanz ist ein schreibgeschütztes Map-ähnliches Objekt, in dem jeder Schlüssel ein Identifikator für ein Objekt ist, für das Statistiken erstellt werden, und der entsprechende Wert ein Wörterbuchobjekt ist, das die Statistiken bereitstellt.

Instanz-Eigenschaften

RTCStatsReport.size

Gibt die Anzahl der Elemente im RTCStatsReport-Objekt zurück.

Instanz-Methoden

RTCStatsReport.entries()

Gibt ein neues Iterator-Objekt zurück, das ein zweigliedriges Array von [id, statistic-dictionary] für jedes Element im RTCStatsReport-Objekt in Einfügungsreihenfolge enthält.

RTCStatsReport.forEach()

Ruft callbackFn einmal für jedes im RTCStatsReport-Objekt vorhandene Schlüssel-Wert-Paar in Einfügungsreihenfolge auf. Wenn ein thisArg-Parameter an forEach übergeben wird, wird er als this-Wert für jeden Rückruf verwendet.

RTCStatsReport.get()

Gibt das Statistik-Wörterbuch zurück, das mit der übergebenen id verknüpft ist, oder undefined, wenn keine vorhanden ist.

RTCStatsReport.has()

Gibt einen booleschen Wert zurück, der angibt, ob das RTCStatsReport ein Statistik-Wörterbuch enthält, das mit der angegebenen id verknüpft ist.

RTCStatsReport.keys()

Gibt ein neues Iterator-Objekt zurück, das die Schlüssel (IDs) für jedes Element im RTCStatsReport-Objekt in Einfügungsreihenfolge enthält.

RTCStatsReport.values()

Gibt ein neues Iterator-Objekt zurück, das die Werte (Statistik-Objekte) für jedes Element im RTCStatsReport-Objekt in Einfügungsreihenfolge enthält.

RTCStatsReport[Symbol.iterator]()

Gibt ein neues Iterator-Objekt zurück, das ein zweigliedriges Array von [id, statistic-dictionary] für jedes Element im RTCStatsReport-Objekt in Einfügungsreihenfolge enthält.

Beschreibung

Ein Promise, der sich in ein RTCStatsReport auflöst, wird von den Methoden RTCRtpReceiver.getStats(), RTCRtpSender.getStats() und RTCPeerConnection.getStats() zurückgegeben. Das Aufrufen von getStats() bei einem RTCPeerConnection ermöglicht es Ihnen, anzugeben, ob Sie ausgehende Statistiken, eingehende Statistiken oder Statistiken für die gesamte Verbindung erhalten möchten. Die Versionen getStats() von RTCRtpReceiver und RTCRtpSender geben jeweils nur eingehende bzw. ausgehende Statistiken zurück.

Der Statistikbericht ist ein schreibgeschütztes Map-ähnliches Objekt: ein geordnetes Wörterbuch, bei dem die Eigenschaften id-Strings sind, die das WebRTC-Objekt eindeutig identifizieren, das zur Erstellung eines bestimmten Satzes von Statistiken überprüft wurde, und der Wert ein Wörterbuchobjekt ist, das diese Statistiken enthält. Ein RTCStatsReport kann wie ein schreibgeschütztes Map durchlaufen und verwendet werden.

Der Bericht kann viele verschiedene Kategorien von Statistiken enthalten, einschließlich ein- und ausgehender Statistiken sowohl für die aktuellen als auch für die Remote-Enden der Peer-Verbindung, Informationen über Codecs, Zertifikate und verwendete Medien und so weiter. Jede Kategorie von Statistiken wird in einem anderen Typ von Statistik-Wörterbuchobjekt bereitgestellt, das anhand seiner type-Eigenschaft identifiziert werden kann.

Allgemeine Instanz-Eigenschaften

Alle Wörterbuchtypen haben die folgenden Eigenschaften:

id

Ein String, der das Objekt eindeutig identifiziert, das überwacht wurde, um den Satz von Statistiken zu erstellen. Dieser Wert bleibt über Berichte hinweg für (mindestens) die Lebensdauer der Verbindung bestehen. Beachten Sie jedoch, dass sich die ID für einige Statistiken zwischen Browsern und für nachfolgende Verbindungen, selbst zum gleichen Peer, ändern kann.

timestamp

Ein hochauflösendes Zeitstempelobjekt (DOMHighResTimeStamp), das Zeit angibt, zu der die Probe entnommen wurde. Viele gemeldete Statistiken sind kumulative Werte; der Zeitstempel ermöglicht es, Raten und Durchschnitte zwischen beliebigen zwei Berichten mit jeder gewünschten Berichtsrate zu berechnen.

type

Ein String mit einem Wert, der den Typ der Statistiken angibt, die das Objekt enthält, wie candidate-pair, inbound-rtp, certificate und so weiter. Die Statistik-Typen und deren zugehörige Objekte sind unten aufgelistet.

Benutzer iterieren typischerweise ein RTCStatsReport, indem sie eine forEach()- oder for...of-Schleife verwenden und die interessierenden Statistiken mit der type-Eigenschaft auswählen. Sobald ein bestimmtes Statistikobjekt mit seinem type identifiziert wurde, kann die id-Eigenschaft anschließend mit get() verwendet werden, um denselben Statistikbericht zu einem anderen Zeitpunkt zu erhalten.

Der Zeitstempel kann verwendet werden, um Durchschnittswerte für Statistiken zu berechnen, die sich über die Lebensdauer einer Verbindung ansammeln.

Die Statistik-Typen

Die Statistik-type-Werte und deren entsprechende Wörterbücher sind unten aufgeführt.

type Dictionary Beschreibung
candidate-pair RTCIceCandidatePairStats Statistiken, die den Wechsel von einem RTCIceTransport zu einem anderen beschreiben, wie z.B. während eines ICE Neustarts.
certificate RTCCertificateStats Statistiken über ein Zertifikat, das von einem RTCIceTransport verwendet wird.
codec RTCCodecStats Statistiken über einen spezifischen Codec, der von den von dieser Verbindung gesendeten oder empfangenen Streams verwendet wird.
data-channel RTCDataChannelStats Statistiken, die sich auf einen RTCDataChannel in der Verbindung beziehen.
inbound-rtp RTCInboundRtpStreamStats Statistiken, die den Zustand eines der eingehenden Datenströme der Verbindung beschreiben.
local-candidate RTCIceCandidateStats Statistiken über einen lokalen ICE-Kandidaten, der mit den RTCIceTransport der Verbindung verbunden ist.
media-source RTCAudioSourceStats oder RTCVideoSourceStats Statistiken über die Medien, die von der MediaStreamTrack erzeugt werden, die an einen RTP-Sender angehängt ist. Das Wörterbuch, dem dieser Schlüssel zugeordnet ist, hängt von der kind der Spur ab.
outbound-rtp RTCOutboundRtpStreamStats Statistiken, die den Zustand eines der ausgehenden Datenströme auf dieser Verbindung beschreiben.
peer-connection RTCPeerConnectionStats Statistiken, die den Zustand der RTCPeerConnection beschreiben.
remote-candidate RTCIceCandidateStats Statistiken über einen Remote-ICE-Kandidaten, der mit den RTCIceTransport der Verbindung verbunden ist.
remote-inbound-rtp RTCRemoteInboundRtpStreamStats Statistiken, die den Zustand des eingehenden Datenstroms aus der Perspektive des Remote-Peers beschreiben.
remote-outbound-rtp RTCRemoteOutboundRtpStreamStats Statistiken, die den Zustand des ausgehenden Datenstroms aus der Perspektive des Remote-Peers beschreiben.
transport RTCTransportStats Statistiken über einen Transport, der von der Verbindung verwendet wird.

Beispiele

Bericht von einer RTCPeerConnection mithilfe der forEach-Schleife iterieren

Dieses Beispiel zeigt, wie Sie videobezogene Statistiken für den lokalen RTCRtpReceiver, der für den Empfang von gestreamten Medien verantwortlich ist, protokollieren könnten.

Angenommen, Sie haben eine Variable myPeerConnection, die eine Instanz von RTCPeerConnection ist, dann verwendet der Code await, um auf den Statistikbericht zu warten, und iteriert ihn dann unter Verwendung von RTCStatsReport.forEach(). Er filtert dann die Wörterbücher für nur die Berichte, die den type von inbound-rtp und kind von video haben.

js
const stats = await myPeerConnection.getStats();

stats.forEach((report) => {
  if (report.type === "inbound-rtp" && report.kind === "video") {
    // Log the frame rate
    console.log(report.framesPerSecond);
  }
});

Bericht von einem RTCRtpSender mit einer for...of-Schleife iterieren

Dieses Beispiel zeigt, wie Sie die ausgehenden Statistiken von einem RTCRtpSender durchlaufen könnten.

Der Code folgt einem ähnlichen Muster wie das vorherige Beispiel, iteriert jedoch mit einer for...of-Schleife über die RTCStatsReport.values() und filtert den type von outbound-rtp. Es wird vorausgesetzt, dass Sie bereits ein RTCRtpSender-Objekt namens "sender" haben.

js
const stats = await sender.getStats();

for (const stat of stats.values()) {
  if (stat.type != "outbound-rtp") continue;
  Object.keys(stat).forEach((statName) => {
    console.log(`${statName}: ${report[statName]}`);
  });
}

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers
# rtcstatsreport-object

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
RTCStatsReport
[Symbol.iterator]
entries
forEach
get
has
keys
size
candidate-pair stats
availableOutgoingBitrate in 'candidate-pair' stats
bytesDiscardedOnSend in 'candidate-pair' stats
Experimental
bytesReceived in 'candidate-pair' stats
bytesSent in 'candidate-pair' stats
consentRequestsSent in 'candidate-pair' stats
Experimental
currentRoundTripTime in 'candidate-pair' stats
id in 'candidate-pair' stats
lastPacketReceivedTimestamp in 'candidate-pair' stats
lastPacketSentTimestamp in 'candidate-pair' stats
localCandidateId in 'candidate-pair' stats
nominated in 'candidate-pair' stats
packetsDiscardedOnSend in 'candidate-pair' stats
Experimental
packetsReceived in 'candidate-pair' stats
Experimental
packetsSent in 'candidate-pair' stats
Experimental
priority in 'candidate-pair' stats
DeprecatedNon-standard
remoteCandidateId in 'candidate-pair' stats
requestsReceived in 'candidate-pair' stats
requestsSent in 'candidate-pair' stats
responsesReceived in 'candidate-pair' stats
responsesSent in 'candidate-pair' stats
state in 'candidate-pair' stats
timestamp in 'candidate-pair' stats
totalRoundTripTime in 'candidate-pair' stats
transportId in 'candidate-pair' stats
type in 'candidate-pair' stats
certificate stats
base64Certificate in 'certificate' stats
fingerprint in 'certificate' stats
fingerprintAlgorithm in 'certificate' stats
id in 'certificate' stats
timestamp in 'certificate' stats
type in 'certificate' stats
codec stats
channels in 'codec' stats
clockRate in 'codec' stats
id in 'codec' stats
mimeType in 'codec' stats
payloadType in 'codec' stats
sdpFmtpLine in 'codec' stats
timestamp in 'codec' stats
transportId in 'codec' stats
type in 'codec' stats
data-channel stats
bytesReceived in 'data-channel' stats
bytesSent in 'data-channel' stats
dataChannelIdentifier in 'data-channel' stats
id in 'data-channel' stats
label in 'data-channel' stats
messagesReceived in 'data-channel' stats
messagesSent in 'data-channel' stats
protocol in 'data-channel' stats
state in 'data-channel' stats
timestamp in 'data-channel' stats
type in 'data-channel' stats
inbound-rtp stats
audioLevel in 'inbound-rtp' stats
bytesReceived in 'inbound-rtp' stats
codecId in 'inbound-rtp' stats
concealedSamples in 'inbound-rtp' stats
concealmentEvents in 'inbound-rtp' stats
fecPacketsDiscarded in 'inbound-rtp' stats
fecPacketsReceived in 'inbound-rtp' stats
frameHeight in 'inbound-rtp' stats
frameWidth in 'inbound-rtp' stats
framesDecoded in 'inbound-rtp' stats
framesPerSecond in 'inbound-rtp' stats
framesReceived in 'inbound-rtp' stats
headerBytesReceived in 'inbound-rtp' stats
id in 'inbound-rtp' stats
insertedSamplesForDeceleration in 'inbound-rtp' stats
jitter in 'inbound-rtp' stats
jitterBufferDelay in 'inbound-rtp' stats
jitterBufferEmittedCount in 'inbound-rtp' stats
jitterBufferMinimumDelay in 'inbound-rtp' stats
Experimental
jitterBufferTargetDelay in 'inbound-rtp' stats
Experimental
keyFramesDecoded in 'inbound-rtp' stats
Experimental
kind in 'inbound-rtp' stats
lastPacketReceivedTimestamp in 'inbound-rtp' stats
mid in 'inbound-rtp' stats
nackCount in 'inbound-rtp' stats
packetsDiscarded in 'inbound-rtp' stats
packetsLost in 'inbound-rtp' stats
packetsReceived in 'inbound-rtp' stats
playoutId in 'inbound-rtp' stats
Experimental
qpSum in 'inbound-rtp' stats
type_inbound-rtp.remoteId
removedSamplesForAcceleration in 'inbound-rtp' stats
silentConcealedSamples in 'inbound-rtp' stats
ssrc in 'inbound-rtp' stats
timestamp in 'inbound-rtp' stats
totalAudioEnergy in 'inbound-rtp' stats
totalDecodeTime in 'inbound-rtp' stats
totalInterFrameDelay in 'inbound-rtp' stats
totalProcessingDelay in 'inbound-rtp' stats
totalSamplesDuration in 'inbound-rtp' stats
totalSamplesReceived in 'inbound-rtp' stats
totalSquaredInterFrameDelay in 'inbound-rtp' stats
trackIdentifier in 'inbound-rtp' stats
transportId in 'inbound-rtp' stats
type in 'inbound-rtp' stats
local-candidate stats
address in 'local-candidate' stats
candidateType in 'local-candidate' stats
foundation in 'local-candidate' stats
Experimental
id in 'local-candidate' stats
port in 'local-candidate' stats
priority in 'local-candidate' stats
protocol in 'local-candidate' stats
timestamp in 'local-candidate' stats
transportId in 'local-candidate' stats
type in 'local-candidate' stats
usernameFragment in 'local-candidate' stats
Experimental
media-playout stats
id in 'media-playout' stats
Experimental
kind in 'media-playout' stats
Experimental
synthesizedSamplesDuration in 'media-playout' stats
Experimental
synthesizedSamplesEvents in 'media-playout' stats
Experimental
timestamp in 'media-playout' stats
Experimental
totalPlayoutDelay in 'media-playout' stats
Experimental
totalSamplesCount in 'media-playout' stats
Experimental
totalSamplesDuration in 'media-playout' stats
Experimental
type in 'media-playout' stats
Experimental
media-source stats
audioLevel in 'media-source' stats
Experimental
frames in 'media-source' stats for video
framesPerSecond in 'media-source' stats for video
height in 'media-source' stats for video
id in 'media-source' stats
kind in 'media-source' stats
timestamp in 'media-source' stats
totalAudioEnergy in 'media-source' stats
Experimental
totalSamplesDuration in 'media-source' stats
Experimental
trackIdentifier in 'media-source' stats
type in 'media-source' stats
width in 'media-source' stats for video
outbound-rtp stats
active in 'outbound-rtp' stats
Experimental
bytesSent in 'outbound-rtp' stats
codecId in 'outbound-rtp' stats
frameHeight in 'outbound-rtp' stats
frameWidth in 'outbound-rtp' stats
framesEncoded in 'outbound-rtp' stats
framesPerSecond in 'outbound-rtp' stats
framesSent in 'outbound-rtp' stats
headerBytesSent in 'outbound-rtp' stats
id in 'outbound-rtp' stats
keyFramesEncoded in 'outbound-rtp' stats
Experimental
kind in 'outbound-rtp' stats
mediaSourceId in 'outbound-rtp' stats
mid in 'outbound-rtp' stats
nackCount in 'outbound-rtp' stats
packetsSent in 'outbound-rtp' stats
qpSum in 'outbound-rtp' stats
qualityLimitationDurations in 'outbound-rtp' stats
Experimental
qualityLimitationReason in 'outbound-rtp' stats
Experimental
remoteId in 'outbound-rtp' stats
retransmittedBytesSent in 'outbound-rtp' stats
retransmittedPacketsSent in 'outbound-rtp' stats
rid in 'outbound-rtp' stats
scalabilityMode in 'outbound-rtp' stats
Experimental
ssrc in 'outbound-rtp' stats
targetBitrate in 'outbound-rtp' stats
timestamp in 'outbound-rtp' stats
totalEncodeTime in 'outbound-rtp' stats
totalEncodedBytesTarget in 'outbound-rtp' stats
Experimental
totalPacketSendDelay in 'outbound-rtp' stats
transportId in 'outbound-rtp' stats
type in 'outbound-rtp' stats
peer-connection stats
dataChannelsClosed in 'peer-connection' stats
dataChannelsOpened in 'peer-connection' stats
id in 'peer-connection' stats
timestamp in 'peer-connection' stats
type in 'peer-connection' stats
remote-candidate stats
address in 'remote-candidate' stats
candidateType in 'remote-candidate' stats
foundation in 'remote-candidate' stats
Experimental
id in 'remote-candidate' stats
port in 'remote-candidate' stats
priority in 'remote-candidate' stats
protocol in 'remote-candidate' stats
timestamp in 'remote-candidate' stats
transportId in 'remote-candidate' stats
type in 'remote-candidate' stats
usernameFragment in 'remote-candidate' stats
Experimental
remote-inbound-rtp stats
codecId in 'remote-inbound-rtp' stats
fractionLost in 'remote-inbound-rtp' stats
id in 'remote-inbound-rtp' stats
jitter in 'remote-inbound-rtp' stats
kind in 'remote-inbound-rtp' stats
localId in 'remote-inbound-rtp' stats
packetsLost in 'remote-inbound-rtp' stats
packetsReceived in 'remote-inbound-rtp' stats
Experimental
roundTripTime in 'remote-inbound-rtp' stats
roundTripTimeMeasurements in 'remote-inbound-rtp' stats
ssrc in 'remote-inbound-rtp' stats
timestamp in 'remote-inbound-rtp' stats
totalRoundTripTime in 'remote-inbound-rtp' stats
transportId in 'remote-inbound-rtp' stats
type in 'remote-inbound-rtp' stats
remote-outbound-rtp stats
bytesSent in 'remote-outbound-rtp' stats
codecId in 'remote-outbound-rtp' stats
id in 'remote-outbound-rtp' stats
kind in 'remote-outbound-rtp' stats
localId in 'remote-outbound-rtp' stats
packetsSent in 'remote-outbound-rtp' stats
remoteTimestamp in 'remote-outbound-rtp' stats
reportsSent in 'remote-outbound-rtp' stats
Experimental
roundTripTimeMeasurements in 'remote-outbound-rtp' stats
Experimental
ssrc in 'remote-outbound-rtp' stats
timestamp in 'remote-outbound-rtp' stats
totalRoundTripTime in 'remote-outbound-rtp' stats
Experimental
transportId in 'remote-outbound-rtp' stats
type in 'remote-outbound-rtp' stats
transport stats
bytesReceived in 'transport' stats
bytesSent in 'transport' stats
dtlsCipher in 'transport' stats
dtlsRole in 'transport' stats
Experimental
dtlsState in 'transport' stats
iceLocalUsernameFragment in 'transport' stats
Experimental
iceRole in 'transport' stats
Experimental
iceState in 'transport' stats
Experimental
id in 'transport' stats
localCertificateId in 'transport' stats
packetsReceived in 'transport' stats
Experimental
packetsSent in 'transport' stats
Experimental
remoteCertificateId in 'transport' stats
selectedCandidatePairChanges in 'transport' stats
selectedCandidatePairId in 'transport' stats
srtpCipher in 'transport' stats
timestamp in 'transport' stats
tlsVersion in 'transport' stats
type in 'transport' stats
values

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
Uses a non-standard name.
Requires a vendor prefix or different name for use.
Has more compatibility info.

Siehe auch