@fluidframework/telemetry-utils 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/src/mockLogger.ts

@@ -3,102 +3,244 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLogger, ITelemetryBaseEvent } from "@fluidframework/common-definitions";
-import { TelemetryLogger } from "./logger";
+import {
+	ITelemetryBaseEvent,
+	ITelemetryBaseLogger,
+	LogLevel,
+} from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils";
+import { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes";
+import { createChildLogger } from "./logger";
 
 /**
  * The MockLogger records events sent to it, and then can walk back over those events
  * searching for a set of expected events to match against the logged events.
+ *
+ * @internal
  */
-export class MockLogger extends TelemetryLogger implements ITelemetryLogger {
-    events: ITelemetryBaseEvent[] = [];
-
-    constructor() { super(); }
-
-    clear() {
-        this.events = [];
-    }
-
-    send(event: ITelemetryBaseEvent): void {
-        this.events.push(event);
-    }
-
-    /**
-     * Search events logged since the last time matchEvents was called, looking for the given expected
-     * events in order.
-     * @param expectedEvents - events in order that are expected to appear in the recorded log.
-     * These event objects may be subsets of the logged events.
-     * Note: category is ommitted from the type because it's usually uninteresting and tedious to type.
-     */
-    matchEvents(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): boolean {
-        const matchedExpectedEventCount = this.getMatchedEventsCount(expectedEvents);
-        // How many expected events were left over? Hopefully none.
-        const unmatchedExpectedEventCount = expectedEvents.length - matchedExpectedEventCount;
-        return unmatchedExpectedEventCount === 0;
-    }
-
-    /** Asserts that matchEvents is true, and prints the actual/expected output if not */
-    assertMatch(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
-        const actualEvents = this.events;
-        if (!this.matchEvents(expectedEvents)) {
-            throw new Error(`${message}
+export class MockLogger implements ITelemetryBaseLogger {
+	events: ITelemetryBaseEvent[] = [];
+
+	constructor(public readonly minLogLevel?: LogLevel) {}
+
+	clear(): void {
+		this.events = [];
+	}
+
+	toTelemetryLogger(): ITelemetryLoggerExt {
+		return createChildLogger({ logger: this });
+	}
+
+	send(event: ITelemetryBaseEvent): void {
+		this.events.push(event);
+	}
+
+	/**
+	 * Search events logged since the last time matchEvents was called, looking for the given expected
+	 * events in order.
+	 * @param expectedEvents - events in order that are expected to appear in the recorded log.
+	 * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+	 * These event objects may be subsets of the logged events.
+	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
+	 */
+	matchEvents(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		inlineDetailsProp: boolean = false,
+	): boolean {
+		const matchedExpectedEventCount = this.getMatchedEventsCount(
+			expectedEvents,
+			inlineDetailsProp,
+		);
+		// How many expected events were left over? Hopefully none.
+		const unmatchedExpectedEventCount = expectedEvents.length - matchedExpectedEventCount;
+		return unmatchedExpectedEventCount === 0;
+	}
+
+	/**
+	 * Asserts that matchEvents is true, and prints the actual/expected output if not.
+	 */
+	assertMatch(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		message?: string,
+		inlineDetailsProp: boolean = false,
+	): void {
+		const actualEvents = this.events;
+		if (!this.matchEvents(expectedEvents, inlineDetailsProp)) {
+			throw new Error(`${message}
 expected:
 ${JSON.stringify(expectedEvents)}
 
 actual:
 ${JSON.stringify(actualEvents)}`);
-        }
-    }
-
-    /**
-     * Search events logged since the last time matchEvents was called, looking for any of the given
-     * expected events.
-     * @param expectedEvents - events that are expected to appear in the recorded log.
-     * These event objects may be subsets of the logged events.
-     * Note: category is ommitted from the type because it's usually uninteresting and tedious to type.
-     * @returns if any of the expected events is found.
-     */
-    matchAnyEvent(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): boolean {
-        const matchedExpectedEventCount = this.getMatchedEventsCount(expectedEvents);
-        return matchedExpectedEventCount > 0;
-    }
-
-    /** Asserts that matchAnyEvent is true, and prints the actual/expected output if not */
-    assertMatchAny(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
-        const actualEvents = this.events;
-        if (!this.matchAnyEvent(expectedEvents)) {
-            throw new Error(`${message}
+		}
+	}
+
+	/**
+	 * Search events logged since the last time matchEvents was called, looking for any of the given
+	 * expected events.
+	 * @param expectedEvents - events that are expected to appear in the recorded log.
+	 * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+	 * These event objects may be subsets of the logged events.
+	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
+	 * @returns if any of the expected events is found.
+	 */
+	matchAnyEvent(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		inlineDetailsProp: boolean = false,
+	): boolean {
+		const matchedExpectedEventCount = this.getMatchedEventsCount(
+			expectedEvents,
+			inlineDetailsProp,
+		);
+		return matchedExpectedEventCount > 0;
+	}
+
+	/**
+	 * Asserts that matchAnyEvent is true, and prints the actual/expected output if not.
+	 */
+	assertMatchAny(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		message?: string,
+		inlineDetailsProp: boolean = false,
+	): void {
+		const actualEvents = this.events;
+		if (!this.matchAnyEvent(expectedEvents, inlineDetailsProp)) {
+			throw new Error(`${message}
 expected:
 ${JSON.stringify(expectedEvents)}
 
 actual:
 ${JSON.stringify(actualEvents)}`);
-            }
-    }
-
-    private getMatchedEventsCount(expectedEvents: Omit<ITelemetryBaseEvent, "category">[]): number {
-        let iExpectedEvent = 0;
-        this.events.forEach((event) => {
-            if (iExpectedEvent < expectedEvents.length &&
-                MockLogger.eventsMatch(event, expectedEvents[iExpectedEvent])
-            ) {
-                // We found the next expected event; increment
-                ++iExpectedEvent;
-            }
-        });
-
-        // Remove the events so far; next call will just compare subsequent events from here
-        this.events = [];
-
-        // Return the count of matched events.
-        return iExpectedEvent;
-    }
-
-    /**
-     * Ensure the expected event is a strict subset of the actual event
-     */
-    private static eventsMatch(actual: ITelemetryBaseEvent, expected: Omit<ITelemetryBaseEvent, "category">): boolean {
-        const masked = { ...actual, ...expected };
-        return JSON.stringify(masked) === JSON.stringify(actual);
-    }
+		}
+	}
+
+	/**
+	 * Search events logged since the last time matchEvents was called, looking only for the given expected
+	 * events in order.
+	 * @param expectedEvents - events in order that are expected to be the only events in the recorded log.
+	 * @param inlineDetailsProp - true if the "details" property in the actual event should be extracted and inlined.
+	 * These event objects may be subsets of the logged events.
+	 * Note: category is omitted from the type because it's usually uninteresting and tedious to type.
+	 */
+	matchEventStrict(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		inlineDetailsProp: boolean = false,
+	): boolean {
+		return (
+			expectedEvents.length === this.events.length &&
+			this.matchEvents(expectedEvents, inlineDetailsProp)
+		);
+	}
+
+	/**
+	 * Asserts that matchEvents is true, and prints the actual/expected output if not
+	 */
+	assertMatchStrict(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		message?: string,
+		inlineDetailsProp: boolean = false,
+	): void {
+		const actualEvents = this.events;
+		if (!this.matchEventStrict(expectedEvents, inlineDetailsProp)) {
+			throw new Error(`${message}
+expected:
+${JSON.stringify(expectedEvents)}
+
+actual:
+${JSON.stringify(actualEvents)}`);
+		}
+	}
+
+	/**
+	 * Asserts that matchAnyEvent is false for the given events, and prints the actual/expected output if not
+	 */
+	assertMatchNone(
+		disallowedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		message?: string,
+		inlineDetailsProp: boolean = false,
+	): void {
+		const actualEvents = this.events;
+		if (this.matchAnyEvent(disallowedEvents, inlineDetailsProp)) {
+			throw new Error(`${message}
+disallowed events:
+${JSON.stringify(disallowedEvents)}
+
+actual:
+${JSON.stringify(actualEvents)}`);
+		}
+	}
+
+	private getMatchedEventsCount(
+		expectedEvents: Omit<ITelemetryBaseEvent, "category">[],
+		inlineDetailsProp: boolean,
+	): number {
+		let iExpectedEvent = 0;
+		for (const event of this.events) {
+			if (
+				iExpectedEvent < expectedEvents.length &&
+				MockLogger.eventsMatch(event, expectedEvents[iExpectedEvent], inlineDetailsProp)
+			) {
+				// We found the next expected event; increment
+				++iExpectedEvent;
+			}
+		}
+
+		// Remove the events so far; next call will just compare subsequent events from here
+		this.events = [];
+
+		// Return the count of matched events.
+		return iExpectedEvent;
+	}
+
+	/**
+	 * Ensure the expected event is a strict subset of the actual event
+	 */
+	private static eventsMatch(
+		actual: ITelemetryBaseEvent,
+		expected: Omit<ITelemetryBaseEvent, "category">,
+		inlineDetailsProp: boolean,
+	): boolean {
+		const { details, ...actualForMatching } = actual;
+		// "details" is used in a lot of telemetry logs to group a bunch of properties together and stringify them.
+		// Some of the properties in the expected event may be inside "details". So, if inlineDetailsProp is true,
+		// extract the properties from "details" in the actual event and inline them in the actual event.
+		if (inlineDetailsProp && details !== undefined) {
+			assert(
+				typeof details === "string",
+				// eslint-disable-next-line unicorn/numeric-separators-style
+				0x6c9 /* Details should a JSON stringified string if inlineDetailsProp is true */,
+			);
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+			const detailsExpanded = JSON.parse(details);
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+			return matchObjects({ ...actualForMatching, ...detailsExpanded }, expected);
+		}
+		return matchObjects(actual, expected);
+	}
+}
+
+function matchObjects(actual: ITelemetryPropertiesExt, expected: ITelemetryPropertiesExt): boolean {
+	for (const [expectedKey, expectedValue] of Object.entries(expected)) {
+		const actualValue = actual[expectedKey];
+		if (
+			!Array.isArray(expectedValue) &&
+			expectedValue !== null &&
+			typeof expectedValue === "object"
+		) {
+			if (
+				Array.isArray(actualValue) ||
+				actualValue === null ||
+				typeof actualValue !== "object" ||
+				!matchObjects(
+					actualValue as ITelemetryPropertiesExt,
+					expectedValue as ITelemetryPropertiesExt,
+				)
+			) {
+				return false;
+			}
+		} else if (JSON.stringify(actualValue) !== JSON.stringify(expectedValue)) {
+			return false;
+		}
+	}
+	return true;
 }

