PressureRecord — Schnittstelle · JavaScript-Referenz

Signatur

interface PressureRecord

Beschreibung

PressureRecord ist Teil der Compute Pressure API. Ein solches Objekt beschreibt, in welchem Druckzustand sich eine Quelle (derzeit nur "cpu") zu einem bestimmten Zeitpunkt befindet. Du erzeugst es nie selbst: Ein PressureObserver liefert immer dann ein Array von PressureRecord-Objekten an seinen Callback, wenn sich der Zustand ändert. Mit takeRecords() kannst du noch nicht zugestellte Einträge auch direkt abholen.

Ein Eintrag hat drei schreibgeschützte Eigenschaften:

source: die beobachtete Quelle als String, derzeit "cpu".
state: der Druckzustand, einer der Werte "nominal", "fair", "serious" oder "critical".
time: ein DOMHighResTimeStamp (in Millisekunden, bezogen auf performance.timeOrigin), der den Zeitpunkt des Eintrags angibt.

Außerdem gibt die Methode toJSON() die Eigenschaften als einfaches Objekt zurück. Das ist praktisch zum Loggen oder um die Daten per postMessage() bzw. an einen Analyse-Endpunkt zu senden.

Einsatzbereiche sind Anwendungen, die ihre Last an die Systemauslastung anpassen, etwa Videokonferenzen (weniger Videokacheln, niedrigere Auflösung), Spiele (einfachere Effekte) oder Editoren (seltenere Live-Vorschau). Die Zustände sind absichtlich grob gehalten. Sie verraten keine exakten CPU-Werte, damit sich Nutzer nicht darüber identifizieren lassen (Fingerprinting).

Rückgabewert

Typ

PressureRecord

Beschreibung

Kein Konstruktor. Instanzen erhältst du nur über den Callback von PressureObserver oder über PressureObserver.prototype.takeRecords(). Eigenschaften: source (string), state ("nominal" | "fair" | "serious" | "critical") und time (DOMHighResTimeStamp).

Beispiele

CPU-Druck beobachten und Einträge ausgeben

if ('PressureObserver' in globalThis) {
  const observer = new PressureObserver((records) => {
    for (const record of records) {
      console.log(`${record.source}: ${record.state} @ ${record.time.toFixed(0)} ms`);
    }
  });

  try {
    // sampleInterval: gewünschter Mindestabstand zwischen Messungen in ms
    await observer.observe('cpu', { sampleInterval: 1000 });
  } catch (err) {
    console.warn('Compute Pressure nicht erlaubt:', err.name);
  }
} else {
  console.log('Compute Pressure API wird nicht unterstützt.');
}

cpu: nominal @ 1523 ms cpu: fair @ 8741 ms

Videoqualität an den Druckzustand anpassen

const qualityByState = {
  nominal: { width: 1280, fps: 30 },
  fair: { width: 960, fps: 30 },
  serious: { width: 640, fps: 24 },
  critical: { width: 320, fps: 15 }
};

const applyQuality = ({ width, fps }) => {
  console.log(`Setze Video auf ${width}px / ${fps} fps`);
  // hier z. B. track.applyConstraints({ width, frameRate: fps })
};

const observer = new PressureObserver((records) => {
  // Nur der jüngste Eintrag ist relevant
  const latest = records.at(-1);
  applyQuality(qualityByState[latest.state]);
});

await observer.observe('cpu', { sampleInterval: 2000 });

Setze Video auf 640px / 24 fps

Einträge per toJSON() serialisieren und mit takeRecords() abholen

const log = [];

const observer = new PressureObserver((records) => {
  log.push(...records.map((r) => r.toJSON()));
});

await observer.observe('cpu');

// Später, z. B. beim Verlassen der Seite
addEventListener('pagehide', () => {
  // Noch nicht zugestellte Einträge einsammeln
  const pending = observer.takeRecords().map((r) => r.toJSON());
  observer.disconnect();
  navigator.sendBeacon('/telemetry/pressure', JSON.stringify([...log, ...pending]));
});

console.log(JSON.stringify(log[0]));

{"source":"cpu","state":"nominal","time":1523.4}

// Wichtig · Fallstricke

Experimentell: Die API gibt es nur in Chromium-Browsern ab Version 125 (Desktop). Firefox und Safari unterstützen sie nicht. Prüfe vor der Nutzung immer mit 'PressureObserver' in globalThis, ob sie vorhanden ist. PressureObserver.knownSources nennt die unterstützten Quellen.

Die API funktioniert nur in einem sicheren Kontext (HTTPS). Sie steht in Window sowie in dedizierten und geteilten Workern zur Verfügung.
In iframes muss die Permissions Policy compute-pressure gesetzt sein (z. B. <iframe allow="compute-pressure">). Sonst schlägt observe() mit NotAllowedError fehl.
Einträge kommen nur, wenn die Seite sichtbar ist bzw. den Fokus hat. Hintergrund-Tabs bekommen in der Regel keine Updates.
Die Zustände sind grob und absichtlich ungenau. Der Browser kann Einträge verzögern oder zusammenfassen, und sampleInterval ist nur ein Wunsch, keine Garantie. Leite daraus keine exakten Prozentwerte oder Benchmarks ab.
Die Eigenschaften sind schreibgeschützt. time ist relativ zu performance.timeOrigin und kein Unix-Zeitstempel. Für absolute Zeit rechne performance.timeOrigin + record.time.
Pass deine Anpassungen mit Hysterese an: Reagiere z. B. nicht auf jeden kurzen Wechsel zwischen fair und serious, sonst flackert die Qualität.

Siehe auch

Performance.prototype.now() NDEFRecord PressureObserver CrashReport GestureEvent