@fluidframework/telemetry-utils 2.0.0-internal.6.1.1 → 2.0.0-internal.6.3.0

package/src/mockLogger.ts

@@ -3,9 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseEvent, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { assert } from "@fluidframework/common-utils";
-import { ITelemetryPropertiesExt } from "./telemetryTypes";
+import {
+	ITelemetryBaseEvent,
+	ITelemetryBaseLogger,
+	LogLevel,
+} from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils";
+import { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes";
 import { createChildLogger } from "./logger";
 
 /**
@@ -15,11 +19,13 @@ import { createChildLogger } from "./logger";
 export class MockLogger implements ITelemetryBaseLogger {
 	events: ITelemetryBaseEvent[] = [];
 
-	clear() {
+	constructor(public readonly minLogLevel?: LogLevel) {}
+
+	clear(): void {
 		this.events = [];
 	}
 
-	toTelemetryLogger() {
+	toTelemetryLogger(): ITelemetryLoggerExt {
 		return createChildLogger({ logger: this });
 	}
 
@@ -48,12 +54,14 @@ export class MockLogger implements ITelemetryBaseLogger {
 		return unmatchedExpectedEventCount === 0;
 	}
 
-	/** Asserts that matchEvents is true, and prints the actual/expected output if not */
+	/**
+	 * 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}
@@ -85,12 +93,14 @@ ${JSON.stringify(actualEvents)}`);
 		return matchedExpectedEventCount > 0;
 	}
 
-	/** Asserts that matchAnyEvent is true, and prints the actual/expected output if not */
+	/**
+	 * 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}
@@ -120,12 +130,14 @@ ${JSON.stringify(actualEvents)}`);
 		);
 	}
 
-	/** Asserts that matchEvents is true, and prints the actual/expected output if not */
+	/**
+	 * 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}
@@ -137,12 +149,14 @@ ${JSON.stringify(actualEvents)}`);
 		}
 	}
 
-	/** Asserts that matchAnyEvent is false for the given events, and prints the actual/expected output if not */
+	/**
+	 * 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}
@@ -159,7 +173,7 @@ ${JSON.stringify(actualEvents)}`);
 		inlineDetailsProp: boolean,
 	): number {
 		let iExpectedEvent = 0;
-		this.events.forEach((event) => {
+		for (const event of this.events) {
 			if (
 				iExpectedEvent < expectedEvents.length &&
 				MockLogger.eventsMatch(event, expectedEvents[iExpectedEvent], inlineDetailsProp)
@@ -167,7 +181,7 @@ ${JSON.stringify(actualEvents)}`);
 				// We found the next expected event; increment
 				++iExpectedEvent;
 			}
-		});
+		}
 
 		// Remove the events so far; next call will just compare subsequent events from here
 		this.events = [];
@@ -191,16 +205,19 @@ ${JSON.stringify(actualEvents)}`);
 		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) {
+function matchObjects(actual: ITelemetryPropertiesExt, expected: ITelemetryPropertiesExt): boolean {
 	for (const [expectedKey, expectedValue] of Object.entries(expected)) {
 		const actualValue = actual[expectedKey];
 		if (

package/src/sampledTelemetryHelper.ts

@@ -9,14 +9,17 @@ import {
 	ITelemetryProperties,
 	IDisposable,
 } from "@fluidframework/core-interfaces";
-import { performance } from "@fluidframework/common-utils";
+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.
 	 */
@@ -45,7 +48,7 @@ interface Measurements {
 
 /**
  * Helper class that executes a specified code block and writes an
- * {@link @fluidframework/common-definitions#ITelemetryPerformanceEvent} to a specified logger every time a specified
+ * {@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.
@@ -82,12 +85,13 @@ export class SampledTelemetryHelper implements IDisposable {
 	) {}
 
 	/**
-	 * @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.
+	 * 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 {
@@ -116,7 +120,7 @@ export class SampledTelemetryHelper implements IDisposable {
 		return returnValue;
 	}
 
-	private flushBucket(bucket: string) {
+	private flushBucket(bucket: string): void {
 		const measurements = this.measurementsMap.get(bucket);
 		if (measurements === undefined) {
 			return;
@@ -137,6 +141,6 @@ export class SampledTelemetryHelper implements IDisposable {
 	}
 
 	public dispose(error?: Error | undefined): void {
-		this.measurementsMap.forEach((_, k) => this.flushBucket(k));
+		for (const [k] of this.measurementsMap.entries()) this.flushBucket(k);
 	}
 }

package/src/telemetryTypes.ts

@@ -3,11 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseLogger, TelemetryEventCategory } from "@fluidframework/core-interfaces";
+import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
+
+/**
+ * The categories FF uses when instrumenting the code.
+ *
+ * generic - Informational log event
+ * error - Error log event, ideally 0 of these are logged during a session
+ * performance - Includes duration, and often has _start, _end, or _cancel suffixes for activity tracking
+ */
+export type TelemetryEventCategory = "generic" | "error" | "performance";
 
 /**
  * Property types that can be logged.
- * Includes extra types beyond TelemetryEventPropertyType (which will be deprecated in favor of this one)
+ * Includes extra types beyond TelemetryBaseEventPropertyType, which must be converted before sending to a base logger
  */
 export type TelemetryEventPropertyTypeExt =
 	| string
@@ -24,6 +33,8 @@ export type TelemetryEventPropertyTypeExt =
  * 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.
+ *
+ * @deprecated Use Tagged<TelemetryEventPropertyTypeExt>
  */
 export interface ITaggedTelemetryPropertyTypeExt {
 	value: TelemetryEventPropertyTypeExt;
@@ -34,7 +45,7 @@ export interface ITaggedTelemetryPropertyTypeExt {
  * JSON-serializable properties, which will be logged with telemetry.
  */
 export interface ITelemetryPropertiesExt {
-	[index: string]: TelemetryEventPropertyTypeExt | ITaggedTelemetryPropertyTypeExt;
+	[index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
 }
 
 /**
@@ -83,18 +94,30 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	 * Send information telemetry event
 	 * @param event - Event to send
 	 * @param error - optional error object to log
+	 * @param logLevel - optional level of the log.
 	 */
-	sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: any): void;
+	sendTelemetryEvent(
+		event: ITelemetryGenericEventExt,
+		error?: unknown,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+	): void;
 
 	/**
 	 * Send error telemetry event
 	 * @param event - Event to send
+	 * @param error - optional error object to log
 	 */
-	sendErrorEvent(event: ITelemetryErrorEventExt, error?: any): void;
+	sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
 
 	/**
 	 * Send performance telemetry event
 	 * @param event - Event to send
+	 * @param error - optional error object to log
+	 * @param logLevel - optional level of the log.
 	 */
-	sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: any): void;
+	sendPerformanceEvent(
+		event: ITelemetryPerformanceEventExt,
+		error?: unknown,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+	): void;
 }

package/src/thresholdCounter.ts

@@ -19,7 +19,7 @@ export class ThresholdCounter {
 	/**
 	 * Sends the value if it's above the treshold.
 	 */
-	public send(eventName: string, value: number) {
+	public send(eventName: string, value: number): void {
 		if (value < this.threshold) {
 			return;
 		}
@@ -36,7 +36,7 @@ export class ThresholdCounter {
 	 * To be used in scenarios where we'd like to record a
 	 * threshold violation while reducing telemetry noise.
 	 */
-	public sendIfMultiple(eventName: string, value: number) {
+	public sendIfMultiple(eventName: string, value: number): void {
 		if (value === this.thresholdMultiple) {
 			this.logger.sendPerformanceEvent({
 				eventName,

package/src/utils.ts

@@ -16,7 +16,7 @@ import {
  * @returns - The outcome of the condition
  */
 export function logIfFalse(
-	condition: any,
+	condition: unknown,
 	logger: ITelemetryBaseLogger,
 	event: string | ITelemetryGenericEvent,
 ): condition is true {