RTCPeerConnectionStats — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCPeerConnectionStats extends RTCStats

Beschreibung

RTCPeerConnectionStats ist ein Dictionary der WebRTC-Statistik-API. Es beschreibt nicht einen einzelnen Medienstrom oder Transportweg, sondern die übergeordnete Peer-Verbindung als Ganzes. Du erzeugst es nicht selbst: Es steckt als Eintrag im RTCStatsReport, den RTCPeerConnection.getStats() zurückgibt. Erkennbar ist der Eintrag an type === "peer-connection". Pro Bericht gibt es genau einen solchen Eintrag.

Zusätzlich zu den geerbten RTCStats-Feldern (id, timestamp, type) enthält das Dictionary vor allem zwei Zähler: dataChannelsOpened und dataChannelsClosed. Beide zählen fortlaufend seit dem Anlegen der Verbindung. Aus der Differenz ergibt sich die Zahl der gerade offenen RTCDataChannel-Objekte.

Typische Einsatzfälle sind Monitoring-Dashboards, Diagnose-Logs und das Aufspüren von Lecks, z. B. wenn eine Anwendung ständig neue Datenkanäle öffnet und nie schließt. Für Medienqualität, also Bitrate, Paketverlust oder Jitter, brauchst du dagegen andere Statistiktypen wie inbound-rtp, outbound-rtp oder candidate-pair.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Eindeutige Kennung des Statistikobjekts innerhalb des Berichts (von `RTCStats` geerbt).
$timestamp Pflicht	DOMHighResTimeStamp		Zeitpunkt, zu dem die Werte erfasst wurden (von `RTCStats` geerbt).
$type Pflicht	string	"peer-connection"	Statistiktyp. Bei diesem Dictionary immer `"peer-connection"`.
$dataChannelsOpened	number		Wie oft ein `RTCDataChannel` seit Beginn der Verbindung in den Zustand `"open"` gewechselt ist.
$dataChannelsClosed	number		Wie oft ein Datenkanal seit Beginn der Verbindung den Zustand `"open"` wieder verlassen hat, also geschlossen wurde.

Rückgabewert

Typ

RTCPeerConnectionStats

Beschreibung

Wird nicht direkt zurückgegeben, sondern steckt als Wert im RTCStatsReport (einer Map), den RTCPeerConnection.getStats() liefert.

Beispiele

Peer-Connection-Statistik aus getStats() auslesen

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel("chat");

const report = await pc.getStats();

// Den einzigen Eintrag vom Typ "peer-connection" suchen
const pcStats = [...report.values()].find((s) => s.type === "peer-connection");

console.log(pcStats.type);
console.log("Geöffnet:", pcStats.dataChannelsOpened ?? "nicht unterstützt");
console.log("Geschlossen:", pcStats.dataChannelsClosed ?? "nicht unterstützt");

peer-connection Geöffnet: 0 Geschlossen: 0 // (0, solange noch keine Verbindung ausgehandelt ist)

Aktuell offene Datenkanäle regelmäßig überwachen

const monitorDataChannels = (pc, intervalMs = 5000) => {
  const timer = setInterval(async () => {
    if (pc.connectionState === "closed") {
      clearInterval(timer);
      return;
    }
    const report = await pc.getStats();
    for (const stats of report.values()) {
      if (stats.type !== "peer-connection") continue;
      const open = (stats.dataChannelsOpened ?? 0) - (stats.dataChannelsClosed ?? 0);
      console.log(`[${new Date().toLocaleTimeString()}] offene Datenkanäle: ${open}`);
      if (open > 50) console.warn("Mögliches Leck: sehr viele offene Datenkanäle!");
    }
  }, intervalMs);
  return () => clearInterval(timer);
};

// Nutzung
const pc = new RTCPeerConnection();
const stopMonitoring = monitorDataChannels(pc);
// später: stopMonitoring();

[14:02:10] offene Datenkanäle: 2

Statistik für ein Diagnose-Log serialisieren

const collectPeerConnectionStats = async (pc) => {
  const report = await pc.getStats();
  const entry = [...report.values()].find((s) => s.type === "peer-connection");
  if (!entry) return null;
  // Nur relevante Felder übernehmen
  const { id, timestamp, dataChannelsOpened, dataChannelsClosed } = entry;
  return { id, timestamp: Math.round(timestamp), dataChannelsOpened, dataChannelsClosed };
};

const pc = new RTCPeerConnection();
console.log(JSON.stringify(await collectPeerConnectionStats(pc)));

{"id":"P","timestamp":1718000000000,"dataChannelsOpened":0,"dataChannelsClosed":0}

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser und Safari liefern den Eintrag "peer-connection" samt Datenkanal-Zählern. Bei Firefox und bei älteren Versionen können einzelne Felder fehlen. Prüfe deshalb mit ?? oder in, ob ein Feld vorhanden ist.
Die Zähler sind kumulativ, laufen also seit Beginn der Verbindung hoch. Sie geben nicht direkt an, wie viele Kanäle gerade offen sind. Diese Zahl erhältst du erst als dataChannelsOpened - dataChannelsClosed.
Die älteren Felder dataChannelsRequested und dataChannelsAccepted wurden aus der Spezifikation entfernt. Verlass dich nicht auf sie.
Wenn du getStats(track) mit einem Track als Filter aufrufst, fehlt der Eintrag "peer-connection" unter Umständen. Rufe getStats() ohne Argument auf, wenn du die Verbindungsstatistik brauchst.
Der Wert von id ist browserspezifisch (z. B. "P" in Chrome). Suche den Eintrag deshalb immer über type, nicht über eine fest eingetragene ID.
Rufe getStats() nicht zu häufig auf, etwa nicht in jedem Animations-Frame. Die Abfrage kostet Rechenzeit. Ein Intervall von 1 bis 5 Sekunden reicht für Monitoring in der Regel aus.

Siehe auch

RTCPeerConnection RTCPeerConnection.prototype.getStats() RTCStatsReport RTCDataChannel RTCInboundRtpStreamStats RTCIceCandidatePairStats