@fluidframework/telemetry-utils 2.0.0-internal.3.0.0 → 2.0.0-internal.3.1.0

package/src/mockLogger.ts

@@ -11,131 +11,137 @@ import { TelemetryLogger } from "./logger";
  * searching for a set of expected events to match against the logged events.
  */
 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 omitted 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}
+	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 omitted 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}
 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 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">[]): 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.
+	 * 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">[]): 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}
 expected:
 ${JSON.stringify(expectedEvents)}
 
 actual:
 ${JSON.stringify(actualEvents)}`);
-            }
-    }
-
-    /**
-    * 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.
-    * 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">[]): boolean {
-        return expectedEvents.length === this.events.length && this.matchEvents(expectedEvents);
-    }
-
-    /** Asserts that matchEvents is true, and prints the actual/expected output if not */
-    assertMatchStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
-        const actualEvents = this.events;
-        if (!this.matchEventStrict(expectedEvents)) {
-            throw new Error(`${message}
+		}
+	}
+
+	/**
+	 * 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.
+	 * 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">[]): boolean {
+		return expectedEvents.length === this.events.length && this.matchEvents(expectedEvents);
+	}
+
+	/** Asserts that matchEvents is true, and prints the actual/expected output if not */
+	assertMatchStrict(expectedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
+		const actualEvents = this.events;
+		if (!this.matchEventStrict(expectedEvents)) {
+			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) {
-        const actualEvents = this.events;
-        if (this.matchAnyEvent(disallowedEvents)) {
-            throw new Error(`${message}
+		}
+	}
+
+	/** Asserts that matchAnyEvent is false for the given events, and prints the actual/expected output if not */
+	assertMatchNone(disallowedEvents: Omit<ITelemetryBaseEvent, "category">[], message?: string) {
+		const actualEvents = this.events;
+		if (this.matchAnyEvent(disallowedEvents)) {
+			throw new Error(`${message}
 disallowed events:
 ${JSON.stringify(disallowedEvents)}
 
 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);
-    }
+		}
+	}
+
+	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);
+	}
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/telemetry-utils";
-export const pkgVersion = "2.0.0-internal.3.0.0";
+export const pkgVersion = "2.0.0-internal.3.1.0";

package/src/sampledTelemetryHelper.ts

@@ -4,43 +4,43 @@
  */
 
 import {
-    IDisposable,
-    ITelemetryGenericEvent,
-    ITelemetryLogger,
-    ITelemetryPerformanceEvent,
-    ITelemetryProperties,
+	IDisposable,
+	ITelemetryGenericEvent,
+	ITelemetryLogger,
+	ITelemetryPerformanceEvent,
+	ITelemetryProperties,
 } from "@fluidframework/common-definitions";
 import { performance } from "@fluidframework/common-utils";
 
 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 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;
 }
 
 /**
@@ -50,93 +50,93 @@ interface Measurements {
  * 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.
  */
- 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: 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));
+	}
 }

package/src/telemetryTypes.ts

@@ -10,27 +10,27 @@ import { ITelemetryBaseLogger, TelemetryEventCategory } from "@fluidframework/co
  * Includes extra types beyond TelemetryEventPropertyType (which will be deprecated in favor of this one)
  */
 export type TelemetryEventPropertyTypeExt =
-    | string
-    | number
-    | boolean
-    | undefined
-    | (string | number | boolean)[];
+	| string
+	| number
+	| boolean
+	| undefined
+	| (string | number | boolean)[];
 
- /**
-  * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
-  * to mark pieces of information that should be organized or handled differently by loggers in various first or third
-  * party scenarios. For example, tags are used to mark personal information that should not be stored in logs.
-  */
+/**
+ * A property to be logged to telemetry containing both the value and a tag. Tags are generic strings that can be used
+ * to mark pieces of information that should be organized or handled differently by loggers in various first or third
+ * party scenarios. For example, tags are used to mark personal information that should not be stored in logs.
+ */
 export interface ITaggedTelemetryPropertyTypeExt {
-    value: TelemetryEventPropertyTypeExt;
-    tag: string;
+	value: TelemetryEventPropertyTypeExt;
+	tag: string;
 }
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
  */
 export interface ITelemetryPropertiesExt {
-    [index: string]: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt;
+	[index: string]: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt;
 }
 
 /**
@@ -39,18 +39,18 @@ export interface ITelemetryPropertiesExt {
  * @param category - category of the event, like "error", "performance", "generic", etc.
  * @param eventName - name of the event.
  */
- export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
-    category: string;
-    eventName: string;
+export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
+	category: string;
+	eventName: string;
 }
 
 /**
  * Informational (non-error) telemetry event
  * Maps to category = "generic"
  */
- export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
-    eventName: string;
-    category?: TelemetryEventCategory;
+export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
+	eventName: string;
+	category?: TelemetryEventCategory;
 }
 
 /**
@@ -58,7 +58,7 @@ export interface ITelemetryPropertiesExt {
  * Maps to category = "error"
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
-    eventName: string;
+	eventName: string;
 }
 
 /**
@@ -66,7 +66,7 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
  * Maps to category = "performance"
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
-    duration?: number; // Duration of event (optional)
+	duration?: number; // Duration of event (optional)
 }
 
 /**
@@ -75,22 +75,22 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
  * and ITelemetryBaseLogger should be used when loggers are passed between layers.
  */
 export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
-    /**
-     * Send information telemetry event
-     * @param event - Event to send
-     * @param error - optional error object to log
-     */
-    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: any): void;
+	/**
+	 * Send information telemetry event
+	 * @param event - Event to send
+	 * @param error - optional error object to log
+	 */
+	sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: any): void;
 
-    /**
-     * Send error telemetry event
-     * @param event - Event to send
-     */
-    sendErrorEvent(event: ITelemetryErrorEventExt, error?: any): void;
+	/**
+	 * Send error telemetry event
+	 * @param event - Event to send
+	 */
+	sendErrorEvent(event: ITelemetryErrorEventExt, error?: any): void;
 
-    /**
-     * Send performance telemetry event
-     * @param event - Event to send
-     */
-    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: any): void;
+	/**
+	 * Send performance telemetry event
+	 * @param event - Event to send
+	 */
+	sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: any): void;
 }