PerformanceServerTiming.description — Eigenschaft · JavaScript-Referenz

Signatur

PerformanceServerTiming.description

Beschreibung

Die Eigenschaft description eines PerformanceServerTiming-Objekts liefert den lesbaren Beschreibungstext einer Server-Metrik. Der Server legt ihn im HTTP-Antwort-Header Server-Timing über den Parameter desc fest, z. B. Server-Timing: db;dur=53;desc="Datenbankabfrage". Fehlt desc, ist der Wert eine leere Zeichenkette "".

An die PerformanceServerTiming-Einträge kommt man über die Eigenschaft serverTiming von PerformanceResourceTiming- und PerformanceNavigationTiming-Einträgen. Zusammen mit name und duration lassen sich damit Backend-Messwerte (Datenbank, Cache, Rendering auf dem Server) direkt im Browser auswerten, etwa für Real-User-Monitoring (RUM) oder eigene Dashboards.

Da description für Menschen gedacht ist, eignet es sich für Anzeige und Logging. Für die maschinelle Auswertung sollte man eher den stabilen name verwenden, weil sich Beschreibungstexte leichter ändern.

Rückgabewert

Typ

string

Beschreibung

Der Wert des desc-Parameters aus dem Server-Timing-Header oder "", wenn keine Beschreibung angegeben wurde.

Beispiele

Server-Metriken der Navigation auslesen

// Server-Header: Server-Timing: db;dur=53;desc="Datenbankabfrage", cache;desc="Cache-Treffer"
const [navigation] = performance.getEntriesByType('navigation');

for (const metric of navigation.serverTiming) {
  console.log(`${metric.name}: ${metric.description || '(keine Beschreibung)'} – ${metric.duration} ms`);
}

db: Datenbankabfrage – 53 ms cache: Cache-Treffer – 0 ms

Neue Ressourcen mit PerformanceObserver überwachen

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    for (const { name, description, duration } of entry.serverTiming) {
      console.log(entry.name, { name, description, duration });
    }
  }
});

observer.observe({ type: 'resource', buffered: true });

// Löst einen Eintrag aus, sobald die Antwort vorliegt
await fetch('/api/produkte');

https://example.com/api/produkte { name: 'app', description: 'Anwendungslogik', duration: 12.4 }

Beschreibungen für ein RUM-Beacon sammeln

const collectServerTimings = () =>
  performance.getEntriesByType('resource')
    .flatMap((entry) => entry.serverTiming.map((m) => ({
      url: entry.name,
      metric: m.name,
      label: m.description.trim() || m.name, // Fallback auf den Namen
      ms: m.duration
    })));

addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    navigator.sendBeacon('/rum', JSON.stringify(collectServerTimings()));
  }
});

// Wichtig · Fallstricke

Cross-Origin: Bei Ressourcen von fremden Origins ist serverTiming ein leeres Array, außer der Server sendet Timing-Allow-Origin (z. B. Timing-Allow-Origin: https://example.com).
Nur sichere Kontexte: Die Server-Timing-Daten gibt es nur über HTTPS (bzw. localhost).
Leere Zeichenkette statt null: Ohne desc ist der Wert "". Deshalb mit || oder trim() prüfen, nicht mit ?? .
Datenschutz/Sicherheit: Der Header ist für jeden Client lesbar. Keine internen Details wie Hostnamen, SQL-Abfragen oder Benutzerdaten in desc schreiben. Beschreibungen nicht ungeprüft per innerHTML ausgeben, lieber textContent verwenden.
Werte mit Leerzeichen oder Sonderzeichen muss der Server in Anführungszeichen setzen (desc="Mein Text"), sonst wird der Header womöglich falsch geparst.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden ignoriert und lösen im Strict Mode keinen Fehler aus.

Siehe auch

PerformanceEventTiming.target PerformanceServerTiming.duration PerformanceServerTiming.name PerformanceEventTiming.interactionId PerformanceScriptTiming.pauseDuration