From 3789d668f75c0a60c85208750a823e5c70184cb3 Mon Sep 17 00:00:00 2001
From: legendecas <legendecas@gmail.com>
Date: Thu, 17 Feb 2022 00:24:37 +0800
Subject: [PATCH] doc: add missing api entries on performance

PR-URL: https://github.com/nodejs/node/pull/42018
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
---
 doc/api/perf_hooks.md | 81 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index fd7c2bbcd68729..18c8ddba02f9e2 100644
--- a/doc/api/perf_hooks.md
+++ b/doc/api/perf_hooks.md
@@ -55,6 +55,17 @@ added: v8.5.0
 If `name` is not provided, removes all `PerformanceMark` objects from the
 Performance Timeline. If `name` is provided, removes only the named mark.
 
+### `performance.clearMeasures([name])`
+
+<!-- YAML
+added: v16.7.0
+-->
+
+* `name` {string}
+
+If `name` is not provided, removes all `PerformanceMeasure` objects from the
+Performance Timeline. If `name` is provided, removes only the named mark.
+
 ### `performance.eventLoopUtilization([utilization1[, utilization2]])`
 
 <!-- YAML
@@ -118,6 +129,47 @@ Passing in a user-defined object instead of the result of a previous call to
 `eventLoopUtilization()` will lead to undefined behavior. The return values
 are not guaranteed to reflect any correct state of the event loop.
 
+### `performance.getEntries()`
+
+<!-- YAML
+added: v16.7.0
+-->
+
+* Returns: {PerformanceEntry\[]}
+
+Returns a list of `PerformanceEntry` objects in chronological order with
+respect to `performanceEntry.startTime`. If you are only interested in
+performance entries of certain types or that have certain names, see
+`performance.getEntriesByType()` and `performance.getEntriesByName()`.
+
+### `performance.getEntriesByName(name[, type])`
+
+<!-- YAML
+added: v16.7.0
+-->
+
+* `name` {string}
+* `type` {string}
+* Returns: {PerformanceEntry\[]}
+
+Returns a list of `PerformanceEntry` objects in chronological order
+with respect to `performanceEntry.startTime` whose `performanceEntry.name` is
+equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to
+`type`.
+
+### `performance.getEntriesByType(type)`
+
+<!-- YAML
+added: v16.7.0
+-->
+
+* `type` {string}
+* Returns: {PerformanceEntry\[]}
+
+Returns a list of `PerformanceEntry` objects in chronological order
+with respect to `performanceEntry.startTime` whose `performanceEntry.entryType`
+is equal to `type`.
+
 ### `performance.mark([name[, options]])`
 
 <!-- YAML
@@ -140,6 +192,12 @@ Creates a new `PerformanceMark` entry in the Performance Timeline. A
 `performanceEntry.duration` is always `0`. Performance marks are used
 to mark specific significant moments in the Performance Timeline.
 
+The created `PerformanceMark` entry is put in the global Performance Timeline
+and can be queried with `performance.getEntries`,
+`performance.getEntriesByName`, and `performance.getEntriesByType`. When the
+observation is performed, the entries should be cleared from the global
+Performance Timeline manually with `performance.clearMarks`.
+
 ### `performance.measure(name[, startMarkOrOptions[, endMark]])`
 
 <!-- YAML
@@ -183,6 +241,12 @@ in the Performance Timeline or any of the timestamp properties provided by the
 if no parameter is passed, otherwise if the named `endMark` does not exist, an
 error will be thrown.
 
+The created `PerformanceMeasure` entry is put in the global Performance Timeline
+and can be queried with `performance.getEntries`,
+`performance.getEntriesByName`, and `performance.getEntriesByType`. When the
+observation is performed, the entries should be cleared from the global
+Performance Timeline manually with `performance.clearMeasures`.
+
 ### `performance.nodeTiming`
 
 <!-- YAML
@@ -258,6 +322,9 @@ const wrapped = performance.timerify(someFunction);
 
 const obs = new PerformanceObserver((list) => {
   console.log(list.getEntries()[0].duration);
+
+  performance.clearMarks();
+  performance.clearMeasures();
   obs.disconnect();
 });
 obs.observe({ entryTypes: ['function'] });
@@ -585,6 +652,9 @@ const {
 
 const obs = new PerformanceObserver((list, observer) => {
   console.log(list.getEntries());
+
+  performance.clearMarks();
+  performance.clearMeasures();
   observer.disconnect();
 });
 obs.observe({ entryTypes: ['mark'], buffered: true });
@@ -700,6 +770,9 @@ const obs = new PerformanceObserver((perfObserverList, observer) => {
    *   }
    * ]
    */
+
+  performance.clearMarks();
+  performance.clearMeasures();
   observer.disconnect();
 });
 obs.observe({ type: 'mark' });
@@ -755,6 +828,9 @@ const obs = new PerformanceObserver((perfObserverList, observer) => {
    * ]
    */
   console.log(perfObserverList.getEntriesByName('test', 'measure')); // []
+
+  performance.clearMarks();
+  performance.clearMeasures();
   observer.disconnect();
 });
 obs.observe({ entryTypes: ['mark', 'measure'] });
@@ -800,6 +876,8 @@ const obs = new PerformanceObserver((perfObserverList, observer) => {
    *   }
    * ]
    */
+  performance.clearMarks();
+  performance.clearMeasures();
   observer.disconnect();
 });
 obs.observe({ type: 'mark' });
@@ -1133,6 +1211,7 @@ hook.enable();
 const obs = new PerformanceObserver((list, observer) => {
   console.log(list.getEntries()[0]);
   performance.clearMarks();
+  performance.clearMeasures();
   observer.disconnect();
 });
 obs.observe({ entryTypes: ['measure'], buffered: true });
@@ -1166,6 +1245,8 @@ const obs = new PerformanceObserver((list) => {
   entries.forEach((entry) => {
     console.log(`require('${entry[0]}')`, entry.duration);
   });
+  performance.clearMarks();
+  performance.clearMeasures();
   obs.disconnect();
 });
 obs.observe({ entryTypes: ['function'], buffered: true });