| 1 | /********************************************************************************
|
| 2 | * Copyright (c) 2021 STMicroelectronics and others.
|
| 3 | *
|
| 4 | * This program and the accompanying materials are made available under the
|
| 5 | * terms of the Eclipse Public License 2.0 which is available at
|
| 6 | * http://www.eclipse.org/legal/epl-2.0.
|
| 7 | *
|
| 8 | * This Source Code may also be made available under the following Secondary
|
| 9 | * Licenses when the conditions for such availability set forth in the Eclipse
|
| 10 | * Public License v. 2.0 are satisfied: GNU General Public License, version 2
|
| 11 | * with the GNU Classpath Exception which is available at
|
| 12 | * https://www.gnu.org/software/classpath/license.html.
|
| 13 | *
|
| 14 | * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
|
| 15 | *******************************************************************************/
|
| 16 | import { LogLevel } from '../logger';
|
| 17 | /**
|
| 18 | * A `Measurement` counts the time elapsed between its creation when the {@link Stopwatch}
|
| 19 | * is {@link Stopwatch.start started} and when it is {@link stop stopped}.
|
| 20 | */
|
| 21 | export interface Measurement {
|
| 22 | /**
|
| 23 | * Compute the elapsed time, in milliseconds, if not already done (only has effect on the first invocation).
|
| 24 | * A `NaN` result indicates that the watch was stopped but failed to make a measurement.
|
| 25 | */
|
| 26 | stop(): number;
|
| 27 | /** The measurement name. This may show up in the performance measurement framework appropriate to the application context. */
|
| 28 | name: string;
|
| 29 | /**
|
| 30 | * The elapsed time measured, if it has been {@link stop stopped} and measured, or `NaN` if the platform disabled
|
| 31 | * performance measurement.
|
| 32 | */
|
| 33 | elapsed?: number;
|
| 34 | /**
|
| 35 | * Compute the elapsed time and log a message annotated with that timing information.
|
| 36 | * The message is logged at the level determined by the {@link MeasurementOptions}.
|
| 37 | *
|
| 38 | * @param detail a message detailing what activity was measured
|
| 39 | * @param optionalArgs optional message arguments as per the usual console API
|
| 40 | */
|
| 41 | log(detail: string, ...optionalArgs: any[]): void;
|
| 42 | /**
|
| 43 | * Compute the elapsed time and log a debug message annotated with that timing information.
|
| 44 | *
|
| 45 | * @param detail a message detailing what activity was measured
|
| 46 | * @param optionalArgs optional message arguments as per the usual console API
|
| 47 | */
|
| 48 | debug(detail: string, ...optionalArgs: any[]): void;
|
| 49 | /**
|
| 50 | * Compute the elapsed time and log an info message annotated with that timing information.
|
| 51 | *
|
| 52 | * @param detail a message detailing what activity was measured
|
| 53 | * @param optionalArgs optional message arguments as per the usual console API
|
| 54 | */
|
| 55 | info(detail: string, ...optionalArgs: any[]): void;
|
| 56 | /**
|
| 57 | * Compute the elapsed time and log a warning message annotated with that timing information.
|
| 58 | *
|
| 59 | * @param detail a message detailing what activity was measured
|
| 60 | * @param optionalArgs optional message arguments as per the usual console API
|
| 61 | */
|
| 62 | warn(detail: string, ...optionalArgs: any[]): void;
|
| 63 | /**
|
| 64 | * Compute the elapsed time and log an error message annotated with that timing information.
|
| 65 | *
|
| 66 | * @param detail a message detailing what activity was measured
|
| 67 | * @param optionalArgs optional message arguments as per the usual console API
|
| 68 | */
|
| 69 | error(detail: string, ...optionalArgs: any[]): void;
|
| 70 | }
|
| 71 | /**
|
| 72 | * Optional configuration of a {@link Measurement} specified at the time of its creation.
|
| 73 | */
|
| 74 | export interface MeasurementOptions {
|
| 75 | /**
|
| 76 | * A specific context of the application in which an activity was measured.
|
| 77 | * Results in logs being emitted with a "[<context>]" qualified at the head.
|
| 78 | */
|
| 79 | context?: string;
|
| 80 | /** An optional logging level at which to emit the log message. The default value is {@link LogLevel.INFO}. */
|
| 81 | defaultLogLevel?: LogLevel;
|
| 82 | /**
|
| 83 | * Some measurements are measured against a threshold (in millis) that they should not exceed.
|
| 84 | * If omitted, the implied threshold is unlimited time (no threshold).
|
| 85 | *
|
| 86 | * @see {@link Stopwatch.startAsync}
|
| 87 | * @see {@link thresholdLogLevel}
|
| 88 | */
|
| 89 | thresholdMillis?: number;
|
| 90 | /**
|
| 91 | * Flag to indicate whether the stopwatch should store measurement results for later retrieval.
|
| 92 | * For example the cache can be used to retrieve measurements which were taken during startup before a listener had a chance to register.
|
| 93 | */
|
| 94 | storeResults?: boolean;
|
| 95 | }
|
| 96 | /**
|
| 97 | * Captures the result of a {@link Measurement} in a serializable format.
|
| 98 | */
|
| 99 | export interface MeasurementResult {
|
| 100 | /** The measurement name. This may show up in the performance measurement framework appropriate to the application context. */
|
| 101 | name: string;
|
| 102 | /** The time when the measurement recording has been started */
|
| 103 | startTime: number;
|
| 104 | /**
|
| 105 | * The elapsed time measured, if it has been {@link stop stopped} and measured, or `NaN` if the platform disabled
|
| 106 | * performance measurement.
|
| 107 | */
|
| 108 | elapsed: number;
|
| 109 | /** An optional label for the application the start of which (in real time) is the basis of all measurements. */
|
| 110 | owner?: string;
|
| 111 | }
|
| 112 | //# sourceMappingURL=measurement.d.ts.map |
| \ | No newline at end of file |