@fluidframework/telemetry-utils 2.0.0-dev-rc.5.0.0.271717 → 2.0.0-dev-rc.5.0.0.272889

package/src/sampledTelemetryHelper.ts

@@ -6,10 +6,10 @@
 import { performance } from "@fluid-internal/client-utils";
 import type { IDisposable, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
 
-import {
-	type ITelemetryGenericEventExt,
+import type {
+	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
-	type ITelemetryPerformanceEventExt,
+	ITelemetryPerformanceEventExt,
 } from "./telemetryTypes.js";
 
 /**
@@ -58,7 +58,14 @@ interface Measurements {
  * @internal
  */
 export class SampledTelemetryHelper implements IDisposable {
-	disposed: boolean = false;
+	private _disposed: boolean = false;
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IDisposable.disposed}
+	 */
+	public get disposed(): boolean {
+		return this._disposed;
+	}
 
 	private readonly measurementsMap = new Map<string, Measurements>();
 
@@ -145,6 +152,9 @@ export class SampledTelemetryHelper implements IDisposable {
 	}
 
 	public dispose(error?: Error | undefined): void {
-		for (const [k] of this.measurementsMap.entries()) this.flushBucket(k);
+		for (const [k] of this.measurementsMap.entries()) {
+			this.flushBucket(k);
+		}
+		this._disposed = true;
 	}
 }

package/src/telemetryEventBatcher.ts

@@ -3,8 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import { performance } from "@fluid-internal/client-utils";
-
 import { roundToDecimalPlaces } from "./mathTools.js";
 import type {
 	ITelemetryGenericEventExt,
@@ -13,20 +11,10 @@ import type {
 } from "./telemetryTypes.js";
 
 /**
- * Expected type of the custom data passed into the logger.
- * @internal
- */
-export interface IMeasuredCodeResult<TKey extends string> {
-	/**
-	 * Optional properties to log custom data. The set of properties must be the same for all calls to the `measure` function.
-	 */
-	telemetryProperties?: { readonly [key in TKey]: number };
-}
-
-/**
- * Telemetry class that measures the execution time of a given piece of code and accumulates user defined telemetry metrics, to finally log an event through the {@link TelemetryEventBatcher.logger | logger} provided to this class when the number of calls to the {@link TelemetryEventBatcher.measure | measure} function reaches the specified by {@link TelemetryEventBatcher.threshold | threshold}.
+ * Telemetry class that accumulates measurements which are eventually logged in a telemetry event through the provided
+ * {@link TelemetryEventBatcher.logger | logger} when the number of calls to the function reaches the specified {@link TelemetryEventBatcher.threshold | threshold}.
  *
- * @remarks It is expected to be used for a single event type. If the set of `telemetryProperties` is different for different events, a separate `TelemetryEventBatcher` should be created for each event type.
+ * @remarks It is expected to be used for a single event type. If different properties should be logged at different times, a separate `TelemetryEventBatcher` should be created with separate `TMetrics` type.
  * @typeparam TMetrics - The set of keys that should be logged.
  * E.g., `keyof Foo` for logging properties `bar` and `baz` from `type Foo = { bar: number, baz: number }`.
  *
@@ -34,11 +22,6 @@ export interface IMeasuredCodeResult<TKey extends string> {
  * @internal
  */
 export class TelemetryEventBatcher<TMetrics extends string> {
-	/**
-	 * Stores the accumulated duration of the code passed into the logger.
-	 */
-	private accumulatedDuration: number = 0;
-
 	/**
 	 * Stores the sum of the custom data passed into the logger.
 	 */
@@ -71,34 +54,13 @@ export class TelemetryEventBatcher<TMetrics extends string> {
 		private readonly threshold: number,
 	) {}
 
-	/**
-	 * Executes the specified code, keeping statistics of its execution time and the telemetry properties it returns, and when the {@link TelemetryEventBatcher.threshold} is reached it logs a performance event which includes the maxes and averages.
-	 * @param codeToMeasure - The code to be executed and measured.
-	 * @param customData - Custom data to be logged.
-	 *
-	 * @returns Whatever the passed-in code block returns.
-	 */
-	public measure<T extends IMeasuredCodeResult<TMetrics>>(codeToMeasure: () => T): T {
-		const start = performance.now();
-		const returnValue = codeToMeasure();
-		const duration = performance.now() - start;
-
-		this.accumulatedDuration += duration;
-
-		if (returnValue.telemetryProperties) {
-			this.accumulateAndLog(returnValue.telemetryProperties);
-		}
-
-		return returnValue;
-	}
-
 	/**
 	 * Accumulates the custom data and sends it to the logger every {@link TelemetryEventBatcher.threshold} calls.
 	 *
 	 * @param customData -
 	 * A record storing the custom data to be accumulated and eventually logged.
 	 */
-	private accumulateAndLog(customData: Record<TMetrics, number>): void {
+	public accumulateAndLog(customData: Record<TMetrics, number>): void {
 		for (const key of Object.keys(customData) as TMetrics[]) {
 			this.dataSums[key] = (this.dataSums[key] ?? 0) + customData[key];
 			this.dataMaxes[key] = Math.max(
@@ -119,17 +81,15 @@ export class TelemetryEventBatcher<TMetrics extends string> {
 			...this.eventBase,
 		};
 
-		telemetryEvent.duration = this.accumulatedDuration /= this.counter;
-
 		for (const key of Object.keys(this.dataSums) as TMetrics[]) {
 			if (this.dataSums[key] !== undefined) {
-				telemetryEvent[`avg${key}`] = roundToDecimalPlaces(
+				telemetryEvent[`avg_${key}`] = roundToDecimalPlaces(
 					this.dataSums[key]! / this.counter,
 					6,
 				);
 			}
 			if (this.dataMaxes[key] !== undefined) {
-				telemetryEvent[`max${key}`] = this.dataMaxes[key];
+				telemetryEvent[`max_${key}`] = this.dataMaxes[key];
 			}
 		}
 
@@ -137,7 +97,6 @@ export class TelemetryEventBatcher<TMetrics extends string> {
 
 		// Reset the counter and the data.
 		this.counter = 0;
-		this.accumulatedDuration = 0;
 		this.dataSums = {};
 		this.dataMaxes = {};
 	}

package/src/telemetryTypes.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/core-interfaces";
 
 /**
  * The categories FF uses when instrumenting the code.
@@ -31,10 +31,7 @@ export type TelemetryEventPropertyTypeExt =
 	| boolean
 	| undefined
 	| (string | number | boolean)[]
-	| {
-			[key: string]: // Flat objects can have the same properties as the event itself
-			string | number | boolean | undefined | (string | number | boolean)[];
-	  };
+	| Record<string, 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
@@ -53,9 +50,10 @@ export interface ITaggedTelemetryPropertyTypeExt {
  * JSON-serializable properties, which will be logged with telemetry.
  * @alpha
  */
-export interface ITelemetryPropertiesExt {
-	[index: string]: TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>;
-}
+export type ITelemetryPropertiesExt = Record<
+	string,
+	TelemetryEventPropertyTypeExt | Tagged<TelemetryEventPropertyTypeExt>
+>;
 
 /**
  * Interface for logging telemetry statements.
@@ -66,7 +64,14 @@ export interface ITelemetryPropertiesExt {
  * @internal
  */
 export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.category}
+	 */
 	category: string;
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
 }
 
@@ -76,7 +81,15 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
+
+	/**
+	 * Optional event {@link @fluidframework/core-interfaces#ITelemetryBaseEvent.category}.
+	 * @defaultValue "generic"
+	 */
 	category?: TelemetryEventCategory;
 }
 
@@ -86,6 +99,9 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseEvent.eventName}
+	 */
 	eventName: string;
 }
 
@@ -95,7 +111,10 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
  * @alpha
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
-	duration?: number; // Duration of event (optional)
+	/**
+	 * Duration of event (optional)
+	 */
+	duration?: number;
 }
 
 /**
@@ -108,10 +127,10 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
  */
 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.
+	 * Send an information telemetry event.
+	 * @param event - Event to send.
+	 * @param error - Optional error object to log.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.default}.
 	 */
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
@@ -120,17 +139,17 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	): void;
 
 	/**
-	 * Send error telemetry event
-	 * @param event - Event to send
-	 * @param error - optional error object to log
+	 * Send an error telemetry event.
+	 * @param event - Event to send.
+	 * @param error - Optional error object to log.
 	 */
 	sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
 
 	/**
-	 * Send performance telemetry event
+	 * Send a performance telemetry event.
 	 * @param event - Event to send
-	 * @param error - optional error object to log
-	 * @param logLevel - optional level of the log.
+	 * @param error - Optional error object to log.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.default}.
 	 */
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,

package/src/thresholdCounter.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryLoggerExt } from "./telemetryTypes.js";
+import type { ITelemetryLoggerExt } from "./telemetryTypes.js";
 
 /**
  * Utility counter which will send event only if the provided value is above a configured threshold.

package/src/utils.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
 
 import { loggerToMonitoringContext } from "./config.js";
-import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
+import type { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes.js";
 
 /**
  * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.
@@ -104,3 +104,18 @@ export function createSampledLogger(
 
 	return sampledLogger;
 }
+
+/**
+ * Runs the specified function and returns an object with the time it took to run as well as any output from it.
+ * @remarks Useful in conjunction with {@link TelemetryEventBatcher}.
+ *
+ * @param codeToMeasure - The code to be executed and measured.
+ * @returns The total duration of the code execution and whatever the passed-in code block returns.
+ * @internal
+ */
+export function measure<T>(codeToMeasure: () => T): { duration: number; output: T } {
+	const start = performance.now();
+	const output = codeToMeasure();
+	const duration = performance.now() - start;
+	return { duration, output };
+}

package/tsdoc.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+	"extends": ["../../../common/build/build-common/tsdoc-base.json"]
+}