RTCStatsReport

Instanzeigenschaften

RTCStatsReport.size

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

Gemeinsame Instanzeigenschaften

Alle Dictionary-Typen haben die folgenden Eigenschaften:

id

Ein String, der 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 bestehen. Beachten Sie jedoch, dass die ID bei manchen Statistiken je nach Browser und bei späteren Verbindungen variieren kann, selbst wenn die Verbindung zum selben Peer besteht.

timestamp

Ein hochauflösender Zeitstempel (DOMHighResTimeStamp), der angibt, wann die Stichprobe erfasst wurde. Viele der gemeldeten Statistiken sind kumulative Werte. Anhand des Zeitstempels lassen sich Raten und Durchschnittswerte zwischen zwei beliebigen Berichten bei jeder gewünschten Berichtsfrequenz berechnen.

type

Ein String, dessen Wert angibt, welche Art von Statistiken das Objekt enthält, 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 die gewünschten Statistiken anhand der Eigenschaft type aus. Nachdem Sie ein Statistikobjekt anhand seines type identifiziert haben, können Sie dessen Eigenschaft id bei einem späteren Aufruf von get() verwenden, um den Bericht zur selben Statistik zu einem anderen Zeitpunkt abzurufen.

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

Instanzmethoden

RTCStatsReport.entries()

Gibt ein neues Iterator-Objekt zurück, das für jeden Eintrag im RTCStatsReport-Objekt ein Array mit zwei Elementen der Form [id, statistic-dictionary] enthält, und zwar in der Reihenfolge, in der die Einträge eingefügt wurden.

RTCStatsReport.forEach()

Ruft callbackFn einmal für jedes Schlüssel-Wert-Paar im RTCStatsReport-Objekt auf, und zwar in der Reihenfolge, in der die Einträge eingefügt wurden. Wenn Sie forEach einen Parameter thisArg übergeben, wird dieser bei jedem Callback als this-Wert verwendet.

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 RTCStatsReport ein Statistik-Dictionary enthält, das der angegebenen id zugeordnet ist.

RTCStatsReport.keys()

Gibt ein neues Iterator-Objekt zurück, das die Schlüssel (IDs) aller Einträge im RTCStatsReport-Objekt enthält, und zwar in der Reihenfolge, in der die Einträge eingefügt wurden.

RTCStatsReport.values()

Gibt ein neues Iterator-Objekt zurück, das die Werte (Statistikobjekte) aller Einträge im RTCStatsReport-Objekt enthält, und zwar in der Reihenfolge, in der die Einträge eingefügt wurden.

RTCStatsReport[Symbol.iterator]()

Gibt ein neues Iterator-Objekt zurück, das für jeden Eintrag im RTCStatsReport-Objekt ein Array mit zwei Elementen der Form [id, statistic-dictionary] enthält, und zwar in der Reihenfolge, in der die Einträge eingefügt wurden.

Beschreibung

Die Methoden RTCRtpReceiver.getStats(), RTCRtpSender.getStats() und RTCPeerConnection.getStats() geben ein Promise zurück, das mit einem RTCStatsReport erfüllt wird. Beim Aufruf von getStats() für eine RTCPeerConnection können Sie festlegen, ob Sie Statistiken zu ausgehenden Daten, eingehenden Daten oder zur gesamten Verbindung abrufen möchten. Die getStats()-Varianten von RTCRtpReceiver und RTCRtpSender geben dagegen nur Statistiken zu eingehenden beziehungsweise ausgehenden Daten zurück.

Der Statistikbericht ist ein schreibgeschütztes, Map-ähnliches Objekt: ein geordnetes Dictionary, dessen Schlüssel id-Strings sind, die das WebRTC-Objekt eindeutig identifizieren, das für eine bestimmte Statistik untersucht wurde. Der jeweilige Wert ist ein Dictionary-Objekt mit diesen Statistiken. Sie können einen RTCStatsReport auf dieselbe Weise wie eine schreibgeschützte Map durchlaufen und verwenden.

Der Bericht kann zahlreiche Kategorien von Statistiken enthalten, darunter Statistiken zu eingehenden und ausgehenden Daten sowohl für die lokale als auch für die entfernte Seite der Peer-Verbindung sowie Informationen zu verwendeten Codecs, Zertifikaten und Medien. Jede Statistikkategorie wird durch einen eigenen Typ von Statistik-Dictionary-Objekt dargestellt, den Sie anhand seiner Eigenschaft type identifizieren können.

Statistiktypen

Die Werte von type und die zugehörigen Dictionary-Typen sind unten aufgeführt.

Beispiele

Bericht einer RTCPeerConnection mit einer forEach-Schleife 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.

Die Variable myPeerConnection enthält eine Instanz von RTCPeerConnection. Der Code wartet mit await auf den Statistikbericht und durchläuft ihn anschließend mit RTCStatsReport.forEach(). Dabei berücksichtigt er nur Dictionary-Objekte, deren Berichte den type-Wert inbound-rtp und den kind-Wert video haben.

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 zu ausgehenden 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 berücksichtigt nur Einträge mit dem type-Wert 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()