package/src/sampledTelemetryHelper.ts

@@ -4,139 +4,147 @@
  */
 
 import {
-    IDisposable,
-    ITelemetryGenericEvent,
-    ITelemetryLogger,
-    ITelemetryPerformanceEvent,
-    ITelemetryProperties,
-} from "@fluidframework/common-definitions";
-import { performance } from "@fluidframework/common-utils";
+	ITelemetryGenericEvent,
+	ITelemetryPerformanceEvent,
+	ITelemetryProperties,
+	IDisposable,
+} from "@fluidframework/core-interfaces";
+import { performance } from "@fluid-internal/client-utils";
+import { ITelemetryLoggerExt } from "./telemetryTypes";
 
+/**
+ * @privateRemarks
+ *
+ * The names of the properties in this interface are the ones that will get stamped in the
+ * telemetry event, changes should be considered carefully. The optional properties should
+ * only be populated if 'includeAggregateMetrics' is true.
+ */
 interface Measurements {
-    // The names of the properties in this interface are the ones that will get stamped in the
-    // telemetry event, changes should be considered carefully. The optional properties should
-    // only be populated if 'includeAggregateMetrics' is true.
-
-    /**
-     * The duration of the latest execution.
-     */
-    duration: number;
-
-    /**
-     * The number of executions since the last time an event was generated.
-     */
-    count: number;
-
-    /**
-     * Total duration across all the executions since the last event was generated.
-     */
-    totalDuration?: number;
-
-    /**
-     * Min duration across all the executions since the last event was generated.
-     */
-    minDuration?: number;
-
-    /**
-     * Max duration across all the executions since the last event was generated.
-     */
-    maxDuration?: number;
+	/**
+	 * The duration of the latest execution.
+	 */
+	duration: number;
+
+	/**
+	 * The number of executions since the last time an event was generated.
+	 */
+	count: number;
+
+	/**
+	 * Total duration across all the executions since the last event was generated.
+	 */
+	totalDuration?: number;
+
+	/**
+	 * Min duration across all the executions since the last event was generated.
+	 */
+	minDuration?: number;
+
+	/**
+	 * Max duration across all the executions since the last event was generated.
+	 */
+	maxDuration?: number;
 }
 
 /**
  * Helper class that executes a specified code block and writes an
- * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
- * number of executions is reached (or when the class is disposed). The `duration` field in the telemetry event is
- * the duration of the latest execution (sample) of the specified function. See the documentation of the
- * `includeAggregateMetrics` parameter for additional details that can be included.
+ * {@link @fluidframework/core-interfaces#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * number of executions is reached (or when the class is disposed).
+ *
+ * The `duration` field in the telemetry event is the duration of the latest execution (sample) of the specified
+ * function. See the documentation of the `includeAggregateMetrics` parameter for additional details that can be
+ * included.
+ *
+ * @internal
  */
