Performance: measure()-Methode

Syntax

measure(measureName)
measure(measureName, startMark)
measure(measureName, startMark, endMark)
measure(measureName, measureOptions)
measure(measureName, measureOptions, endMark)

Wenn nur measureName angegeben ist, wird der Start-Zeitstempel auf null gesetzt, und der End-Zeitstempel (der zur Berechnung der Dauer verwendet wird) ist der Wert, der von Performance.now() zurückgegeben würde.

Sie können Zeichenfolgen verwenden, um PerformanceMark-Objekte als Start- und Endmarken zu identifizieren.

Um nur eine endMark bereitzustellen, müssen Sie ein leeres measureOptions-Objekt verwenden: performance.measure("myMeasure", {}, "myEndMarker").

Parameter

measureName

Ein String, der den Namen des Measure darstellt.

measureOptions Optional

Ein Objekt, das Messoptionen enthalten kann.

detail Optional

Beliebige Metadaten, die im Measure enthalten sein sollen. Standardmäßig null. Muss strukturiert klonbar sein.

devtools

Einige Browser verwenden ein strukturiertes devtools-Objekt innerhalb des detail-Objekts als Teil einer Erweiterungs-API, die diese in benutzerdefinierte Spuren in Leistungs-Traces einbindet. Weitere Informationen finden Sie in der Chrome's Extensibility API Dokumentation.

dataType

String mit einem Wert von track-entry (zum Definieren einer neuen Spur) oder marker (zum Definieren eines Eintrags in einer Spur).

color Optional

Standardmäßig "primary". Muss einer der folgenden Werte sein: "primary", "primary-light", "primary-dark", "secondary", "secondary-light", "secondary-dark", "tertiary", "tertiary-light", "tertiary-dark", "error".

track Optional

String des Namens der benutzerdefinierten Spur (erforderlich für track-entry).

trackGroup Optional

String des Namens der Gruppierung innerhalb einer benutzerdefinierten Spur (erforderlich für track-entry).

properties Optional

Array aus Schlüssel-Wert-Paaren. Werte können jeder JSON-kompatible Typ sein.

tooltipText Optional

Kurze Beschreibung für das Tooltip.

start Optional

Zeitstempel (DOMHighResTimeStamp), der als Startzeit verwendet werden soll, oder ein String, der den Namen einer PerformanceMark angibt, die als Startzeit verwendet werden soll.

Wenn dies ein String ist, der eine PerformanceMark benennt, dann ist er auf die gleiche Weise wie startMark definiert.

duration Optional

Dauer (in Millisekunden) zwischen den Start- und Endmarkenzeiten. Wenn weggelassen, ist dies standardmäßig performance.now(); die Zeit, die seit der Erstellung des Kontexts verstrichen ist. Wenn angegeben, müssen Sie entweder start oder end angeben, aber nicht beide.

end Optional

Zeitstempel (DOMHighResTimeStamp), der als Endzeit verwendet werden soll, oder ein String, der den Namen einer PerformanceMark angibt, die als Endzeit verwendet werden soll.

Wenn dies ein String ist, der eine PerformanceMark benennt, dann ist er auf die gleiche Weise wie endMark definiert.

startMark Optional

Ein String, der eine PerformanceMark in der Leistungszeitleiste benennt. Die PerformanceEntry.startTime-Eigenschaft dieser Marke wird zur Berechnung des Measure verwendet.

endMark Optional

Ein String, der eine PerformanceMark in der Leistungszeitleiste benennt. Die PerformanceEntry.startTime-Eigenschaft dieser Marke wird zur Berechnung des Measure verwendet. Wenn Sie dieses Argument übergeben möchten, müssen Sie entweder startMark oder ein leeres measureOptions-Objekt übergeben.

Rückgabewert

Der PerformanceMeasure-Eintrag, der erstellt wurde.

Das zurückgegebene Measure wird die folgenden Eigenschaftswerte haben:

• entryType - wird auf "measure" gesetzt.

• name - wird auf das name-Argument gesetzt.

• startTime - wird gesetzt auf:

  • einen timestamp, wenn in measureOptions.start angegeben.
  • den timestamp einer Startmarke, wenn in measureOptions.start oder startMark angegeben.
  • einen Zeitstempel berechnet aus measureOptions.end und measureOptions.duration (wenn measureOptions.start nicht angegeben wurde).
  • 0, wenn es nicht angegeben ist und nicht aus anderen Werten ermittelt werden kann.

