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 Startzeitstempel auf null gesetzt und der Endzeitstempel (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 bereitstellen: performance.measure("myMeasure", {}, "myEndMarker").

Parameter

measureName

Eine Zeichenfolge, die den Namen der Messung darstellt.

measureOptions Optional

Ein Objekt, das Messoptionen enthalten kann.

detail Optional

Beliebige Metadaten, die in die Messung einbezogen werden sollen. Standardmäßig null. Muss strukturklon-bar sein.

devtools

Einige Browser verwenden ein strukturiertes devtools Objekt innerhalb des detail Objekts als Teil einer Extensibility API, die diese in benutzerdefinierten Spuren in Leistungstraces anzeigt. Siehe die Chrome's Extensibility API-Dokumentation für weitere Informationen.

dataType Experimentell

Zeichenfolge mit dem Wert track-entry (zum Definieren einer neuen Spur) oder marker (zum Definieren eines Eintrags in einer Spur).

color Optional Experimentell

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

track Optional Experimentell

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

trackGroup Optional Experimentell

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

properties Optional Experimentell

Array von Schlüssel-Wert-Paaren. Werte können jeden JSON-kompatiblen Typ haben.

tooltipText Optional Experimentell

Kurze Beschreibung für Tooltip.

start Optional

Zeitstempel (DOMHighResTimeStamp) der als Startzeit verwendet werden soll, oder eine Zeichenfolge, die eine PerformanceMark benennt, die als Startzeit verwendet werden soll.

Wenn dies eine Zeichenfolge ist, die eine PerformanceMark benennt, dann ist diese in derselben Weise definiert wie startMark.

duration Optional

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

end Optional

Zeitstempel (DOMHighResTimeStamp) der als Endzeit verwendet werden soll, oder eine Zeichenfolge, die eine PerformanceMark benennt, die als Endzeit verwendet werden soll.

Wenn dies eine Zeichenfolge ist, die eine PerformanceMark benennt, dann ist diese in derselben Weise definiert wie endMark.

startMark Optional

Eine Zeichenfolge, die eine PerformanceMark in der Leistungstimeline benennt. Die PerformanceEntry.startTime Eigenschaft dieser Marke wird zur Berechnung der Messung verwendet.

endMark Optional

Eine Zeichenfolge, die eine PerformanceMark in der Leistungstimeline benennt. Die PerformanceEntry.startTime Eigenschaft dieser Marke wird zur Berechnung der Messung verwendet. Wenn Sie dieses Argument übergeben möchten, müssen Sie entweder startMark oder ein leeres measureOptions Objekt übergeben.

Rückgabewert

Der erstellte PerformanceMeasure Eintrag.

Die zurückgegebene Messung wird folgende Eigenschaftswerte haben:

• entryType - auf "measure" gesetzt.

• name - auf das name Argument gesetzt.

• startTime - gesetzt auf:

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

• duration - auf einen DOMHighResTimeStamp gesetzt, der die Dauer der Messung ist, die durch Subtrahieren des startTime vom Endzeitstempel berechnet wird.

  Der Endzeitstempel ist einer der folgenden:

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

• detail - auf den in measureOptions übergebenen Wert gesetzt.

Ausnahmen

TypeError

Dies kann in jedem Fall ausgelöst werden, in dem der Start, das Ende oder die Dauer mehrdeutig sein könnten:

• Sowohl endMark als auch measureOptions sind angegeben.
• measureOptions ist mit duration angegeben, aber ohne Angabe entweder von start oder end.
• measureOptions ist angegeben mit allen start, end und duration.

SyntaxError DOMException

Die benannte Marke existiert nicht.

• Eine Endmarke ist mit entweder endMark oder measureOptions.end angegeben, aber es gibt keine PerformanceMark im Leistungsbuffer mit dem übereinstimmenden Namen.
• Eine Endmarke ist mit entweder endMark oder measureOptions.end angegeben, aber sie kann nicht konvertiert werden, um mit einem schreibgeschützten Attribut in der PerformanceTiming Schnittstelle übereinzustimmen.
• Eine Startmarke ist mit entweder startMark oder measureOptions.start angegeben, aber es gibt keine PerformanceMark im Leistungsbuffer mit dem übereinstimmenden Namen.
• Eine Startmarke ist mit entweder startMark oder measureOptions.start angegeben, aber sie kann nicht konvertiert werden, um mit einem schreibgeschützten Attribut in der PerformanceTiming Schnittstelle übereinzustimmen.

DataCloneError DOMException

Der measureOptions.detail Wert ist nicht-null und kann nicht unter Verwendung des HTML "StructuredSerialize" Algorithmus serialisiert werden.

RangeError

Der measureOptions.detail Wert ist nicht-null und es kann während der Serialisierung unter Verwendung des HTML "StructuredSerialize" Algorithmus kein Speicher zugewiesen werden.

Beispiele

Messen der Dauer zwischen benannten Markern

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

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

Messen der Dauer mit benutzerdefinierten Start- und Endzeiten

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

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

Bereitstellen zusätzlicher Messdetails

Sie können die details Eigenschaft verwenden, um zusätzliche Informationen beliebigen Typs bereitzustellen. Vielleicht möchten Sie zum Beispiel festhalten, 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 mehr Details in einem devtools Objekt bereitzustellen, das in Leistungsprofilen angezeigt 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