1 | declare module 'perf_hooks' {
|
2 | import { AsyncResource } from 'async_hooks';
|
3 |
|
4 | type EntryType = 'node' | 'mark' | 'measure' | 'gc' | 'function' | 'http2' | 'http';
|
5 |
|
6 | class PerformanceEntry {
|
7 | protected constructor();
|
8 | /**
|
9 | * The total number of milliseconds elapsed for this entry.
|
10 | * This value will not be meaningful for all Performance Entry types.
|
11 | */
|
12 | readonly duration: number;
|
13 |
|
14 | /**
|
15 | * The name of the performance entry.
|
16 | */
|
17 | readonly name: string;
|
18 |
|
19 | /**
|
20 | * The high resolution millisecond timestamp marking the starting time of the Performance Entry.
|
21 | */
|
22 | readonly startTime: number;
|
23 |
|
24 | /**
|
25 | * The type of the performance entry.
|
26 | * Currently it may be one of: 'node', 'mark', 'measure', 'gc', or 'function'.
|
27 | */
|
28 | readonly entryType: EntryType;
|
29 |
|
30 | /**
|
31 | * When `performanceEntry.entryType` is equal to 'gc', `the performance.kind` property identifies
|
32 | * the type of garbage collection operation that occurred.
|
33 | * See perf_hooks.constants for valid values.
|
34 | */
|
35 | readonly kind?: number;
|
36 |
|
37 | /**
|
38 | * When `performanceEntry.entryType` is equal to 'gc', the `performance.flags`
|
39 | * property contains additional information about garbage collection operation.
|
40 | * See perf_hooks.constants for valid values.
|
41 | */
|
42 | readonly flags?: number;
|
43 | }
|
44 |
|
45 | class PerformanceNodeTiming extends PerformanceEntry {
|
46 | /**
|
47 | * The high resolution millisecond timestamp at which the Node.js process completed bootstrap.
|
48 | */
|
49 | readonly bootstrapComplete: number;
|
50 |
|
51 | /**
|
52 | * The high resolution millisecond timestamp at which the Node.js process completed bootstrapping.
|
53 | * If bootstrapping has not yet finished, the property has the value of -1.
|
54 | */
|
55 | readonly environment: number;
|
56 |
|
57 | /**
|
58 | * The high resolution millisecond timestamp at which the Node.js environment was initialized.
|
59 | */
|
60 | readonly idleTime: number;
|
61 |
|
62 | /**
|
63 | * The high resolution millisecond timestamp of the amount of time the event loop has been idle
|
64 | * within the event loop's event provider (e.g. `epoll_wait`). This does not take CPU usage
|
65 | * into consideration. If the event loop has not yet started (e.g., in the first tick of the main script),
|
66 | * the property has the value of 0.
|
67 | */
|
68 | readonly loopExit: number;
|
69 |
|
70 | /**
|
71 | * The high resolution millisecond timestamp at which the Node.js event loop started.
|
72 | * If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of -1.
|
73 | */
|
74 | readonly loopStart: number;
|
75 |
|
76 | /**
|
77 | * The high resolution millisecond timestamp at which the V8 platform was initialized.
|
78 | */
|
79 | readonly v8Start: number;
|
80 | }
|
81 |
|
82 | interface EventLoopUtilization {
|
83 | idle: number;
|
84 | active: number;
|
85 | utilization: number;
|
86 | }
|
87 |
|
88 | /**
|
89 | * @param util1 The result of a previous call to eventLoopUtilization()
|
90 | * @param util2 The result of a previous call to eventLoopUtilization() prior to util1
|
91 | */
|
92 | type EventLoopUtilityFunction = (
|
93 | util1?: EventLoopUtilization,
|
94 | util2?: EventLoopUtilization,
|
95 | ) => EventLoopUtilization;
|
96 |
|
97 | interface Performance {
|
98 | /**
|
99 | * If name is not provided, removes all PerformanceMark objects from the Performance Timeline.
|
100 | * If name is provided, removes only the named mark.
|
101 | * @param name
|
102 | */
|
103 | clearMarks(name?: string): void;
|
104 |
|
105 | /**
|
106 | * Creates a new PerformanceMark entry in the Performance Timeline.
|
107 | * A PerformanceMark is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'mark',
|
108 | * and whose performanceEntry.duration is always 0.
|
109 | * Performance marks are used to mark specific significant moments in the Performance Timeline.
|
110 | * @param name
|
111 | */
|
112 | mark(name?: string): void;
|
113 |
|
114 | /**
|
115 | * Creates a new PerformanceMeasure entry in the Performance Timeline.
|
116 | * A PerformanceMeasure is a subclass of PerformanceEntry whose performanceEntry.entryType is always 'measure',
|
117 | * and whose performanceEntry.duration measures the number of milliseconds elapsed since startMark and endMark.
|
118 | *
|
119 | * The startMark argument may identify any existing PerformanceMark in the the Performance Timeline, or may identify
|
120 | * any of the timestamp properties provided by the PerformanceNodeTiming class. If the named startMark does not exist,
|
121 | * then startMark is set to timeOrigin by default.
|
122 | *
|
123 | * The endMark argument must identify any existing PerformanceMark in the the Performance Timeline or any of the timestamp
|
124 | * properties provided by the PerformanceNodeTiming class. If the named endMark does not exist, an error will be thrown.
|
125 | * @param name
|
126 | * @param startMark
|
127 | * @param endMark
|
128 | */
|
129 | measure(name: string, startMark?: string, endMark?: string): void;
|
130 |
|
131 | /**
|
132 | * An instance of the PerformanceNodeTiming class that provides performance metrics for specific Node.js operational milestones.
|
133 | */
|
134 | readonly nodeTiming: PerformanceNodeTiming;
|
135 |
|
136 | /**
|
137 | * @return the current high resolution millisecond timestamp
|
138 | */
|
139 | now(): number;
|
140 |
|
141 | /**
|
142 | * The timeOrigin specifies the high resolution millisecond timestamp from which all performance metric durations are measured.
|
143 | */
|
144 | readonly timeOrigin: number;
|
145 |
|
146 | /**
|
147 | * Wraps a function within a new function that measures the running time of the wrapped function.
|
148 | * A PerformanceObserver must be subscribed to the 'function' event type in order for the timing details to be accessed.
|
149 | * @param fn
|
150 | */
|
151 | timerify<T extends (...optionalParams: any[]) => any>(fn: T): T;
|
152 |
|
153 | /**
|
154 | * eventLoopUtilization is similar to CPU utilization except that it is calculated using high precision wall-clock time.
|
155 | * It represents the percentage of time the event loop has spent outside the event loop's event provider (e.g. epoll_wait).
|
156 | * No other CPU idle time is taken into consideration.
|
157 | */
|
158 | eventLoopUtilization: EventLoopUtilityFunction;
|
159 | }
|
160 |
|
161 | interface PerformanceObserverEntryList {
|
162 | /**
|
163 | * @return a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime.
|
164 | */
|
165 | getEntries(): PerformanceEntry[];
|
166 |
|
167 | /**
|
168 | * @return a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime
|
169 | * whose performanceEntry.name is equal to name, and optionally, whose performanceEntry.entryType is equal to type.
|
170 | */
|
171 | getEntriesByName(name: string, type?: EntryType): PerformanceEntry[];
|
172 |
|
173 | /**
|
174 | * @return Returns a list of PerformanceEntry objects in chronological order with respect to performanceEntry.startTime
|
175 | * whose performanceEntry.entryType is equal to type.
|
176 | */
|
177 | getEntriesByType(type: EntryType): PerformanceEntry[];
|
178 | }
|
179 |
|
180 | type PerformanceObserverCallback = (list: PerformanceObserverEntryList, observer: PerformanceObserver) => void;
|
181 |
|
182 | class PerformanceObserver extends AsyncResource {
|
183 | constructor(callback: PerformanceObserverCallback);
|
184 |
|
185 | /**
|
186 | * Disconnects the PerformanceObserver instance from all notifications.
|
187 | */
|
188 | disconnect(): void;
|
189 |
|
190 | /**
|
191 | * Subscribes the PerformanceObserver instance to notifications of new PerformanceEntry instances identified by options.entryTypes.
|
192 | * When options.buffered is false, the callback will be invoked once for every PerformanceEntry instance.
|
193 | * Property buffered defaults to false.
|
194 | * @param options
|
195 | */
|
196 | observe(options: { entryTypes: ReadonlyArray<EntryType>; buffered?: boolean }): void;
|
197 | }
|
198 |
|
199 | namespace constants {
|
200 | const NODE_PERFORMANCE_GC_MAJOR: number;
|
201 | const NODE_PERFORMANCE_GC_MINOR: number;
|
202 | const NODE_PERFORMANCE_GC_INCREMENTAL: number;
|
203 | const NODE_PERFORMANCE_GC_WEAKCB: number;
|
204 |
|
205 | const NODE_PERFORMANCE_GC_FLAGS_NO: number;
|
206 | const NODE_PERFORMANCE_GC_FLAGS_CONSTRUCT_RETAINED: number;
|
207 | const NODE_PERFORMANCE_GC_FLAGS_FORCED: number;
|
208 | const NODE_PERFORMANCE_GC_FLAGS_SYNCHRONOUS_PHANTOM_PROCESSING: number;
|
209 | const NODE_PERFORMANCE_GC_FLAGS_ALL_AVAILABLE_GARBAGE: number;
|
210 | const NODE_PERFORMANCE_GC_FLAGS_ALL_EXTERNAL_MEMORY: number;
|
211 | const NODE_PERFORMANCE_GC_FLAGS_SCHEDULE_IDLE: number;
|
212 | }
|
213 |
|
214 | const performance: Performance;
|
215 |
|
216 | interface EventLoopMonitorOptions {
|
217 | /**
|
218 | * The sampling rate in milliseconds.
|
219 | * Must be greater than zero.
|
220 | * @default 10
|
221 | */
|
222 | resolution?: number;
|
223 | }
|
224 |
|
225 | interface Histogram {
|
226 | /**
|
227 | * A `Map` object detailing the accumulated percentile distribution.
|
228 | */
|
229 | readonly percentiles: Map<number, number>;
|
230 |
|
231 | /**
|
232 | * The number of times the event loop delay exceeded the maximum 1 hour eventloop delay threshold.
|
233 | */
|
234 | readonly exceeds: number;
|
235 |
|
236 | /**
|
237 | * The minimum recorded event loop delay.
|
238 | */
|
239 | readonly min: number;
|
240 |
|
241 | /**
|
242 | * The maximum recorded event loop delay.
|
243 | */
|
244 | readonly max: number;
|
245 |
|
246 | /**
|
247 | * The mean of the recorded event loop delays.
|
248 | */
|
249 | readonly mean: number;
|
250 |
|
251 | /**
|
252 | * The standard deviation of the recorded event loop delays.
|
253 | */
|
254 | readonly stddev: number;
|
255 |
|
256 | /**
|
257 | * Resets the collected histogram data.
|
258 | */
|
259 | reset(): void;
|
260 |
|
261 | /**
|
262 | * Returns the value at the given percentile.
|
263 | * @param percentile A percentile value between 1 and 100.
|
264 | */
|
265 | percentile(percentile: number): number;
|
266 | }
|
267 |
|
268 | interface IntervalHistogram extends Histogram {
|
269 | /**
|
270 | * Enables the event loop delay sample timer. Returns `true` if the timer was started, `false` if it was already started.
|
271 | */
|
272 | enable(): boolean;
|
273 | /**
|
274 | * Disables the event loop delay sample timer. Returns `true` if the timer was stopped, `false` if it was already stopped.
|
275 | */
|
276 | disable(): boolean;
|
277 | }
|
278 |
|
279 | interface RecordableHistogram extends Histogram {
|
280 | record(val: number | bigint): void;
|
281 |
|
282 | /**
|
283 | * Calculates the amount of time (in nanoseconds) that has passed since the previous call to recordDelta() and records that amount in the histogram.
|
284 | */
|
285 | recordDelta(): void;
|
286 | }
|
287 |
|
288 | function monitorEventLoopDelay(options?: EventLoopMonitorOptions): IntervalHistogram;
|
289 |
|
290 | interface CreateHistogramOptions {
|
291 | /**
|
292 | * The minimum recordable value. Must be an integer value greater than 0.
|
293 | * @default 1
|
294 | */
|
295 | min?: number | bigint;
|
296 |
|
297 | /**
|
298 | * The maximum recordable value. Must be an integer value greater than min.
|
299 | * @default Number.MAX_SAFE_INTEGER
|
300 | */
|
301 | max?: number | bigint;
|
302 | /**
|
303 | * The number of accuracy digits. Must be a number between 1 and 5.
|
304 | * @default 3
|
305 | */
|
306 | figures?: number;
|
307 | }
|
308 |
|
309 | function createHistogram(options?: CreateHistogramOptions): RecordableHistogram;
|
310 | }
|