• duration - wird auf einen DOMHighResTimeStamp gesetzt, der die Dauer des Measure ist, berechnet durch Subtraktion der startTime vom End-Zeitstempel.

  Der End-Zeitstempel ist einer der folgenden:

  • ein timestamp, wenn in measureOptions.end angegeben.
  • der timestamp einer Endmarke, wenn eine in measureOptions.end oder endMark angegeben ist.
  • ein Zeitstempel berechnet aus measureOptions.start und measureOptions.duration (wenn measureOptions.end nicht angegeben wurde).
  • der von Performance.now() zurückgegebene Wert, wenn keine Endmarke angegeben ist oder aus anderen Werten ermittelt werden kann.

• detail - wird auf den Wert gesetzt, der in measureOptions übergeben wurde.

Ausnahmen

TypeError

Dies kann in jedem Fall ausgelöst werden, in dem der Start, das Ende oder die Dauer möglicherweise mehrdeutig sind:

• Sowohl endMark als auch measureOptions sind angegeben.
• measureOptions ist mit duration angegeben, ohne start oder end anzugeben.
• measureOptions ist mit allen start, end und duration angegeben.

SyntaxError DOMException

Die benannte Marke existiert nicht.

• Eine Endmarke wird entweder mit endMark oder measureOptions.end angegeben, aber es gibt keine PerformanceMark im Leistungsbuffer mit dem übereinstimmenden Namen.
• Eine Endmarke wird entweder mit endMark oder measureOptions.end angegeben, aber sie kann nicht in eine Übereinstimmung mit einem schreibgeschützten Attribut in der PerformanceTiming-Schnittstelle umgewandelt werden.
• Eine Startmarke wird entweder mit startMark oder measureOptions.start angegeben, aber es gibt keine PerformanceMark im Leistungsbuffer mit dem übereinstimmenden Namen.
• Eine Startmarke wird entweder mit startMark oder measureOptions.start angegeben, aber sie kann nicht in eine Übereinstimmung mit einem schreibgeschützten Attribut in der PerformanceTiming-Schnittstelle umgewandelt werden.

DataCloneError DOMException

Der measureOptions.detail-Wert ist nicht-null und kann nicht mit dem HTML-Algorithmus "StructuredSerialize" serialisiert werden.

RangeError

Der measureOptions.detail-Wert ist nicht-null und der Speicher kann während der Serialisierung mit dem HTML-Algorithmus "StructuredSerialize" nicht zugeteilt werden.

Beispiele

Messen der Dauer zwischen benannten Markern

Angenommen, Sie haben zwei eigene Marker, "login-started" und "login-finished", können Sie eine Messung mit dem Namen "login-duration" erstellen, wie im folgenden Beispiel gezeigt. Das zurückgegebene PerformanceMeasure-Objekt stellt dann eine duration-Eigenschaft bereit, die Ihnen die vergangene Zeit zwischen den beiden Markern angibt.

const loginMeasure = performance.measure(
  "login-duration",
  "login-started",
  "login-finished",
);
console.log(loginMeasure.duration);

Messen der Dauer mit benutzerdefinierten Start- und Endzeiten

Um fortgeschrittenere Messungen durchzuführen, können Sie einen measureOptions-Parameter übergeben. Beispielsweise können Sie die event.timeStamp-Eigenschaft eines click-Events als Startzeit verwenden.

performance.measure("login-click", {
  start: myClickEvent.timeStamp,
  end: myMarker.startTime,
});

Zusätzliche Messdetails bereitstellen

Sie können die details-Eigenschaft verwenden, um zusätzliche Informationen jeglicher Art bereitzustellen. Vielleicht möchten Sie aufzeichnen, welches HTML-Element angeklickt wurde.

performance.measure("login-click", {
  detail: { htmlElement: myElement.id },
  start: myClickEvent.timeStamp,
  end: myMarker.startTime,
});

DevTools Extensibility API

Für Browser, die die Extensibility API unterstützen, können Sie den detail-Parameter verwenden, um weitere Details in einem devtools-Objekt bereitzustellen, das zur Anzeige in Leistungsprofilen verwendet wird:

const imageProcessingTimeStart = performance.now();

// ... later in your code

performance.measure("Image Processing Complete", {
  start: imageProcessingTimeStart,
  end: performance.now(),
  detail: {
    // This data appears in the "Summary"
    extraInfo: {
      imageId: "xyz-123",
      source: "cache",
      checkUrl: "https://example.com/check/xyz-123",
    },
    // The devtools object controls the track visualization
    devtools: {
      dataType: "track-entry",
      track: "Image Processing Tasks",
      trackGroup: "My Tracks",
      color: "tertiary-dark",
      properties: [
        ["Filter Type", "Gaussian Blur"],
        // Values can be objects, arrays, or other types
        ["Resize Dimensions", { w: 500, h: 300 }],
        // String values that are URLs get linkified
        ["Image URL", "https://example.com/img.png"],
      ],
      tooltipText: "Image processed successfully",
    },
  },
});

Spezifikationen

Browser-Kompatibilität