PerformanceTimingConfidence — Schnittstelle · JavaScript-Referenz

Signatur

interface PerformanceTimingConfidence

Beschreibung

Die Schnittstelle PerformanceTimingConfidence sagt aus, wie verlässlich die Zeitmessungen eines Leistungseintrags sind. Der Browser weiß oft besser als die Seite selbst, ob ein Seitenaufruf unter normalen Bedingungen stattfand oder durch äußere Umstände verlangsamt wurde, etwa durch einen Kaltstart des Browsers, eine stark belastete Maschine oder eine wiederhergestellte Sitzung. Für solche Fälle meldet er eine niedrige Verlässlichkeit.

Eine eigene Instanz erzeugt man nicht. Man liest sie über die Eigenschaft confidence eines PerformanceNavigationTiming-Eintrags aus. Sie hat zwei Eigenschaften, die nur gelesen werden können:

value: "high" oder "low". Das ist die Einschätzung, wie repräsentativ die Messung ist.
randomizedTriggerRate: eine Zahl zwischen 0 und 1. Sie gibt an, mit welcher Wahrscheinlichkeit value zufällig gesetzt wurde, statt die echte Einschätzung wiederzugeben.

Dazu kommt die Methode toJSON(), die beide Werte als einfaches Objekt zurückgibt.

Die Schnittstelle ist vor allem für Real User Monitoring (RUM) gedacht. Messungen mit "low" kann man getrennt auswerten oder herausfiltern, damit Kennzahlen wie Ladezeit oder TTFB nicht durch Ausreißer verzerrt werden. Aus Datenschutzgründen wird value absichtlich verrauscht. Einzelne Werte sind deshalb nicht verlässlich. Belastbar sind nur statistisch ausgewertete Mengen, bei denen die Zufallsrate herausgerechnet wird.

Parameter

Name	Typ	Beschreibung
$value Pflicht	"high" \| "low"	Eigenschaft, die nur gelesen werden kann: Einschätzung des Browsers, ob die Messung typisch (`"high"`) oder durch äußere Faktoren beeinflusst ist (`"low"`).
$randomizedTriggerRate Pflicht	number	Eigenschaft, die nur gelesen werden kann: Wahrscheinlichkeit von 0 bis 1, mit der `value` zufällig bestimmt wurde. Wird für die statistische Korrektur beim Auswerten gebraucht.
$toJSON()	() => { value: string, randomizedTriggerRate: number }	Methode, die ein einfaches Objekt mit beiden Eigenschaften zurückgibt, z. B. zum Versand an einen Analyse-Server.

Rückgabewert

Typ

PerformanceTimingConfidence

Beschreibung

Erreichbar über PerformanceNavigationTiming.confidence. Ist die Funktion nicht unterstützt, ist die Eigenschaft undefined.

Beispiele

Verlässlichkeit des aktuellen Seitenaufrufs auslesen

const [nav] = performance.getEntriesByType('navigation');

if (nav?.confidence) {
  const { value, randomizedTriggerRate } = nav.confidence;
  console.log(`Verlässlichkeit: ${value}`);
  console.log(`Zufallsrate: ${randomizedTriggerRate}`);
} else {
  console.log('PerformanceTimingConfidence wird nicht unterstützt');
}

Verlässlichkeit: high Zufallsrate: 0.1

RUM-Daten zusammen mit der Verlässlichkeit senden

const reportNavigation = () => {
  const [nav] = performance.getEntriesByType('navigation');
  if (!nav) return;

  const payload = {
    url: location.pathname,
    ttfb: Math.round(nav.responseStart - nav.startTime),
    loadTime: Math.round(nav.loadEventEnd - nav.startTime),
    // toJSON() liefert { value, randomizedTriggerRate }
    confidence: nav.confidence?.toJSON() ?? null
  };

  navigator.sendBeacon('/rum', JSON.stringify(payload));
};

addEventListener('pagehide', reportNavigation, { once: true });

Auf dem Server: tatsächlichen Anteil von "high" schätzen

// Das Verrauschen wird herausgerechnet. Die Formel setzt voraus,
// dass ein zufällig gesetzter Wert zu 50 % "high" und zu 50 % "low" ist.
const estimateHighShare = (records) => {
  const n = records.length;
  if (n === 0) return null;
  const observedHigh = records.filter(r => r.confidence.value === 'high').length / n;
  const rate = records[0].confidence.randomizedTriggerRate;
  const p = (observedHigh - rate / 2) / (1 - rate);
  return Math.min(1, Math.max(0, p));
};

const records = [
  { confidence: { value: 'high', randomizedTriggerRate: 0.1 } },
  { confidence: { value: 'high', randomizedTriggerRate: 0.1 } },
  { confidence: { value: 'low', randomizedTriggerRate: 0.1 } },
  { confidence: { value: 'high', randomizedTriggerRate: 0.1 } }
];

console.log(estimateHighShare(records).toFixed(3));

0.778

// Wichtig · Fallstricke

Experimentell: Die Schnittstelle gibt es bisher nur in Chromium-basierten Browsern. Firefox und Safari unterstützen sie nicht. Vor dem Zugriff immer prüfen, ob sie vorhanden ist, z. B. mit nav.confidence?.value. Die Spezifikation kann sich noch ändern.
Absichtlich verrauscht: Mit der Wahrscheinlichkeit randomizedTriggerRate ist value zufällig gesetzt. Entscheide deshalb nie anhand eines einzelnen Seitenaufrufs, z. B. zum Verwerfen oder Hervorheben einer Messung. Werte nur große Mengen aus und rechne die Zufallsrate heraus. Die Formel im dritten Beispiel setzt voraus, dass ein zufällig gesetzter Wert zu 50 % "high" und zu 50 % "low" ist. Das sollte mit der aktuellen Spezifikation abgeglichen werden.
Bisher gibt es sie nur für Navigationseinträge, also PerformanceNavigationTiming, und nicht für Ressourcen oder eigene Messungen.
"low" sagt nichts über die Qualität deines Codes aus. Es beschreibt Umstände, auf die die Seite keinen Einfluss hat, etwa einen Kaltstart des Browsers.
Die Werte stehen erst fest, wenn die Navigation abgeschlossen ist. Lies sie also am besten nach dem load-Ereignis oder beim pagehide-Ereignis aus.

Siehe auch

PerformanceTiming PerformanceNavigation PerformanceNavigationTiming PerformancePaintTiming PerformanceElementTiming