RTCStatsReport.entries() — Methode · JavaScript-Referenz

Signatur

RTCStatsReport.prototype.entries()

Beschreibung

Die Methode entries() des Interfaces RTCStatsReport gibt ein neues Iterator-Objekt zurück. Es liefert für jedes Statistik-Objekt im Bericht ein Array [schlüssel, wert]. Der Schlüssel ist die eindeutige Statistik-ID (stats.id), der Wert ist das zugehörige Statistik-Wörterbuch, z. B. vom Typ inbound-rtp, outbound-rtp, candidate-pair oder transport.

RTCStatsReport ist ein Map-ähnliches, schreibgeschütztes Objekt. entries() verhält sich deshalb genauso wie Map.prototype.entries() und ist auch der Standard-Iterator des Berichts (report[Symbol.iterator]). Ein for...of direkt über den Bericht liefert also dieselben Paare.

Die Methode brauchen Sie, wenn Sie beim Auswerten von RTCPeerConnection.getStats(), RTCRtpSender.getStats() oder RTCRtpReceiver.getStats() gleichzeitig ID und Inhalt benötigen. Das ist z. B. beim Auflösen von Verweisen wie transportId, codecId oder localCandidateId nützlich, beim Aufbauen einer eigenen Nachschlagetabelle oder beim Umwandeln in ein einfaches Objekt mit Object.fromEntries().

Rückgabewert

Typ

Iterator<[string, object]>

Beschreibung

Ein neuer Map-Iterator, der für jeden Eintrag ein Array [id, stats] liefert: id ist ein string, stats ein Statistik-Wörterbuch mit mindestens id, type und timestamp.

Beispiele

Alle Statistik-Einträge einer Verbindung auflisten

const pc = new RTCPeerConnection();
pc.createDataChannel('probe');

const report = await pc.getStats();

for (const [id, stats] of report.entries()) {
  console.log(`${id} → ${stats.type} @ ${stats.timestamp.toFixed(0)}`);
}

PC_xyz → peer-connection @ 1718000000000 DC_1 → data-channel @ 1718000000000 ...

Aktives Kandidatenpaar und Round-Trip-Zeit ermitteln

const getRtt = async (pc) => {
  const report = await pc.getStats();
  // Nachschlagetabelle aus den Einträgen aufbauen
  const byId = new Map(report.entries());

  for (const [, stats] of report.entries()) {
    if (stats.type === 'transport' && stats.selectedCandidatePairId) {
      const pair = byId.get(stats.selectedCandidatePairId);
      return pair?.currentRoundTripTime ?? null; // Sekunden
    }
  }
  return null;
};

const rtt = await getRtt(pc);
console.log('RTT:', rtt !== null ? `${(rtt * 1000).toFixed(1)} ms` : 'unbekannt');

RTT: 23.4 ms

Bericht als JSON speichern oder übertragen

const report = await pc.getStats();

// RTCStatsReport lässt sich nicht direkt serialisieren – daher entries() nutzen
const plain = Object.fromEntries(report.entries());
const json = JSON.stringify(plain);

await fetch('/api/webrtc-stats', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: json
});
console.log(`${Object.keys(plain).length} Einträge gesendet`);

14 Einträge gesendet

Eingehende Video-Statistiken filtern

const report = await pc.getStats();

const inboundVideo = [...report.entries()]
  .filter(([, s]) => s.type === 'inbound-rtp' && s.kind === 'video')
  .map(([id, s]) => ({ id, fps: s.framesPerSecond, lost: s.packetsLost }));

console.table(inboundVideo);

┌─────────┬───────────────┬─────┬──────┐ │ (index) │ id │ fps │ lost │ │ 0 │ 'IT01V1234' │ 30 │ 2 │ └─────────┴───────────────┴─────┴──────┘

// Wichtig · Fallstricke

Einmal verwendbar: Der zurückgegebene Iterator ist nach einem Durchlauf erschöpft. Wenn Sie mehrfach iterieren möchten, rufen Sie entries() erneut auf oder wandeln Sie ihn mit [...report.entries()] in ein Array um.
Momentaufnahme: Ein RTCStatsReport ändert sich nicht. Für aktuelle Werte, etwa zum Berechnen einer Bitrate aus zwei bytesReceived-Werten, müssen Sie getStats() regelmäßig neu aufrufen.
Schreibgeschützt: Anders als bei Map gibt es kein set(), delete() oder clear().
Reihenfolge und IDs: Die Reihenfolge der Einträge und das Format der IDs legt der Browser fest und sie unterscheiden sich zwischen den Engines. Filtern Sie deshalb immer nach type und verlassen Sie sich nicht auf Position oder ID-Muster.
Kompatibilität: Sehr alte Chrome-Versionen (vor 58) hatten ein veraltetes, callback-basiertes getStats() ohne Map-Schnittstelle. Welche Statistik-Felder vorhanden sind (z. B. framesPerSecond, selectedCandidatePairId), unterscheidet sich je nach Browser. Prüfen Sie Felder daher vor der Verwendung, etwa mit ?. oder ??.
Datenschutz: ICE-Kandidaten-Statistiken können lokale oder öffentliche IP-Adressen enthalten. Entfernen Sie diese, bevor Sie Berichte an einen Server senden.

Siehe auch

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