RTCStatsReport

Instanzeigenschaften

RTCStatsReport.size

Gibt die Anzahl der Einträge im RTCStatsReport-Objekt zurück.

Instanzmethoden

RTCStatsReport.entries()

Gibt ein neues Iterator-Objekt zurück, das für jedes Element im RTCStatsReport-Objekt ein Array mit zwei Einträgen der Form [id, statistic-dictionary] enthält, in der Reihenfolge des Einfügens.

RTCStatsReport.forEach()

Ruft callbackFn einmal für jedes Schlüssel-Wert-Paar im RTCStatsReport-Objekt auf, in der Reihenfolge des Einfügens. Wenn für forEach ein thisArg-Parameter angegeben wird, dient er bei jedem Callback als this-Wert.

RTCStatsReport.get()

Gibt das der übergebenen id zugeordnete Statistik-Dictionary zurück oder undefined, wenn keines vorhanden ist.

RTCStatsReport.has()

Gibt einen booleschen Wert zurück, der angibt, ob das RTCStatsReport-Objekt ein der angegebenen id zugeordnetes Statistik-Dictionary enthält.

RTCStatsReport.keys()

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

RTCStatsReport.values()

Gibt ein neues Iterator-Objekt zurück, das die Werte (Statistikobjekte) für jedes Element im RTCStatsReport-Objekt enthält, in der Reihenfolge des Einfügens.

RTCStatsReport[Symbol.iterator]()

Gibt ein neues Iterator-Objekt zurück, das für jedes Element im RTCStatsReport-Objekt ein Array mit zwei Einträgen der Form [id, statistic-dictionary] enthält, in der Reihenfolge des Einfügens.

Beschreibung

Die Methoden RTCRtpReceiver.getStats(), RTCRtpSender.getStats() und RTCPeerConnection.getStats() geben jeweils eine Promise zurück, die mit einem RTCStatsReport erfüllt wird. Beim Aufruf von getStats() auf einer RTCPeerConnection können Sie angeben, ob Sie Statistiken für ausgehende Daten, eingehende Daten oder die gesamte Verbindung erhalten möchten. Die Varianten von getStats() für RTCRtpReceiver und RTCRtpSender geben dagegen nur Statistiken für eingehende beziehungsweise ausgehende Daten zurück.

Der Statistikbericht ist ein schreibgeschütztes Map-ähnliches Objekt: ein geordnetes Dictionary, dessen Schlüssel id-Zeichenfolgen sind, die das WebRTC-Objekt eindeutig identifizieren, das zur Erstellung einer bestimmten Statistik untersucht wurde. Der zugehörige Wert ist ein Dictionary-Objekt mit diesen Statistiken. Ein RTCStatsReport kann durchlaufen und wie eine schreibgeschützte Map verwendet werden.

Der Bericht kann viele verschiedene Kategorien von Statistiken enthalten, darunter Statistiken für eingehende und ausgehende Daten sowohl des lokalen als auch des entfernten Endpunkts der Peer-Verbindung sowie Informationen über verwendete Codecs, Zertifikate und Medien. Jede Statistikkategorie wird durch einen anderen Typ von Statistik-Dictionary-Objekt bereitgestellt, der anhand seiner Eigenschaft type identifiziert werden kann.

Gemeinsame Instanzeigenschaften

Alle Dictionary-Typen haben die folgenden Eigenschaften:

id

Eine Zeichenfolge, die das Objekt eindeutig identifiziert, das zur Erstellung der Statistiken überwacht wurde. Dieser Wert bleibt über mehrere Berichte hinweg mindestens für die Lebensdauer der Verbindung erhalten. Beachten Sie jedoch, dass die ID bei manchen Statistiken je nach Browser und bei späteren Verbindungen variieren kann, selbst wenn diese zum selben Peer führen.

timestamp

Ein hochauflösender Zeitstempel (DOMHighResTimeStamp), der angibt, wann die Messung erfolgte. Viele der gemeldeten Statistiken sind kumulative Werte. Mithilfe des Zeitstempels lassen sich Raten und Durchschnittswerte zwischen zwei beliebigen Berichten berechnen, unabhängig davon, in welchen Abständen die Berichte erstellt werden.

type

Eine Zeichenfolge, deren Wert den Typ der im Objekt enthaltenen Statistiken angibt, beispielsweise candidate-pair, inbound-rtp oder certificate. Die Statistiktypen und die zugehörigen Objekte sind unten aufgeführt.

Üblicherweise durchlaufen Sie einen RTCStatsReport mit forEach() oder einer for...of-Schleife und wählen mithilfe der Eigenschaft type die gewünschten Statistiken aus. Nachdem ein bestimmtes Statistikobjekt anhand seines type identifiziert wurde, können Sie seine Eigenschaft id bei einem späteren Aufruf von get() verwenden, um die entsprechende Statistik zu einem anderen Zeitpunkt abzurufen.

Mithilfe des Zeitstempels lassen sich Durchschnittswerte für Statistiken berechnen, deren Werte sich über die Lebensdauer einer Verbindung aufsummieren.

Die Statistiktypen

Die Werte von type und die zugehörigen Dictionaries sind nachstehend aufgeführt.

Beispiele

Bericht einer RTCPeerConnection mit forEach durchlaufen

Dieses Beispiel zeigt, wie Sie videobezogene Statistiken für den lokalen RTCRtpReceiver protokollieren können, der für den Empfang gestreamter Medien zuständig ist.

Gegeben ist die Variable myPeerConnection, eine Instanz von RTCPeerConnection. Der Code wartet mit await auf den Statistikbericht und durchläuft ihn anschließend mit RTCStatsReport.forEach(). Dabei filtert er die Dictionaries nach Berichten mit type gleich inbound-rtp und kind gleich video.

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 eines RTCRtpSender mit einer for...of-Schleife durchlaufen

Dieses Beispiel zeigt, wie Sie die Statistiken für ausgehende Daten eines RTCRtpSender durchlaufen können.

Der Code folgt einem ähnlichen Muster wie im vorherigen Beispiel, verwendet jedoch eine for...of-Schleife über RTCStatsReport.values() und filtert nach type gleich outbound-rtp. Dabei wird vorausgesetzt, dass bereits ein RTCRtpSender-Objekt namens „sender“ vorhanden ist.

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}: ${stat[statName]}`);
  });
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• WebRTC API
• RTCPeerConnection
• RTCPeerConnection.getStats(), RTCRtpReceiver.getStats() und RTCRtpSender.getStats()