WebTransport.getStats() — Methode · JavaScript-Referenz

Signatur

WebTransport.prototype.getStats()

Beschreibung

getStats() fragt Kennzahlen der HTTP/3-/QUIC-Verbindung ab, auf der eine WebTransport-Sitzung läuft. Der Rückgabewert ist ein Promise, das mit einem WebTransportConnectionStats-Objekt erfüllt wird. Es enthält eine Momentaufnahme der Verbindung zum Zeitpunkt des Aufrufs.

Typische Felder sind:

bytesSent, packetsSent: gesendete Bytes und Pakete (inkl. Neuübertragungen)
bytesReceived, packetsReceived: empfangene Bytes und Pakete
packetsLost: als verloren gewertete Pakete
numOutgoingStreamsCreated, numIncomingStreamsCreated: Anzahl der erzeugten Streams
smoothedRtt, rttVariation, minRtt: Round-Trip-Zeiten in Millisekunden
estimatedSendRate: geschätzte Senderate in Bit/s (kann null sein)
datagrams: ein WebTransportDatagramStats-Objekt mit droppedIncoming, expiredOutgoing und lostOutgoing

Die Methode eignet sich für Monitoring, adaptive Qualitätssteuerung (z. B. Bitrate bei Streaming oder Cloud-Gaming anpassen), Debugging-Overlays und Telemetrie. Weil jeder Aufruf nur eine Momentaufnahme liefert, fragt man in der Praxis in festen Abständen ab und berechnet die Differenz zwischen zwei Messungen, um Raten zu bekommen.

Welche Felder genau vorhanden sind, hängt vom Browser und von der Version der Spezifikation ab. Die Spezifikation ist noch in Arbeit, deshalb solltest du fehlende Felder immer abfangen.

Rückgabewert

Typ

Promise<WebTransportConnectionStats>

Beschreibung

Ein Promise, das mit einem Objekt voller Verbindungsstatistiken erfüllt wird. Ist die Verbindung fehlgeschlagen, wird es mit einer DOMException vom Typ InvalidStateError abgelehnt.

Beispiele

Statistiken einmalig abfragen

const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;

const stats = await transport.getStats();
console.log(`Gesendet: ${stats.bytesSent} Bytes in ${stats.packetsSent} Paketen`);
console.log(`Empfangen: ${stats.bytesReceived} Bytes`);
console.log(`RTT (geglättet): ${stats.smoothedRtt} ms`);

Gesendet: 1532 Bytes in 7 Paketen Empfangen: 2048 Bytes RTT (geglättet): 23.4 ms

Durchsatz regelmäßig messen (Differenz zwischen zwei Messungen)

const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;

let last = await transport.getStats();
let lastTime = performance.now();

const timer = setInterval(async () => {
  try {
    const now = await transport.getStats();
    const t = performance.now();
    const seconds = (t - lastTime) / 1000;
    const kbitIn = ((now.bytesReceived - last.bytesReceived) * 8) / 1000 / seconds;
    const lossRate = now.packetsSent > 0 ? (now.packetsLost / now.packetsSent) * 100 : 0;
    console.log(`Eingang: ${kbitIn.toFixed(1)} kbit/s, Verlust: ${lossRate.toFixed(2)} %`);
    last = now;
    lastTime = t;
  } catch (err) {
    console.warn('Statistiken nicht verfügbar:', err.name);
    clearInterval(timer);
  }
}, 1000);

// Beim Schließen der Sitzung das Polling beenden
transport.closed.finally(() => clearInterval(timer));

Eingang: 812.4 kbit/s, Verlust: 0.35 %

Datagramm-Statistiken mit Feature-Erkennung auswerten

const logDatagramStats = async (transport) => {
  if (typeof transport.getStats !== 'function') {
    console.log('getStats() wird nicht unterstützt');
    return;
  }
  const { datagrams, estimatedSendRate } = await transport.getStats();
  if (datagrams) {
    console.table({
      verworfenEingehend: datagrams.droppedIncoming,
      abgelaufenAusgehend: datagrams.expiredOutgoing,
      verlorenAusgehend: datagrams.lostOutgoing
    });
  }
  console.log('Geschätzte Senderate:', estimatedSendRate ?? 'unbekannt', 'bit/s');
};

const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;
await logDatagramStats(transport);

Geschätzte Senderate: 2400000 bit/s

// Wichtig · Fallstricke

Browser-Unterstützung: WebTransport und getStats() gibt es vor allem in Chromium-Browsern. Andere Engines unterstützen die Methode nur teilweise oder gar nicht. Prüfe deshalb vorher mit typeof transport.getStats === 'function'.
Felder können sich ändern: Die Spezifikation entwickelt sich noch weiter. Felder können fehlen, umbenannt sein oder null enthalten (etwa estimatedSendRate). Greife defensiv zu, zum Beispiel mit ?. und ??.
Zähler summieren sich auf: Werte wie bytesSent zählen seit Verbindungsbeginn mit. Für Raten musst du die Differenz zwischen zwei Aufrufen bilden.
Verbindungszustand: Rufe die Methode erst nach await transport.ready auf. Nach einem Verbindungsfehler wird das Promise mit InvalidStateError abgelehnt.
Leistung: Frage nicht in sehr kurzen Abständen ab (z. B. pro Frame). Ein Abstand von etwa einer Sekunde reicht für Monitoring meistens aus.
Nur in sicheren Kontexten (HTTPS) und in Workern verfügbar. Alle RTT-Werte sind in Millisekunden angegeben.

Siehe auch

WebTransport WebTransport.ready WebTransport.closed WebTransport.close() WebTransport.datagrams WebTransport.createBidirectionalStream() RTCPeerConnection.getStats()