- export class SampledTelemetryHelper implements IDisposable {
-    disposed: boolean = false;
-
-    private readonly measurementsMap = new Map<string, Measurements>();
-
-    /**
-     * @param eventBase -
-     * Custom properties to include in the telemetry performance event when it is written.
-     * @param logger -
-     * The logger to use to write the telemetry performance event.
-     * @param sampleThreshold -
-     * Telemetry performance events will be generated every time we hit this many executions of the code block.
-     * @param includeAggregateMetrics -
-     * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
-     * max duration) for all the executions in between generated events.
-     * @param perBucketProperties -
-     * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
-     * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
-     * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
-     * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
-     * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
-     * ignored.
-     */
-    public constructor(
-        private readonly eventBase: ITelemetryGenericEvent,
-        private readonly logger: ITelemetryLogger,
-        private readonly sampleThreshold: number,
-        private readonly includeAggregateMetrics: boolean = false,
-        private readonly perBucketProperties = new Map<string, ITelemetryProperties>()) {
-    }
-
-    /**
-     * @param codeToMeasure -
-     * The code to be executed and measured.
-     * @param bucket -
-     * A key to track executions of the code block separately. Each different value of this parameter has a separate
-     * set of executions and metrics tracked by the class. If no such distinction needs to be made, do not provide a
-     * value.
-     * @returns Whatever the passed-in code block returns.
-     */
-    public measure<T>(codeToMeasure: () => T, bucket: string = ""): T {
-        const start = performance.now();
-        const returnValue = codeToMeasure();
-        const duration = performance.now() - start;
-
-        let m = this.measurementsMap.get(bucket);
-        if (m === undefined) {
-            m = { count: 0, duration: -1 };
-            this.measurementsMap.set(bucket, m);
-        }
-        m.count++;
-        m.duration = duration;
-
-        if (this.includeAggregateMetrics) {
-            m.totalDuration = (m.totalDuration ?? 0) + duration;
-            m.minDuration = Math.min(m.minDuration ?? duration, duration);
-            m.maxDuration = Math.max(m.maxDuration ?? 0, duration);
-        }
-
-        if (m.count >= this.sampleThreshold) {
-            this.flushBucket(bucket);
-        }
-
-        return returnValue;
-    }
-
-    private flushBucket(bucket: string) {
-        const measurements = this.measurementsMap.get(bucket);
-        if (measurements === undefined) {
-            return;
-        }
-
-        if (measurements.count !== 0) {
-            const bucketProperties = this.perBucketProperties.get(bucket);
-
-            const telemetryEvent: ITelemetryPerformanceEvent = {
-                ...this.eventBase,
-                ...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected
-                ...measurements,
-            };
-
-            this.logger.sendPerformanceEvent(telemetryEvent);
-            this.measurementsMap.delete(bucket);
-        }
-    }
-
-    public dispose(error?: Error | undefined): void {
-        this.measurementsMap.forEach((_, k) => this.flushBucket(k));
-    }
+export class SampledTelemetryHelper implements IDisposable {
+	disposed: boolean = false;
+
+	private readonly measurementsMap = new Map<string, Measurements>();
+
+	/**
+	 * @param eventBase -
+	 * Custom properties to include in the telemetry performance event when it is written.
+	 * @param logger -
+	 * The logger to use to write the telemetry performance event.
+	 * @param sampleThreshold -
+	 * Telemetry performance events will be generated every time we hit this many executions of the code block.
+	 * @param includeAggregateMetrics -
+	 * If set to `true`, the telemetry performance event will include aggregated metrics (total duration, min duration,
+	 * max duration) for all the executions in between generated events.
+	 * @param perBucketProperties -
+	 * Map of strings that represent different buckets (which can be specified when calling the 'measure' method), to
+	 * properties which should be added to the telemetry event for that bucket. If a bucket being measured does not
+	 * have an entry in this map, no additional properties will be added to its telemetry events. The following keys are
+	 * reserved for use by this class: "duration", "count", "totalDuration", "minDuration", "maxDuration". If any of
+	 * them is specified as a key in one of the ITelemetryProperties objects in this map, that key-value pair will be
+	 * ignored.
+	 */
+	public constructor(
+		private readonly eventBase: ITelemetryGenericEvent,
+		private readonly logger: ITelemetryLoggerExt,
+		private readonly sampleThreshold: number,
+		private readonly includeAggregateMetrics: boolean = false,
+		private readonly perBucketProperties = new Map<string, ITelemetryProperties>(),
+	) {}
+
+	/**
+	 * Executes the specified code and keeps track of execution time statistics.
+	 * If it's been called enough times (the sampleThreshold for the class) then it generates a log message with the necessary information.
+	 *
+	 * @param codeToMeasure - The code to be executed and measured.
+	 * @param bucket - A key to track executions of the code block separately.
+	 * Each different value of this parameter has a separate set of executions and metrics tracked by the class.
+	 * If no such distinction needs to be made, do not provide a value.
+	 * @returns Whatever the passed-in code block returns.
+	 */
+	public measure<T>(codeToMeasure: () => T, bucket: string = ""): T {
+		const start = performance.now();
+		const returnValue = codeToMeasure();
+		const duration = performance.now() - start;
+
+		let m = this.measurementsMap.get(bucket);
+		if (m === undefined) {
+			m = { count: 0, duration: -1 };
+			this.measurementsMap.set(bucket, m);
+		}
+		m.count++;
+		m.duration = duration;
+
+		if (this.includeAggregateMetrics) {
+			m.totalDuration = (m.totalDuration ?? 0) + duration;
+			m.minDuration = Math.min(m.minDuration ?? duration, duration);
+			m.maxDuration = Math.max(m.maxDuration ?? 0, duration);
+		}
+
+		if (m.count >= this.sampleThreshold) {
+			this.flushBucket(bucket);
+		}
+
+		return returnValue;
+	}
+
+	private flushBucket(bucket: string): void {
+		const measurements = this.measurementsMap.get(bucket);
+		if (measurements === undefined) {
+			return;
+		}
+
+		if (measurements.count !== 0) {
+			const bucketProperties = this.perBucketProperties.get(bucket);
+
+			const telemetryEvent: ITelemetryPerformanceEvent = {
+				...this.eventBase,
+				...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected
+				...measurements,
+			};
+
+			this.logger.sendPerformanceEvent(telemetryEvent);
+			this.measurementsMap.delete(bucket);
+		}
+	}
+
+	public dispose(error?: Error | undefined): void {
+		for (const [k] of this.measurementsMap.entries()) this.flushBucket(k);
+	}
 }