RTCStatsReport.keys() — Methode · JavaScript-Referenz

Signatur

RTCStatsReport.prototype.keys()

Beschreibung

Die Methode keys() eines RTCStatsReport gibt ein neues Iterator-Objekt zurück, das nacheinander die Schlüssel aller enthaltenen Einträge liefert. RTCStatsReport ist ein schreibgeschütztes, Map-ähnliches Objekt: Jeder Schlüssel ist die eindeutige id eines Statistik-Objekts (z. B. "RTCInboundRTPVideoStream_1234"). Der zugehörige Wert ist ein Statistik-Wörterbuch wie RTCInboundRtpStreamStats oder RTCIceCandidatePairStats.

Einen RTCStatsReport erhält man über RTCPeerConnection.getStats(), RTCRtpSender.getStats() oder RTCRtpReceiver.getStats(). keys() ist nützlich, wenn man nur die IDs braucht – etwa um zwei Berichte zu vergleichen, neu hinzugekommene oder verschwundene Statistik-Objekte zu erkennen oder später gezielt mit report.get(id) nachzuschlagen.

Die Methode verhält sich genau wie Map.prototype.keys(). Der Iterator lässt sich mit for...of, dem Spread-Operator oder Array.from() auslesen. Die Reihenfolge entspricht der Einfügereihenfolge, die der Browser beim Erstellen des Berichts festgelegt hat – daraus sollte man keine inhaltliche Bedeutung ableiten.

Rückgabewert

Typ

Iterator<string>

Beschreibung

Ein neuer Map-Iterator, der die Schlüssel (Statistik-IDs als string) aller Einträge des Berichts in Einfügereihenfolge liefert.

Beispiele

Alle Statistik-IDs einer Verbindung ausgeben

const pc = new RTCPeerConnection();
pc.createDataChannel('chat');
await pc.setLocalDescription(await pc.createOffer());

const report = await pc.getStats();

for (const id of report.keys()) {
  console.log(id);
}

z. B.: RTCCertificate_AB12... RTCDataChannel_1 RTCPeerConnection RTCTransport_0_1

IDs filtern und gezielt Werte nachschlagen

const logInboundVideo = async (pc) => {
  const report = await pc.getStats();
  const ids = [...report.keys()];

  for (const id of ids) {
    const stat = report.get(id);
    if (stat.type === 'inbound-rtp' && stat.kind === 'video') {
      console.log(`${id}: ${stat.framesDecoded} Frames dekodiert`);
    }
  }
};

// Aufruf, sobald eine aktive Verbindung besteht:
// await logInboundVideo(pc);

z. B.: IT01V1234: 1520 Frames dekodiert

Neue und verschwundene Statistik-Objekte erkennen

let previousIds = new Set();

const diffStats = async (pc) => {
  const report = await pc.getStats();
  const currentIds = new Set(report.keys());

  const added = [...currentIds].filter((id) => !previousIds.has(id));
  const removed = [...previousIds].filter((id) => !currentIds.has(id));

  if (added.length) console.log('Neu:', added);
  if (removed.length) console.log('Entfernt:', removed);

  previousIds = currentIds;
};

// Alle 2 Sekunden prüfen
const pc = new RTCPeerConnection();
const timer = setInterval(() => diffStats(pc), 2000);
// später: clearInterval(timer); pc.close();

z. B.: Neu: ['RTCPeerConnection', 'RTCTransport_0_1']

// Wichtig · Fallstricke

Iterator ist einmalig: Der zurückgegebene Iterator kann nur einmal durchlaufen werden. Für mehrfache Nutzung vorher mit [...report.keys()] in ein Array umwandeln.
Momentaufnahme: Ein RTCStatsReport ändert sich nach dem Erzeugen nicht mehr. Für aktuelle Werte muss getStats() erneut aufgerufen werden.
IDs sind browserspezifisch: Das Format der Schlüssel ist nicht standardisiert und unterscheidet sich zwischen Chrome, Firefox und Safari. Nicht auf Namensmuster verlassen – stattdessen die Eigenschaft type des Werts auswerten.
Nur Lesezugriff: Anders als bei Map gibt es kein set(), delete() oder clear().
Die Menge der gelieferten Statistik-Typen variiert je nach Browser und Verbindungszustand; vor der ICE-Verhandlung sind oft nur wenige Einträge vorhanden.

Siehe auch

RTCStatsReport RTCStatsReport.values() RTCStatsReport.entries() RTCStatsReport.get() RTCStatsReport.forEach() RTCPeerConnection.getStats() Map.prototype.keys()